Sdk update (#272)

* Rename get_parameters to get_next_parameter

* annotations add get_next_parameter

* updates

* updates

* updates

* updates

* updates

docs/AnnotationSpec.md

@@ -4,23 +4,26 @@ For good user experience and reduce user effort, we need to design a good annota
 
 If users use NNI system, they only need to:
 
- 1. Annotation variable in code as:
+ 1. Use nni.get_next_parameter() to retrieve hyper parameters from Tuner, before using other annotation, use following annotation at the begining of trial code:
+    '''@nni.get_next_parameter()'''
+
+ 2. Annotation variable in code as:
 
     '''@nni.variable(nni.choice(2,3,5,7),name=self.conv_size)'''
 
- 2. Annotation intermediate in code as:
+ 3. Annotation intermediate in code as:
 
     '''@nni.report_intermediate_result(test_acc)'''
 
- 3. Annotation output in code as:
+ 4. Annotation output in code as:
 
     '''@nni.report_final_result(test_acc)'''
 
- 4. Annotation `function_choice` in code as:
+ 5. Annotation `function_choice` in code as:
 
     '''@nni.function_choice(max_pool(h_conv1, self.pool_size),avg_pool(h_conv1, self.pool_size),name=max_pool)'''
 
-In this way, they can easily realize automatic tuning on NNI. 
+In this way, they can easily implement automatic tuning on NNI. 
 
 For `@nni.variable`, `nni.choice` is the type of search space and there are 10 types to express your search space as follows:
 

docs/howto_1_WriteTrial.md

@@ -27,7 +27,7 @@ Refer to [SearchSpaceSpec.md](SearchSpaceSpec.md) to learn more about search spa
 2.2 Get predefined parameters
     Use the following code snippet: 
 
-        RECEIVED_PARAMS = nni.get_parameters()
+        RECEIVED_PARAMS = nni.get_next_parameter()
 
     to get hyper-parameters' values assigned by tuner. `RECEIVED_PARAMS` is an object, for example: 
 

docs/howto_2_CustomizedTuner.md

@@ -61,7 +61,7 @@ If the you implement the ```generate_parameters``` like this:
         # your code implements here.
         return {"dropout": 0.3, "learning_rate": 0.4}
 ```
-It's means your Tuner will always generate parameters ```{"dropout": 0.3, "learning_rate": 0.4}```. Then Trial will receive ```{"dropout": 0.3, "learning_rate": 0.4}``` this object will using ```nni.get_parameters()``` API from NNI SDK. After training of Trial, it will send result to Tuner by calling ```nni.report_final_result(0.93)```. Then ```receive_trial_result``` will function will receied these parameters like：
+ It means your Tuner will always generate parameters ```{"dropout": 0.3, "learning_rate": 0.4}```. Then Trial will receive ```{"dropout": 0.3, "learning_rate": 0.4}``` by calling API ```nni.get_next_parameter()```. Once the trial ends with a result (normally some kind of metrics), it can send the result to Tuner by calling API ```nni.report_final_result()```, for example ```nni.report_final_result(0.93)```. Then your Tuner's ```receive_trial_result``` function will receied the result like：
 ```
 parameter_id = 82347
 parameters = {"dropout": 0.3, "learning_rate": 0.4}

examples/trials/README.md

@@ -86,7 +86,7 @@ if __name__ == '__main__':
 
 **2)Get configure from Tuner**
 
-User import ```nni``` and use ```nni.get_parameters()``` to recive configure. Please noted **10**, **24** and **25** line in the following code.
+User import ```nni``` and use ```nni.get_next_parameter()``` to recive configure. Please noted **10**, **24** and **25** line in the following code.
 
 
 ```python
@@ -113,7 +113,7 @@ if __name__ == '__main__':
     ARGS, UNKNOWN = PARSER.parse_known_args()
 
     PARAMS = generate_default_params()
-    RECEIVED_PARAMS = nni.get_parameters()
+    RECEIVED_PARAMS = nni.get_next_parameter()
     PARAMS.update(RECEIVED_PARAMS)
     train(ARGS, PARAMS)
 ```
@@ -271,7 +271,7 @@ if __name__ == '__main__':
 
     try:
         # get parameters from tuner
