Rename instrumentation to parametrization in optimizers init (#497)

.circleci/config.yml

@@ -91,12 +91,18 @@ jobs:
             pip freeze
 
       - run:
-          name: "Run wheel and check files presence"
+          name: "Run wheel and check package"
           when: always
           command: |
             . venv/bin/activate
             python setup.py sdist bdist_wheel
             python -c "from pathlib import Path;files = Path('nevergrad.egg-info/SOURCES.txt').read_text().split(); assert 'LICENSE' in files"
+            python3 -m venv test_wheel
+            . test_wheel/bin/activate
+            cd ..  # don't use nevergrad locally
+            pip install repo/dist/nevergrad-*any.whl
+            python -c "from nevergrad import functions;f = functions.ArtificialFunction(name='sphere', block_dimension=2);f([2, 3])"
+
 
 
   mypy:

CHANGELOG.md

@@ -2,18 +2,29 @@
 
 ## master
 
-- `Candidate` class is removed, and is completely replaced by `Parameter` [#459](https://github.com/facebookresearch/nevergrad/pull/459)
-- New parametrization is now as efficient as in v0.3.0 (see CHANGELOG for v0.3.1 for contect)
+## v0.3.2 (2019-02-05)
+
+
+### Breaking changes (possibly for next version)
+
+- Fist argument of optimizers is renamed to `parametrization` instead of `instrumentation` for consistency [#497](https://github.com/facebookresearch/nevergrad/pull/497). There is currently a deprecation warning, but this will be breaking in v0.4.0.
+- Old `instrumentation` classes now raise deprecation warnings, and will disappear in versions >0.3.2.
+  Hence, prefere using parameters from `ng.p` than `ng.var`, and avoid using `ng.Instrumentation` altogether if
+  you don't need it anymore (or import it through `ng.p.Instrumentation`).
 - `CandidateMaker` (`optimizer.create_candidate`) raises `DeprecationWarning`s since it new candidates/parameters
   can be straightforwardly created (`parameter.spawn_child(new_value=new_value)`)
+- `Candidate` class is completely removed, and is completely replaced by `Parameter` [#459](https://github.com/facebookresearch/nevergrad/pull/459).
+  This should not break existing code since `Parameter` can be straightforwardly used as a `Candidate`.
+
+### Other changes
+
+- New parametrization is now as efficient as in v0.3.0 (see CHANGELOG for v0.3.1 for contect)
 - Optimizers can now hold any parametrization, not just `Instrumentation`. This for instance mean that when you
   do `OptimizerClass(instrumentation=12, budget=100)`, the instrumentation (and therefore the candidates) will be of class
   `ng.p.Array` (and not `ng.p.Instrumentation`), and their attribute `value` will be the corresponding `np.ndarray` value.
   You can still use `args` and `kwargs` if you want, but it's no more needed!
-- Old `instrumentation` classes now raise deprecation warnings, and will disappear in versions >0.3.2.
-  Hence, prefere using parameters from `ng.p` than `ng.var`, and avoid using `ng.Instrumentation` altogether if
-  you don't need it anymore (or import it through `ng.p.Instrumentation`).
-- Added experimental evolution-strategy-like algorithms using new parametrization [#471](https://github.com/facebookresearch/nevergrad/pull/471)
+- Added *experimental* evolution-strategy-like algorithms using new parametrization [#471](https://github.com/facebookresearch/nevergrad/pull/471)
+  (the behavior and API of these optimizers will probably evolve in the near future).
 - `DE` algorithms comply with the new parametrization system and can be set to use parameter's recombination.
 - Fixed array as bounds in `Array` parameters
 

README.md

@@ -16,7 +16,7 @@ pip install git+https://github.com/facebookresearch/nevergrad@master#egg=nevergr
 
 Alternatively, you can clone the repository and run `pip install -e .` from inside the repository folder.
 
-By default, this only installs requirements for the optimization and instrumentation subpackages. If you are also interested in the benchmarking part,
+By default, this only installs requirements for the optimization and parametrization subpackages. If you are also interested in the benchmarking part,
 you should install with the `[benchmark]` flag (example: `pip install nevergrad[benchmark]`), and if you also want the test tools, use
 the `[all]` flag (example: `pip install -e .[all]`).
 
@@ -73,14 +73,14 @@ import nevergrad as ng
 def square(x):
     return sum((x - .5)**2)
 
-optimizer = ng.optimizers.OnePlusOne(instrumentation=2, budget=100)
+optimizer = ng.optimizers.OnePlusOne(parametrization=2, budget=100)
 recommendation = optimizer.minimize(square)
 print(recommendation)  # optimal args and kwargs
 >>> Array{(2,)}[recombination=average,sigma=1.0]:[0.49971112 0.5002944 ]
 ```
 
-`instrumentation=n` is a shortcut to state that the function has only one variable, of dimension `n`,
-See the [instrumentation tutorial](docs/instrumentation.md) for more complex instrumentations.
+`parametrization=n` is a shortcut to state that the function has only one variable, of dimension `n`,
+See the [parametrization tutorial](docs/parametrization.md) for more complex parametrizations.
 
 `recommendation` holds the optimal value(s) found by the for the provided function. It can be
 directly accessed through `recommendation.value` which is here a `np.ndarray` of size 2.

docs/adding_an_algorithm.md

@@ -51,14 +51,10 @@ The key string is either `optimistic` or `pessimistic`, and the `Point` value is
 - `_internal_provide_recommendation`: to provide the final recommendation. By default, the recommendation is the pessimistic best point.
 - `_internal_tell_not_asked` (optional): if the optimizer must handle points differently if they were not asked for, this method must be implemented. If you do not want to support this, you can raise `base.TellNotAskedNotSupportedError`. A unit test will make sure that the optimizer either accepts the point or raises this error.
 
-These functions work with `Candidate` instances, which hold the data point, and `args` and `kwargs` depending on the instrumentation provided at the initialization of the optimizer. Such instances can be conveniently created through the `create_candidate` instance of each optimizer. This object creates `Candidate` object in 3 ways: `opt.create_candidate(args, kwargs, data)`, `opt.create_candidate.from_arguments(*args, **kwargs)` and `opt.create_candidate.from_data(data)`. The last one is probably the one you will need to use inside the `_internal_ask_candidate` method.
-
-
-These functions work with `Candidate` instances, which hold the data point, and `args` and `kwargs` depending on the instrumentation provided at the initialization of the optimizer. Such instances can be conveniently created through the `create_candidate` instance of each optimizer. This object creates `Candidate` object in 3 ways: `opt.create_candidate(args, kwargs, data)`, `opt.create_candidate.from_arguments(*args, **kwargs)` and `opt.create_candidate.from_data(data)`. The last one is probably the one you will need to use inside the `_internal_ask_candidate` method.
-
-
-
-These functions work with `Candidate` instances, which hold the data point, and `args` and `kwargs` depending on the instrumentation provided at the initialization of the optimizer. Such instances can be conveniently created through the `create_candidate` instance of each optimizer. This object creates `Candidate` object in 3 ways: `opt.create_candidate(args, kwargs, data)`, `opt.create_candidate.from_arguments(*args, **kwargs)` and `opt.create_candidate.from_data(data)`. The last one is probably the one you will need to use inside the `_internal_ask_candidate` method.
+These functions work with `Parameter` instances, which hold the parameter(s) `value` (which can also be accessed through `args` and `kwargs`) depending on the parametrization provided at the initialization of the optimizer.
+New instances of `Parameter` can be easily created through the `optimizer.parametrization.spawn_child()`. This way it keeps track of the
+filiation between parameters. The value can then be updated either directly through the `parameter.value` attribute, or by setting
+the value in the "standardized space" (`parameter.set_standardized_data`).
 
 
 
@@ -74,7 +70,7 @@ Seeding has an important part for the significance and reproducibility of the al
 - we should be able to seed from **outside** when we need it: we expect that setting a seed to the global random state should lead to
 reproducible results.
 
-In order to facilitate these behaviors, each instrumentation has a `random_state` attribute (`np.random.RandomState`), which can be seeded by the
+In order to facilitate these behaviors, each parametrization has a `random_state` attribute (`np.random.RandomState`), which can be seeded by the
 user if need be. `optimizer._rng` is a shortcut to access it. All calls to stochastic functions should there be made through it.
 By default, it will be seeded randomly by drawing a number from the global numpy random state so
 that seeding the global numpy random state will yield reproducible results as well

docs/index.rst

@@ -10,13 +10,14 @@ Welcome to nevergrad's documentation!
    :maxdepth: 3
    :caption: Contents:
 
+
    optimization.md
    optimizers.rst
-   instrumentation.md
-   instrumentation_api.rst
+   parametrization.md
+   parametrization_api.rst
    machinelearning.md
-   benchmarking.md
    benchmarks.md
+   benchmarking.md
    adding_an_algorithm.md