-        RECEIVED_PARAMS = nni.get_parameters()
+        RECEIVED_PARAMS = nni.get_next_parameter()
         LOG.debug(RECEIVED_PARAMS)
         PARAMS = generate_default_params()
         PARAMS.update(RECEIVED_PARAMS)

examples/trials/auto-gbdt/main.py

@@ -97,7 +97,7 @@ if __name__ == '__main__':
 
     try:
         # get parameters from tuner
-        RECEIVED_PARAMS = nni.get_parameters()
+        RECEIVED_PARAMS = nni.get_next_parameter()
         LOG.debug(RECEIVED_PARAMS)
         PARAMS = get_default_parameters()
         PARAMS.update(RECEIVED_PARAMS)

examples/trials/ga_squad/trial.py

@@ -436,7 +436,7 @@ if __name__ == '__main__':
         qp_pairs, dev_qp_pairs = load_data()
         logger.debug('Init finish.')
 
-        original_params = nni.get_parameters()
+        original_params = nni.get_next_parameter()
         '''
         with open('data.json') as f:
             original_params = json.load(f)

examples/trials/mnist-annotation/mnist.py

@@ -229,6 +229,7 @@ def generate_defualt_params():
 
 
 if __name__ == '__main__':
+    '''@nni.get_next_parameter()'''
     try:
         main(generate_defualt_params())
     except Exception as exception:

examples/trials/mnist-batch-tune-keras/mnist-keras.py

@@ -122,7 +122,7 @@ if __name__ == '__main__':
     try:
         # get parameters from tuner
         # RECEIVED_PARAMS = {"optimizer": "Adam", "learning_rate": 0.00001}
-        RECEIVED_PARAMS = nni.get_parameters()
+        RECEIVED_PARAMS = nni.get_next_parameter()
         LOG.debug(RECEIVED_PARAMS)
         PARAMS = generate_default_params()
         PARAMS.update(RECEIVED_PARAMS)

examples/trials/mnist-cascading-search-space/mnist.py

@@ -149,7 +149,7 @@ def parse_init_json(data):
 if __name__ == '__main__':
     try:
         # get parameters form tuner
-        data = nni.get_parameters()
+        data = nni.get_next_parameter()
         logger.debug(data)
 
         RCV_PARAMS = parse_init_json(data)

examples/trials/mnist-keras/mnist-keras.py

@@ -120,7 +120,7 @@ if __name__ == '__main__':
 
     try:
         # get parameters from tuner
-        RECEIVED_PARAMS = nni.get_parameters()
+        RECEIVED_PARAMS = nni.get_next_parameter()
         LOG.debug(RECEIVED_PARAMS)
         PARAMS = generate_default_params()
         PARAMS.update(RECEIVED_PARAMS)

examples/trials/mnist/mnist.py

@@ -219,7 +219,7 @@ def generate_default_params():
 if __name__ == '__main__':
     try:
         # get parameters form tuner
-        RCV_PARAMS = nni.get_parameters()
+        RCV_PARAMS = nni.get_next_parameter()
         logger.debug(RCV_PARAMS)
         # run
         params = generate_default_params()

examples/trials/pytorch_cifar10/main.py

@@ -175,7 +175,7 @@ def test(epoch):
 
 if __name__ == '__main__':
     try:
-        RCV_CONFIG = nni.get_parameters()
+        RCV_CONFIG = nni.get_next_parameter()
         #RCV_CONFIG = {'lr': 0.1, 'optimizer': 'Adam', 'model':'senet18'}
         _logger.debug(RCV_CONFIG)
 

examples/trials/sklearn/classification/main.py

@@ -71,7 +71,7 @@ if __name__ == '__main__':
 
     try:
         # get parameters from tuner
-        RECEIVED_PARAMS = nni.get_parameters()
+        RECEIVED_PARAMS = nni.get_next_parameter()
         LOG.debug(RECEIVED_PARAMS)
         PARAMS = get_default_parameters()
         PARAMS.update(RECEIVED_PARAMS)

examples/trials/sklearn/regression/main.py

@@ -90,7 +90,7 @@ if __name__ == '__main__':
 
     try:
         # get parameters from tuner
-        RECEIVED_PARAMS = nni.get_parameters()
+        RECEIVED_PARAMS = nni.get_next_parameter()
         LOG.debug(RECEIVED_PARAMS)
         PARAMS = get_default_parameters()
         PARAMS.update(RECEIVED_PARAMS)

src/sdk/pynni/nni/platform/local.py

@@ -49,13 +49,18 @@ def request_next_parameter():
     })
     send_metric(metric)
 
-def get_parameters():
+def get_next_parameter():
     global _param_index
     params_file_name = ''
     if _multiphase and (_multiphase == 'true' or _multiphase == 'True'):
         params_file_name = ('parameter_{}.cfg'.format(_param_index), 'parameter.cfg')[_param_index == 0]
     else:
+        if _param_index > 0:
+            return None
+        elif _param_index == 0:
             params_file_name = 'parameter.cfg'
+        else:
+            raise AssertionError('_param_index value ({}) should >=0'.format(_param_index))
     
     params_filepath = os.path.join(_sysdir, params_file_name)
     if not os.path.isfile(params_filepath):

src/sdk/pynni/nni/platform/standalone.py

@@ -22,7 +22,7 @@
 import json_tricks
 
 
-def get_parameters():
+def get_next_parameter():
     pass
 
 def get_sequence_id():

src/sdk/pynni/nni/platform/test.py

@@ -29,7 +29,7 @@ _params = None
 _last_metric = None
 
 
-def get_parameters():
+def get_next_parameter():
     return _params
 
 def send_metric(string):

src/sdk/pynni/nni/smartparam.py

@@ -126,4 +126,4 @@ else:
         if name is None:
             name = '__line{:d}'.format(lineno)
         key = '{}/{}/{}'.format(module, name, func)
-        return trial.get_parameter(key)
+        return trial.get_current_parameter(key)

src/sdk/pynni/nni/trial.py

@@ -26,7 +26,8 @@ from . import platform
 
 
 __all__ = [
-    'get_parameters',
+    'get_next_parameter',
+    'get_current_parameter',
     'report_intermediate_result',
     'report_final_result',
     'get_sequence_id'
@@ -37,15 +38,18 @@ _params = None
 _sequence_id = platform.get_sequence_id()
 
 
-def get_parameters():
+def get_next_parameter():
     """Returns a set of (hyper-)paremeters generated by Tuner."""
     global _params
-    _params = platform.get_parameters()
+    _params = platform.get_next_parameter()
+    if _params is None:
+        return None
     return _params['parameters']
 
-
-def get_parameter(tag):
-    return get_parameters()[tag]
+def get_current_parameter(tag):
+    if _params is None:
+        return None
+    return _params['parameters'][tag]
 
 def get_sequence_id():
     return _sequence_id
@@ -57,7 +61,7 @@ def report_intermediate_result(metric):
     metric: serializable object.
     """
     global _intermediate_seq
-    assert _params is not None, 'nni.get_parameters() needs to be called before report_intermediate_result'
+    assert _params is not None, 'nni.get_next_parameter() needs to be called before report_intermediate_result'
     metric = json_tricks.dumps({
         'parameter_id': _params['parameter_id'],
         'trial_job_id': env_args.trial_job_id,
@@ -73,7 +77,7 @@ def report_final_result(metric):
     """Reports final result to tuner.
     metric: serializable object.
     """
-    assert _params is not None, 'nni.get_parameters() needs to be called before report_final_result'
+    assert _params is not None, 'nni.get_next_parameter() needs to be called before report_final_result'
     metric = json_tricks.dumps({
         'parameter_id': _params['parameter_id'],
         'trial_job_id': env_args.trial_job_id,

src/sdk/pynni/tests/test_trial.py

@@ -32,8 +32,8 @@ class TrialTestCase(TestCase):
         self._trial_params = { 'msg': 'hi', 'x': 123, 'dict': { 'key': 'value', 'y': None } }
         nni.trial._params = { 'parameter_id': 'test_param', 'parameters': self._trial_params }
 
-    def test_get_parameters(self):
-        self.assertEqual(nni.get_parameters(), self._trial_params)
+    def test_get_next_parameter(self):
+        self.assertEqual(nni.get_next_parameter(), self._trial_params)
 
     def test_report_intermediate_result(self):
         nni.report_intermediate_result(123)