diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md index 742bb2f94..c3b3d5e00 100644 --- a/.github/ISSUE_TEMPLATE/enhancement.md +++ b/.github/ISSUE_TEMPLATE/enhancement.md @@ -7,7 +7,7 @@ assignees: '' --- -* estimagic version used, if any: +* optimagic version used, if any: * Python version, if any: * Operating System: diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2290f8e86..f50f0b740 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -29,14 +29,14 @@ jobs: - name: create build environment uses: mamba-org/setup-micromamba@v1 with: - environment-file: ./.envs/testenv-linux.yml + environment-file: ./.tools/envs/testenv-linux.yml cache-environment: true create-args: | python=${{ matrix.python-version }} - name: run pytest shell: bash -l {0} run: | - micromamba activate estimagic + micromamba activate optimagic pytest --cov-report=xml --cov=./ - name: Upload coverage report. if: runner.os == 'Linux' && matrix.python-version == '3.10' @@ -60,19 +60,19 @@ jobs: - name: create build environment uses: mamba-org/setup-micromamba@v1 with: - environment-file: ./.envs/testenv-others.yml + environment-file: ./.tools/envs/testenv-others.yml cache-environment: true create-args: | python=${{ matrix.python-version }} - name: run pytest shell: bash -l {0} run: | - micromamba activate estimagic + micromamba activate optimagic pytest -m "not slow and not jax" run-tests-with-old-pandas: - # This job is only for testing if estimagic works with older pandas versions, as - # many pandas functions we use will be deprecated in pandas 3. estimagic's behavior - # for older verions is handled in src/estimagic/compat.py. + # This job is only for testing if optimagic works with older pandas versions, as + # many pandas functions we use will be deprecated in pandas 3. optimagic's behavior + # for older verions is handled in src/optimagic/compat.py. name: Run tests for ${{ matrix.os}} on ${{ matrix.python-version }} with pandas 1 runs-on: ${{ matrix.os }} strategy: @@ -87,17 +87,15 @@ jobs: - name: create build environment uses: mamba-org/setup-micromamba@v1 with: - environment-file: ./.envs/testenv-pandas.yml + environment-file: ./.tools/envs/testenv-pandas.yml cache-environment: true create-args: | python=${{ matrix.python-version }} - name: run pytest shell: bash -l {0} run: | - micromamba activate estimagic - pytest tests/visualization - pytest tests/parameters - pytest tests/inference + micromamba activate optimagic + pytest -m "not slow and not jax" code-in-docs: name: Run code snippets in documentation runs-on: ubuntu-latest @@ -106,33 +104,34 @@ jobs: - name: create build environment uses: mamba-org/setup-micromamba@v1 with: - environment-file: ./.envs/testenv-linux.yml - environment-name: estimagic - cache-env: true - extra-specs: python=3.12 + environment-file: ./.tools/envs/testenv-linux.yml + environment-name: optimagic + cache-environment: true + create-args: | + python=3.12 - name: run sphinx shell: bash -l {0} run: |- - micromamba activate estimagic + micromamba activate optimagic cd docs/source - python -m doctest -v how_to_guides/optimization/how_to_specify_constraints.md + python -m doctest -v how_to/how_to_constraints.md run-mypy: name: Run mypy runs-on: ubuntu-latest strategy: fail-fast: false steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: create build environment - uses: mamba-org/provision-with-micromamba@main + uses: mamba-org/setup-micromamba@v1 with: - environment-file: ./.envs/testenv-linux.yml - environment-name: estimagic - cache-env: true - extra-specs: | + environment-file: ./.tools/envs/testenv-linux.yml + environment-name: optimagic + cache-environment: true + create-args: | python=3.10 - name: Run mypy shell: bash -l {0} run: |- - micromamba activate estimagic + micromamba activate optimagic mypy diff --git a/.github/workflows/publish-to-pypi.yml b/.github/workflows/publish-to-pypi.yml index c425857c9..7ab6a5f4a 100644 --- a/.github/workflows/publish-to-pypi.yml +++ b/.github/workflows/publish-to-pypi.yml @@ -2,8 +2,8 @@ name: PyPI on: push jobs: - build-n-publish: - name: Build and publish Python 🐍 distributions 📦 to PyPI + build-n-publish-optimagic: + name: Build and publish optimagic Python 🐍 distributions 📦 to PyPI runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -24,6 +24,40 @@ jobs: --sdist --wheel --outdir dist/ + - name: Publish distribution 📦 to PyPI + if: startsWith(github.ref, 'refs/tags') + uses: pypa/gh-action-pypi-publish@release/v1 + with: + password: ${{ secrets.PYPI_API_TOKEN_OPTIMAGIC }} + build-n-publish-estimagic: + name: Build and publish estimagic Python 🐍 distributions 📦 to PyPI + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python 3.10 + uses: actions/setup-python@v5 + with: + python-version: '3.10' + - name: Install pypa/build + run: >- + python -m + pip install + build + toml + --user + - name: Set name entry in pyproject.toml to estimagic + run: >- + python .tools/update_name_pyproject.py + - name: Add FutureWarning to init files + run: >- + python .tools/update_init_files.py + - name: Build a binary wheel and a source tarball + run: >- + python -m + build + --sdist + --wheel + --outdir dist/ - name: Publish distribution 📦 to PyPI if: startsWith(github.ref, 'refs/tags') uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.gitignore b/.gitignore index 500939250..5e1d077ec 100644 --- a/.gitignore +++ b/.gitignore @@ -132,5 +132,6 @@ venv.bak/ src/estimagic/_version.py +src/optimagic/_version.py *.~lock.* diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3b4d70c31..b22b11601 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -9,12 +9,12 @@ repos: rev: 1.16.0 hooks: - id: yamlfix - exclude: tests/optimization/fixtures + exclude: tests/optimagic/optimizers/_pounders/fixtures - repo: local hooks: - id: update-environment-files name: check environment file updates - entry: python .envs/update_envs.py + entry: python .tools/update_envs.py language: python always_run: true require_serial: true @@ -24,7 +24,7 @@ repos: - id: check-added-large-files args: - --maxkb=1300 - exclude: tests/optimization/fixtures/ + exclude: tests/optimagic/optimizers/_pounders/fixtures/ - id: check-case-conflict - id: check-merge-conflict - id: check-vcs-permalinks @@ -48,24 +48,13 @@ repos: - --branch - main - id: trailing-whitespace + exclude: docs/ - id: check-ast - - id: check-docstring-first - exclude: src/estimagic/optimization/algo_options.py - repo: https://github.com/adrienverge/yamllint.git rev: v1.35.1 hooks: - id: yamllint - exclude: tests/optimization/fixtures - - repo: https://github.com/psf/black - rev: 24.8.0 - hooks: - - id: black - language_version: python3.10 - - repo: https://github.com/asottile/blacken-docs - rev: 1.18.0 - hooks: - - id: blacken-docs - exclude: docs/source/how_to_guides/optimization/how_to_specify_constraints.md + exclude: tests/optimagic/optimizers/_pounders/fixtures - repo: https://github.com/PyCQA/docformatter rev: v1.7.5 hooks: @@ -77,23 +66,32 @@ repos: - --wrap-descriptions - '88' - --blank - exclude: src/estimagic/optimization/algo_options.py + exclude: src/optimagic/optimization/algo_options.py - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.5.6 + rev: v0.5.7 hooks: + # Run the linter. - id: ruff - - repo: https://github.com/nbQA-dev/nbQA - rev: 1.8.7 - hooks: - - id: nbqa-black - - id: nbqa-ruff + types_or: + - python + - pyi + - jupyter + args: + - --fix + # Run the formatter. + - id: ruff-format + types_or: + - python + - pyi + - jupyter - repo: https://github.com/executablebooks/mdformat rev: 0.7.17 hooks: - id: mdformat additional_dependencies: - mdformat-gfm - - mdformat-black + - mdformat-gfm-alerts + - mdformat-ruff args: - --wrap - '88' @@ -104,23 +102,36 @@ repos: - id: mdformat additional_dependencies: - mdformat-myst - - mdformat-black + - mdformat-ruff args: - --wrap - '88' files: (docs/.) - - repo: https://github.com/asottile/setup-cfg-fmt - rev: v2.5.0 + - repo: https://github.com/kynan/nbstripout + rev: 0.7.1 hooks: - - id: setup-cfg-fmt - - repo: https://github.com/mgedmin/check-manifest - rev: '0.49' - hooks: - - id: check-manifest + - id: nbstripout + exclude: | + (?x)^( + docs/source/estimagic/tutorials/estimation_tables_overview.ipynb| + docs/source/estimagic/explanation/bootstrap_montecarlo_comparison.ipynb| + )$ args: - - --no-build-isolation + - --drop-empty-cells + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.11.1 + hooks: + - id: mypy + files: src|tests additional_dependencies: - - setuptools-scm - - toml + - numpy<2.0 + - packaging + - pandas-stubs + - sqlalchemy-stubs + - types-cffi + - types-openpyxl + - types-jinja2 + args: + - --config=pyproject.toml ci: autoupdate_schedule: monthly diff --git a/.envs/testenv-linux.yml b/.tools/envs/testenv-linux.yml similarity index 74% rename from .envs/testenv-linux.yml rename to .tools/envs/testenv-linux.yml index 9a9e0cb13..fa5ece402 100644 --- a/.envs/testenv-linux.yml +++ b/.tools/envs/testenv-linux.yml @@ -1,19 +1,19 @@ --- -name: estimagic +name: optimagic channels: - conda-forge - nodefaults dependencies: + - petsc4py - jax - - pygmo + - cyipopt>=1.4.0 # dev, tests + - pygmo>=2.19.0 # dev, tests - nlopt # dev, tests - pip # dev, tests, docs - pytest # dev, tests - pytest-cov # tests - pytest-xdist # dev, tests - statsmodels # dev, tests - - bokeh<=2.4.3 # run, tests - - click # run, tests - cloudpickle # run, tests - joblib # run, tests - numpy<2.0 # run, tests @@ -22,16 +22,19 @@ dependencies: - pybaum >= 0.1.2 # run, tests - scipy>=1.2.1 # run, tests - sqlalchemy # run, tests - - tranquilo>=0.0.4 # dev, tests - seaborn # dev, tests - mypy>=1.11 # dev, tests + - pyyaml # dev, tests + - jinja2 # dev, tests + - annotated-types # dev, tests - pip: # dev, tests, docs - DFO-LS # dev, tests - Py-BOBYQA # dev, tests - fides==0.7.4 # dev, tests - kaleido # dev, tests - - simoptlib==1.0.1 # dev, tests - pandas-stubs # dev, tests - types-cffi # dev, tests - types-openpyxl # dev, tests - - -e ../ + - types-jinja2 # dev, tests + - sqlalchemy-stubs # dev, tests + - -e ../../ diff --git a/.envs/testenv-others.yml b/.tools/envs/testenv-others.yml similarity index 74% rename from .envs/testenv-others.yml rename to .tools/envs/testenv-others.yml index 777062613..4467a19b0 100644 --- a/.envs/testenv-others.yml +++ b/.tools/envs/testenv-others.yml @@ -1,18 +1,17 @@ --- -name: estimagic +name: optimagic channels: - conda-forge - nodefaults dependencies: - - cyipopt<=1.2.0 + - cyipopt>=1.4.0 # dev, tests + - pygmo>=2.19.0 # dev, tests - nlopt # dev, tests - pip # dev, tests, docs - pytest # dev, tests - pytest-cov # tests - pytest-xdist # dev, tests - statsmodels # dev, tests - - bokeh<=2.4.3 # run, tests - - click # run, tests - cloudpickle # run, tests - joblib # run, tests - numpy<2.0 # run, tests @@ -21,16 +20,19 @@ dependencies: - pybaum >= 0.1.2 # run, tests - scipy>=1.2.1 # run, tests - sqlalchemy # run, tests - - tranquilo>=0.0.4 # dev, tests - seaborn # dev, tests - mypy>=1.11 # dev, tests + - pyyaml # dev, tests + - jinja2 # dev, tests + - annotated-types # dev, tests - pip: # dev, tests, docs - DFO-LS # dev, tests - Py-BOBYQA # dev, tests - fides==0.7.4 # dev, tests - kaleido # dev, tests - - simoptlib==1.0.1 # dev, tests - pandas-stubs # dev, tests - types-cffi # dev, tests - types-openpyxl # dev, tests - - -e ../ + - types-jinja2 # dev, tests + - sqlalchemy-stubs # dev, tests + - -e ../../ diff --git a/.envs/testenv-pandas.yml b/.tools/envs/testenv-pandas.yml similarity index 73% rename from .envs/testenv-pandas.yml rename to .tools/envs/testenv-pandas.yml index 588a9146e..757d5f39a 100644 --- a/.envs/testenv-pandas.yml +++ b/.tools/envs/testenv-pandas.yml @@ -1,18 +1,18 @@ --- -name: estimagic +name: optimagic channels: - conda-forge - nodefaults dependencies: - pandas<2.0.0 + - cyipopt>=1.4.0 # dev, tests + - pygmo>=2.19.0 # dev, tests - nlopt # dev, tests - pip # dev, tests, docs - pytest # dev, tests - pytest-cov # tests - pytest-xdist # dev, tests - statsmodels # dev, tests - - bokeh<=2.4.3 # run, tests - - click # run, tests - cloudpickle # run, tests - joblib # run, tests - numpy<2.0 # run, tests @@ -20,15 +20,18 @@ dependencies: - pybaum >= 0.1.2 # run, tests - scipy>=1.2.1 # run, tests - sqlalchemy # run, tests - - tranquilo>=0.0.4 # dev, tests - seaborn # dev, tests - mypy>=1.11 # dev, tests + - pyyaml # dev, tests + - jinja2 # dev, tests + - annotated-types # dev, tests - pip: # dev, tests, docs - DFO-LS # dev, tests - Py-BOBYQA # dev, tests - fides==0.7.4 # dev, tests - kaleido # dev, tests - - simoptlib==1.0.1 # dev, tests - types-cffi # dev, tests - types-openpyxl # dev, tests - - -e ../ + - types-jinja2 # dev, tests + - sqlalchemy-stubs # dev, tests + - -e ../../ diff --git a/.envs/update_envs.py b/.tools/update_envs.py similarity index 84% rename from .envs/update_envs.py rename to .tools/update_envs.py index f0eff0d7a..0c773a5b8 100644 --- a/.envs/update_envs.py +++ b/.tools/update_envs.py @@ -20,19 +20,18 @@ def main(): # create standard testing environments test_env = [line for line in lines if _keep_line(line, "tests")] - test_env.append(" - -e ../") # add local installation + test_env.append(" - -e ../../") # add local installation # find index to insert additional dependencies _insert_idx = [i for i, line in enumerate(lines) if "dependencies:" in line][0] + 1 ## linux test_env_linux = deepcopy(test_env) - test_env_linux.insert(_insert_idx, " - pygmo") test_env_linux.insert(_insert_idx, " - jax") + test_env_linux.insert(_insert_idx, " - petsc4py") ## test environment others test_env_others = deepcopy(test_env) - test_env_others.insert(_insert_idx, " - cyipopt<=1.2.0") ## test environment for pandas version 1 test_env_pandas = deepcopy(test_env) @@ -42,16 +41,17 @@ def main(): # create docs testing environment docs_env = [line for line in lines if _keep_line(line, "docs")] - docs_env.append(" - -e ../") # add local installation + docs_env.append(" - -e ../../") # add local installation # write environments for name, env in zip( ["linux", "others", "pandas"], [test_env_linux, test_env_others, test_env_pandas], + strict=False, ): # Specify newline to avoid wrong line endings on Windows. # See: https://stackoverflow.com/a/69869641 - Path(f".envs/testenv-{name}.yml").write_text( + Path(f".tools/envs/testenv-{name}.yml").write_text( "\n".join(env) + "\n", newline="\n" ) diff --git a/.tools/update_init_files.py b/.tools/update_init_files.py new file mode 100644 index 000000000..72ef1a4c9 --- /dev/null +++ b/.tools/update_init_files.py @@ -0,0 +1,29 @@ +from pathlib import Path + +SRC = Path(__file__).parent.parent.resolve() / "src" + + +to_append = r""" +import warnings +warnings.warn( + "estimagic has been renamed to optimagic. Please uninstall estimagic and install " + "optimagic instead. Don't worry, your estimagic imports will still work if you " + "install optimagic, and simple warnings will help you to adjust them for future " + "releases.\n\n" + "To make these changes using pip, run:\n" + "-------------------------------------\n" + "$ pip uninstall estimagic\n" + "$ pip install optimagic\n\n" + "For conda users, use:\n" + "---------------------\n" + "$ conda remove estimagic\n" + "$ conda install -c conda-forge optimagic\n", + FutureWarning, +) +""" + +for package in ("estimagic", "optimagic"): + init_file = SRC / package / "__init__.py" + current_content = init_file.read_text() + new_content = current_content + to_append + init_file.write_text(new_content) diff --git a/.tools/update_name_pyproject.py b/.tools/update_name_pyproject.py new file mode 100644 index 000000000..ed8909a27 --- /dev/null +++ b/.tools/update_name_pyproject.py @@ -0,0 +1,13 @@ +from pathlib import Path + +import toml + +file_path = Path(__file__).parent.parent.resolve() / "pyproject.toml" + +with file_path.open("r") as f: + config = toml.load(f) + +config["project"]["name"] = "estimagic" + +with file_path.open("w") as f: + toml.dump(config, f) diff --git a/CHANGES.md b/CHANGES.md index 7b6791c54..184c3dc88 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,12 +1,71 @@ # Changes -This is a record of all past estimagic releases and what went into them in reverse +This is a record of all past optimagic releases and what went into them in reverse chronological order. We follow [semantic versioning](https://semver.org/) and all -releases are available on [Anaconda.org](https://anaconda.org/OpenSourceEconomics/estimagic). +releases are available on [Anaconda.org](https://anaconda.org/OpenSourceEconomics/optimagic). Following the [scientific python guidelines](https://scientific-python.org/specs/spec-0000/) -we drop the official support for Python 3.8. - +we drop the official support for Python 3.9. + + +## 0.5.0 + +This is a major release with several breaking changes and deprecations. On a high level, +the major changes are: + +- Implement EP-02: Static typing +- Implement EP-03: Alignment with SciPy +- Rename the package from `estimagic` to `optimagic` (while keeping the `estimagic` + namespace for the estimation capabilities). + + +- {gh}`500` removes the dashboard, the support for simopt optimizers and the + `derivative_plot` ({ghuser}`janosg`) +- {gh}`504` aligns `maximize` and `minimize` more closely with scipy. All related + deprecations and breaking changes are listed below. As a result, scipy code that uses + minimize with the arguments `x0`, `fun`, `jac` and `method` will run without changes + in optimagic. Similarly, to `OptimizeResult` gets some aliases so it behaves more + like SciPy's. + +### Breaking changes + +- When providing a path for the argument `logging` of the functions + `maximize` and `minimize` and the file already exists, the default + behavior is to raise an error now. Replacement or extension + of an existing file must be explicitly configured. +- The argument `if_table_exists` has no effect anymore and a + corresponding warning is raised. + + +### Deprecations + +- The `criterion` argument of `maximize` and `minimize` is renamed to `fun` (as in + SciPy). +- The `derivative` argument of `maximize` and `minimize` is renamed to `jac` (as + in SciPy) +- The `criterion_and_derivative` argument of `maximize` and `minimize` is renamed + to `fun_and_jac` to align it with the other names. +- The `criterion_kwargs` argument of `maximize` and `minimize` is renamed to + `fun_kwargs` to align it with the other names. +- The `derivative_kwargs` argument of `maximize` and `minimize` is renamed to + `jac_kwargs` to align it with the other names. +- The `criterion_and_derivative_kwargs` argument of `maximize` and `minimize` is + renamed to `fun_and_jac_kwargs` to align it with the other names. +- Algorithm specific convergence and stopping criteria are renamed to align them more + with NlOpt and SciPy names. + - `convergence_relative_criterion_tolerance` -> `convergence_ftol_rel` + - `convergence_absolute_criterion_tolerance` -> `convergence_ftol_abs` + - `convergence_relative_params_tolerance` -> `convergence_xtol_rel` + - `convergence_absolute_params_tolerance` -> `convergence_xtol_abs` + - `convergence_relative_gradient_tolerance` -> `convergence_gtol_rel` + - `convergence_absolute_gradient_tolerance` -> `convergence_gtol_abs` + - `convergence_scaled_gradient_tolerance` -> `convergence_gtol_scaled` + - `stopping_max_criterion_evaluations` -> `stopping_maxfun` + - `stopping_max_iterations` -> `stopping_maxiter` +- The `log_options` argument of `minimize` and `maximize` is deprecated, + an according FutureWarning is raised. +- The class `OptimizeLogReader` is deprecated and redirects to + `SQLiteLogReader`. ## 0.4.7 diff --git a/CITATION b/CITATION index ec0ac5ee3..cdc278cbe 100644 --- a/CITATION +++ b/CITATION @@ -4,16 +4,16 @@ x.y) from this installation Text: -[estimagic] estimagic x.y, 2021 -Janos Gabler, http://estimagic.readthedocs.io +[optimagic] optimagic x.y, 2024 +Janos Gabler, https://github.com/OpenSourceEconomics/optimagic BibTeX: -@Unpublished{Gabler2022, - Title = {A Python Tool for the Estimation of large scale scientific models.}, +@Unpublished{Gabler2024, + Title = {optimagic: A library for nonlinear optimization}, Author = {Janos Gabler}, - Year = {2022}, - Url = {https://github.com/OpenSourceEconomics/estimagic} + Year = {2024}, + Url = {https://github.com/OpenSourceEconomics/optimagic} } -If you are unsure about which version of estimagic you are using run: `conda list estimagic`. +If you are unsure about which version of optimagic you are using run: `conda list optimagic`. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c533c1043..190f2aed7 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,6 +1,6 @@ -## Code of Conduct +# Code of Conduct -### Our Pledge +## Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body @@ -12,7 +12,7 @@ and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. -### Our Standards +## Our Standards Examples of behavior that contributes to a positive environment for our community include: @@ -36,7 +36,7 @@ Examples of unacceptable behavior include: * Other conduct which could reasonably be considered inappropriate in a professional setting -### Enforcement Responsibilities +## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in @@ -48,7 +48,7 @@ comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. -### Scope +## Scope This Code of Conduct applies within all community spaces, on all formal and informal events, and also applies when an individual is officially representing @@ -58,7 +58,7 @@ the community in public spaces. Examples of representing our community include - acting as a representative at an online or offline event - acting as a representative surrounding an event -### Enforcement +## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement. You can contact @@ -70,12 +70,12 @@ promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. -### Enforcement Guidelines +## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: -#### 1. Correction +### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. @@ -84,7 +84,7 @@ unprofessional or unwelcome in the community. clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. -#### 2. Warning +### 2. Warning **Community Impact**: A violation through a single incident or series of actions. @@ -96,7 +96,7 @@ includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. -#### 3. Temporary Ban +### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. @@ -107,7 +107,7 @@ private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. -#### 4. Permanent Ban +### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an @@ -116,7 +116,7 @@ individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. -### Attribution +## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index 0a2288858..000000000 --- a/MANIFEST.in +++ /dev/null @@ -1,34 +0,0 @@ -# The MANIFEST.in specifies which files are copied over from a temporary directory to -# site-packages after ``pip install``. Examples can be found here: -# https://www.reddit.com/r/Python/comments/40s8qw/simplify_your_manifestin_commands/ and -# https://blog.ionelmc.ro/presentations/packaging. - -# Test what is included in the package by running ``python setup.py sdist`` and inspect -# the tarball. - -include CITATION -include LICENSE -include CHANGES.md -include CODE_OF_CONDUCT.md - -recursive-include src *.css -recursive-include src *.csv -recursive-include src *.db -recursive-include src *.html -recursive-include src *.py - -exclude *.sh -exclude *.yaml -exclude *.yml -exclude *.pickle -exclude pytask.ini - -prune docs -prune tests -prune .conda -prune .envs - -global-exclude __pycache__ -global-exclude *.py[co] -global-exclude *-checkpoint.ipynb -global-exclude *.ipynb_checkpoints diff --git a/README.md b/README.md index 7ee02556c..af35ebef2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# estimagic +# optimagic [![image](https://img.shields.io/pypi/v/estimagic?color=blue)](https://pypi.org/project/estimagic) [![image](https://img.shields.io/pypi/pyversions/estimagic)](https://pypi.org/project/estimagic) @@ -7,44 +7,26 @@ [![image](https://img.shields.io/pypi/l/estimagic)](https://pypi.org/project/estimagic) [![image](https://readthedocs.org/projects/estimagic/badge/?version=latest)](https://estimagic.readthedocs.io/en/latest) [![image](https://img.shields.io/github/actions/workflow/status/OpenSourceEconomics/estimagic/main.yml?branch=main)](https://github.com/OpenSourceEconomics/estimagic/actions?query=branch%3Amain) -[![image](https://codecov.io/gh/OpenSourceEconomics/estimagic/branch/main/graph/badge.svg)](https://codecov.io/gh/OpenSourceEconomics/estimagic) -[![image](https://results.pre-commit.ci/badge/github/OpenSourceEconomics/estimagic/main.svg)](https://github.com/OpenSourceEconomics/estimagic/actions?query=branch%3Amain) +[![image](https://codecov.io/gh/OpenSourceEconomics/estimagic/branch/main/graph/badge.svg)](https://codecov.io/gh/OpenSourceEconomics/optimagic) +[![image](https://results.pre-commit.ci/badge/github/OpenSourceEconomics/estimagic/main.svg)](https://github.com/OpenSourceEconomics/optimagic/actions?query=branch%3Amain) [![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![image](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) [![image](https://pepy.tech/badge/estimagic/month)](https://pepy.tech/project/estimagic) +[![image](https://img.shields.io/badge/NumFOCUS-affiliated%20project-orange.svg?style=flat&colorA=E1523D&colorB=007D8A)](https://numfocus.org/sponsored-projects/affiliated-projects) +[![image](https://img.shields.io/twitter/follow/aiidateam.svg?style=social&label=Follow)](https://x.com/optimagic) ## Introduction -estimagic is a Python package for nonlinear optimization with or without constraints. It -is particularly suited to solve difficult nonlinear estimation problems. On top, it -provides functionality to perform statistical inference on estimated parameters. +*optimagic* is a Python package for numerical optimization. It is a unified interface to +optimizers from SciPy, NlOpt and many other Python packages. -### Optimization +*optimagic*'s `minimize` function works just like SciPy's, so you don't have to adjust +your code. You simply get more optimizers for free. On top you get powerful diagnostic +tools, parallel numerical derivatives and more. -- estimagic wraps algorithms from *scipy.optimize*, *nlopt*, *pygmo* and more. -- estimagic implements constraints efficiently via reparametrization, so you can solve - constrained problems with any optimizer that supports bounds. -- The parameters of an optimization problem can be arbitrary pytrees -- The complete history of parameters and function evaluations can be saved in a database - for maximum reproducibility. -- Painless and efficient multistart optimization. -- The progress of the optimization is displayed in real time via an interactive - dashboard. - -### Estimation and Inference - -- You can estimate a model using method of simulated moments (MSM), calculate standard - errors and do sensitivity analysis with just one function call. -- Asymptotic standard errors for maximum likelihood estimation. -- estimagic also provides bootstrap confidence intervals and standard errors. Of course - the bootstrap procedures are parallelized. - -### Numerical differentiation - -- estimagic can calculate precise numerical derivatives using - [Richardson extrapolations](https://en.wikipedia.org/wiki/Richardson_extrapolation). -- Function evaluations needed for numerical derivatives can be done in parallel with - pre-implemented or user provided batch evaluators. +*optimagic* was formerly called *estimagic*, because it also provides functionality to +perform statistical inference on estimated parameters. *estimagic* is now a subpackage +of *optimagic*. ## Installation @@ -53,16 +35,16 @@ terminal: ```bash $ conda config --add channels conda-forge -$ conda install estimagic +$ conda install optimagic ``` The first line adds conda-forge to your conda channels. This is necessary for conda to -find all dependencies of estimagic. The second line installs estimagic and its +find all dependencies of optimagic. The second line installs optimagic and its dependencies. ## Installing optional dependencies -Only `scipy` is a mandatory dependency of estimagic. Other algorithms become available +Only `scipy` is a mandatory dependency of optimagic. Other algorithms become available if you install more packages. We make this optional because most of the time you will use at least one additional package, but only very rarely will you need all of them. @@ -91,13 +73,24 @@ The documentation is hosted ([on rtd](https://estimagic.readthedocs.io/en/latest ## Citation -If you use Estimagic for your research, please do not forget to cite it. +If you use optimagic for your research, please do not forget to cite it. ``` -@Unpublished{Gabler2022, - Title = {A Python Tool for the Estimation of large scale scientific models.}, +@Unpublished{Gabler2024, + Title = {optimagic: A library for nonlinear optimization}, Author = {Janos Gabler}, Year = {2022}, - Url = {https://github.com/OpenSourceEconomics/estimagic} + Url = {https://github.com/OpenSourceEconomics/optimagic} } ``` + +## Acknowledgements + +We thank all institutions that have funded or supported optimagic (formerly estimagic) + + + + + + + diff --git a/codecov.yml b/codecov.yml index e8f2c20b2..bd9681c15 100644 --- a/codecov.yml +++ b/codecov.yml @@ -9,20 +9,14 @@ coverage: status: patch: default: - target: 30% + target: 80% project: default: target: 90% ignore: - - .tox/**/* - - release.py - setup.py - - estimagic/tests/**/* - - src/estimagic/benchmarking/cartis_roberts.py - - src/estimagic/optimization/subsolvers/bntr_fast.py - - src/estimagic/optimization/subsolvers/_trsbox_fast.py - - src/estimagic/optimization/subsolvers/_conjugate_gradient_fast.py - - src/estimagic/optimization/subsolvers/_steihaug_toint_fast.py - - src/estimagic/optimization/subsolvers/gqtpar_fast.py - - src/estimagic/optimization/tranquilo/clustering.py - - tests/optimization/test_tao_optimizers.py + # Uses numba + - src/optimagic/benchmarking/cartis_roberts.py + # not installed on CI + - src/optimagic/optimizers/tranquilo.py + - tests/**/* diff --git a/docs/Makefile b/docs/Makefile index c06ae6a84..06269366b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,7 +4,7 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -SPHINXPROJ = estimagic +SPHINXPROJ = optimagic SOURCEDIR = source BUILDDIR = build diff --git a/docs/make.bat b/docs/make.bat index ab7496625..731270bc7 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -9,7 +9,7 @@ if "%SPHINXBUILD%" == "" ( ) set SOURCEDIR=source set BUILDDIR=build -set SPHINXPROJ=estimagic +set SPHINXPROJ=optimagic if "%1" == "" goto help diff --git a/docs/rtd_environment.yml b/docs/rtd_environment.yml index 3f990e869..8407ede25 100644 --- a/docs/rtd_environment.yml +++ b/docs/rtd_environment.yml @@ -1,14 +1,14 @@ --- -name: estimagic-docs +name: optimagic-docs channels: - conda-forge - nodefaults dependencies: - python=3.10 + - typing-extensions - pip - setuptools_scm - toml - - black - sphinx - sphinxcontrib-bibtex - sphinx-copybutton @@ -27,8 +27,14 @@ dependencies: - patsy - joblib - plotly + - annotated-types - pip: - ../ - kaleido - Py-BOBYQA - DFO-LS + - pandas-stubs # dev, tests + - types-cffi # dev, tests + - types-openpyxl # dev, tests + - types-jinja2 # dev, tests + - sqlalchemy-stubs # dev, tests diff --git a/docs/scripts/task_generate_optimizer_illustration_gifs.py b/docs/scripts/task_generate_optimizer_illustration_gifs.py deleted file mode 100644 index de0635e63..000000000 --- a/docs/scripts/task_generate_optimizer_illustration_gifs.py +++ /dev/null @@ -1,411 +0,0 @@ -from pathlib import Path - -import gif -import matplotlib.pyplot as plt -import numpy as np -import pandas as pd -import pytask -import seaborn as sns -import statsmodels.formula.api as sm -from scipy.optimize import minimize - -gif.options.matplotlib["dpi"] = 200 - -OUT = Path(__file__).resolve().parent.parent / "source" / "_static" / "images" - - -# ====================================================================================== -# Define example function -# ====================================================================================== - -WEIGHTS = [ - 9.003014962148157, - -3.383000146393776, - -0.6037887934635748, - 1.6984454347036886, - -0.9447426232680957, - 0.2669069434366247, - -0.04446368897497234, - 0.00460781796708519, - -0.0003000790127508276, - 1.1934114174145725e-05, - -2.6471293419570505e-07, - 2.5090819960943964e-09, -] - - -def example_criterion(x): - x = _unpack_x(x) - exponents = np.arange(len(WEIGHTS)) - return WEIGHTS @ x**exponents - - -def example_gradient(x): - x = _unpack_x(x) - exponents = np.arange(len(WEIGHTS)) - return (WEIGHTS * exponents) @ x ** (exponents - 1).clip(0) - - -def example_hessian(x): - x = _unpack_x(x) - exponents = np.arange(len(WEIGHTS)) - return (WEIGHTS * exponents * (exponents - 1)) @ x ** (exponents - 2).clip(0) - - -def _unpack_x(x): - if hasattr(x, "__len__"): - assert len(x) == 1 - - if isinstance(x, pd.DataFrame): - res = x["value"].to_numpy()[0] - elif isinstance(x, pd.Series): - res = x.to_numpy()[0] - elif isinstance(x, (np.ndarray, list, tuple)): - res = x[0] - else: - res = float(x) - return res - - -# ====================================================================================== -# Define tools -# ====================================================================================== - - -def minimize_with_history(fun, x0, method, jac=None, hess=None): - """Dumbed down scipy minimize that returns full history. - - This is really only meant for illustration in this notebook. In particular, - the following restrictions apply: - - - Only works for 1 dimensional problems - - does not support all arguments - - """ - history = [] - - def wrapped_fun(x, history=history): - history.append(_unpack_x(x)) - return fun(x) - - res = minimize(wrapped_fun, x0, method=method, jac=jac, hess=hess) - res.history = history - return res - - -def plot_function(): - x_grid = np.linspace(0, 20, 100) - y_grid = [example_criterion(x) for x in x_grid] - fig, ax = plt.subplots() - sns.lineplot(x=x_grid, y=y_grid, ax=ax) - sns.despine() - return fig, ax - - -# ====================================================================================== -# Define self explaining stylized optimizers -# ====================================================================================== - - -def _generate_stylized_line_search_data(): - remarks = [ - "Initial evaluation: Large gradient, low curvature: Make a big step.", - "Iteration 1: Large gradient, large curvature: Make a smaller step.", - "Iteration 2: Very small gradient, low curvature: Make a very small step.", - "Iteration 3: Very small gradient, low curvature: Make a very small step.", - "Iteration 4: Medium-sized gradient, low curvature: Make a larger step again.", - "Iteration 5: Medium-sized gradient, larger curvature: Make a small step.", - "Iteration 6: Reverse direction due to sign switch in gradient ", - "Convergence because gradient is approximately zero", - ] - - x = 2 - data = [] - for remark in remarks: - f_val = example_criterion(x) - grad_val = example_gradient(x) - hess_val = np.clip(example_hessian(x), 0.1, np.inf) - base_step = -1 / hess_val * grad_val - - aux_line = { - "x": [x - 2, x, x + 2], - "y": [f_val - 2 * grad_val, f_val, f_val + 2 * grad_val], - } - - new_value = np.inf - evaluated_x = [x] - evaluated_y = [f_val] - alpha = 1 - while new_value >= f_val: - new_x = x + alpha * base_step - new_value = example_criterion(new_x) - evaluated_x.append(new_x) - evaluated_y.append(new_value) - - iteration_data = { - "evaluated_x": evaluated_x, - "new_x": new_x, - "remark": remark, - "aux_line": aux_line, - } - - data.append(iteration_data) - x = new_x - return data - - -def _generate_stylized_direct_search_data(): - remarks = [ - ( - "Initial evaluation: candidate value worse than original value. " - "Do not accept candidate value, switch direction." - ), - ( - "Iteration 1: candidate value better than original value. " - "Accept candidate value, increase step length." - ), - ( - "Iteration 2: candidate value better than original value. " - "Accept candidate value, increase step length." - ), - ( - "Iteration 3: candidate value worse than original value. " - "Do not accept new point, make step smaller." - ), - ( - "Iteration 4: Will eventually converge around here. " - "From iteration 3 we know that we will do worse further right." - ), - ] - - data = [] - x = 2 - for i, remark in enumerate(remarks): - if i == 0: - other = x - 2 - elif i <= 3: - other = x + i + 1 - else: - other = x + 2 - - evaluated_x = [x, other] - evaluated_y = [example_criterion(x), example_criterion(other)] - argmin_index = np.argmin(evaluated_y) - new_x = evaluated_x[argmin_index] - - iteration_data = { - "evaluated_x": [x, other], - "new_x": new_x, - "remark": remark, - } - data.append(iteration_data) - x = new_x - - return data - - -def _generate_stylized_gradient_based_trust_region_data(): - remarks = [ - "Actual vs. expected improvement is large. Accept point, increase radius", - "Actual vs. expected improvement < 1 but large. Accept point, increase radius.", - "Actual vs. expected improvement is negative. Reject point, decrease radius.", - "Actual vs. expected improvement is around 1. Accept point, increase radius.", - "Actual vs. expected improvement is around 1. Accept point, increase radius.", - "Convergence because gradient norm is close to zero.", - ] - - data = [] - x = 2 - radius = 2 - for i, remark in enumerate(remarks): - if i == 0: - pass - elif i <= 2: - radius += 1 - elif i == 3: - radius = 2 - else: - radius += 1 - - aux_x = list(np.linspace(x - radius, x + radius, 50)) - aux_y = [_taylor_expansion(point, x) for point in aux_x] - - new_x = aux_x[np.argmin(aux_y)] - - iteration_data = { - "evaluated_x": [x], - "new_x": new_x, - "remark": remark, - "aux_line": {"x": aux_x, "y": aux_y}, - } - - data.append(iteration_data) - x = new_x - - return data - - -def _generate_stylized_gradient_free_trust_region_data(): - remarks = [ - "Actual vs. expected improvement is large. Accept point, increase radius.", - "Actual vs. expected improvement is large. Accept point, increase radius.", - ( - "Actual vs. expected improvement is large but step length is small. " - "Accept point, decrease radius." - ), - ( - "Actual vs. expected improvement is reasonable but step length is small. " - "Accept point, decrease radius." - ), - ( - "Actual vs. expected improvement large but absolute improvement is small. " - "Accept new point but decrease radius" - ), - "Absolute improvement is small. Accept new point but decrease radius.", - "Convergence because trust region radius shrinks to zero.", - ] - - data = [] - x = 2 - radius = 2 - for i, remark in enumerate(remarks): - if i == 0: - pass - elif i <= 2: - radius += 1 - else: - radius = max(0.1, radius - 1) - - aux_x = list(np.linspace(x - radius, x + radius, 50)) - aux_y = [_regression_surrogate(point, x, radius) for point in aux_x] - - new_x = aux_x[np.argmin(aux_y)] - - iteration_data = { - "evaluated_x": [x], - "new_x": new_x, - "remark": remark, - "aux_line": {"x": aux_x, "y": aux_y}, - } - - data.append(iteration_data) - x = new_x - - return data - - -def _taylor_expansion(x, x0): - """Evaluate taylor expansion around x0 at x.""" - x = _unpack_x(x) - x0 = _unpack_x(x0) - f = example_criterion(x0) - f_prime = example_gradient(x0) - f_double_prime = example_hessian(x0) - - diff = x - x0 - res = f + f_prime * diff + f_double_prime * 0.5 * diff**2 - return res - - -def _regression_surrogate(x, x0, radius): - """Evaluate a regression based surrogate model at x. - - x0 and radius define the trust region in which evaluation points are sampled. - - """ - x = _unpack_x(x) - x0 = _unpack_x(x0) - deviations = [-radius, 0, radius] - - evaluations = [example_criterion(x0 + deviation) for deviation in deviations] - df = pd.DataFrame() - df["x"] = deviations - df["y"] = evaluations - params = sm.ols(formula="y ~ x + I(x**2)", data=df).fit().params - vec = np.array([1, (x - x0), (x - x0) ** 2]) - return params @ vec - - -# ====================================================================================== -# Make convergence gifs -# ====================================================================================== - -algorithms = ["Cobyla", "L-BFGS-B", "Nelder-Mead", "trust-ncg"] - -PARMETRIZATON = [(OUT / f"history_{algo.lower()}.gif", algo) for algo in algorithms] - - -@pytask.mark.parametrize("produces, algorithm", PARMETRIZATON) -def task_create_convergence_gif(produces, algorithm): - start_x = np.array([2]) - hessian = example_hessian if algorithm == "trust-ncg" else NotImplementedError - res = minimize_with_history( - example_criterion, start_x, method=algorithm, jac=example_gradient, hess=hessian - ) - - # repeat the last point to show it longer in the gif - points = res.history + [res.history[-1]] * 2 - - @gif.frame - def _plot_history(points): - fig, ax = plot_function() - sns.rugplot(points, ax=ax) - plt.plot( - points[-1], - example_criterion(points[-1]), - marker="*", - ) - sns.despine() - - frames = [_plot_history[: i + 1] for i in range(len(points))] - - gif.save(frames, produces, duration=2.5, unit="s") - - -# ====================================================================================== -# Make explanation gifs -# ====================================================================================== -STYLIZED_ALGORITHMS = { - "direct_search": _generate_stylized_direct_search_data, - "line_search": _generate_stylized_line_search_data, - "gradient_based_trust_region": _generate_stylized_gradient_based_trust_region_data, - "gradient_free_trust_region": _generate_stylized_gradient_free_trust_region_data, -} - -PARMETRIZATON = [(OUT / f"stylized_{algo}.gif", algo) for algo in STYLIZED_ALGORITHMS] - - -@pytask.mark.parametrize("produces, algorithm", PARMETRIZATON) -def task_create_stylized_algo_gif(produces, algorithm): - plot_data = STYLIZED_ALGORITHMS[algorithm]() - # repeat the last point to show it longer in the gif - plot_data = plot_data + [plot_data[-1]] * 2 - - @gif.frame - def visualize_step(evaluated_x, new_x, aux_line=None, remark=None): - fig, ax = plot_function() - sns.rugplot(x=evaluated_x) - ax.plot([new_x], [example_criterion(new_x)], marker="*") - if aux_line is not None: - sns.lineplot(x=aux_line["x"], y=aux_line["y"]) - if remark is not None: - plt.subplots_adjust(bottom=0.25) - plt.figtext( - 0.5, - 0.05, - remark, - multialignment="center", - ha="center", - wrap=True, - fontsize=14, - bbox={ - "facecolor": "white", - "alpha": 0.5, - "pad": 5, - "edgecolor": "#ffffff00", - }, - ) - - frames = [visualize_step(**data) for data in plot_data] - - gif.save(frames, produces, duration=7.5, unit="s") diff --git a/docs/source/_static/images/aai-institute-logo.svg b/docs/source/_static/images/aai-institute-logo.svg new file mode 100644 index 000000000..28e18f40a --- /dev/null +++ b/docs/source/_static/images/aai-institute-logo.svg @@ -0,0 +1 @@ + diff --git a/docs/source/_static/images/history_trust-ncg.gif b/docs/source/_static/images/history_trust-ncg.gif index e69de29bb..5119ccfc9 100644 Binary files a/docs/source/_static/images/history_trust-ncg.gif and b/docs/source/_static/images/history_trust-ncg.gif differ diff --git a/docs/source/_static/images/hoover_logo.png b/docs/source/_static/images/hoover_logo.png new file mode 100644 index 000000000..a37719896 Binary files /dev/null and b/docs/source/_static/images/hoover_logo.png differ diff --git a/docs/source/_static/images/numfocus_logo.png b/docs/source/_static/images/numfocus_logo.png new file mode 100644 index 000000000..a1daebf57 Binary files /dev/null and b/docs/source/_static/images/numfocus_logo.png differ diff --git a/docs/source/_static/images/optimagic_logo.svg b/docs/source/_static/images/optimagic_logo.svg new file mode 100644 index 000000000..1e83bcbf4 --- /dev/null +++ b/docs/source/_static/images/optimagic_logo.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/_static/images/optimagic_logo_dark_mode.svg b/docs/source/_static/images/optimagic_logo_dark_mode.svg new file mode 100644 index 000000000..93f55c402 --- /dev/null +++ b/docs/source/_static/images/optimagic_logo_dark_mode.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/_static/images/transferlab-logo.svg b/docs/source/_static/images/transferlab-logo.svg new file mode 100644 index 000000000..b987a9b48 --- /dev/null +++ b/docs/source/_static/images/transferlab-logo.svg @@ -0,0 +1 @@ + diff --git a/docs/source/algorithms.md b/docs/source/algorithms.md index 939aa1890..363ce5faf 100644 --- a/docs/source/algorithms.md +++ b/docs/source/algorithms.md @@ -2,15 +2,15 @@ # Optimizers -Check out {ref}`algorithms` to see how to select an algorithm and specify `algo_options` -when using `maximize` or `minimize`. +Check out {ref}`how-to-select-algorithms` to see how to select an algorithm and specify +`algo_options` when using `maximize` or `minimize`. ## Optimizers from scipy (scipy-algorithms)= -estimagic supports most `scipy` algorithms and scipy is automatically installed when you -install estimagic. +optimagic supports most `scipy` algorithms and scipy is automatically installed when you +install optimagic. ```{eval-rst} .. dropdown:: scipy_lbfgsb @@ -43,7 +43,7 @@ install estimagic. The lbfgsb algorithm is almost perfectly scale invariant. Thus, it is not necessary to scale the parameters. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative improvement + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. More formally, this is expressed as .. math:: @@ -52,11 +52,11 @@ install estimagic. \text{relative_criterion_tolerance} - - **convergence.absolute_gradient_tolerance** (float): Stop if all elements of the projected + - **convergence.gtol_abs** (float): Stop if all elements of the projected gradient are smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. - **limited_memory_storage_length** (int): Maximum number of saved gradients used to approximate the hessian matrix. @@ -80,11 +80,11 @@ install estimagic. originally implemented by :cite:`Kraft1988`. .. note:: - SLSQP's general nonlinear constraints are not supported yet by estimagic. + SLSQP's general nonlinear constraints are not supported yet by optimagic. - - **convergence.absolute_criterion_tolerance** (float): Precision goal for the value of + - **convergence.ftol_abs** (float): Precision goal for the value of f in the stopping criterion. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. ``` @@ -109,19 +109,19 @@ install estimagic. Its popularity is likely due to historic reasons and much larger than its properties warrant. - The argument `initial_simplex` is not supported by estimagic as it is not - compatible with estimagic's handling of constraints. + The argument `initial_simplex` is not supported by optimagic as it is not + compatible with optimagic's handling of constraints. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, the optimization stops, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function evaluation is reached, + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - - **convergence.absolute_params_tolerance** (float): Absolute difference in parameters between iterations + - **convergence.xtol_abs** (float): Absolute difference in parameters between iterations that is tolerated to declare convergence. As no relative tolerances can be passed to Nelder-Mead, - estimagic sets a non zero default for this. - - **convergence.absolute_criterion_tolerance** (float): Absolute difference in the criterion value between + optimagic sets a non zero default for this. + - **convergence.ftol_abs** (float): Absolute difference in the criterion value between iterations that is tolerated to declare convergence. As no relative tolerances can be passed to Nelder-Mead, - estimagic sets a non zero default for this. + optimagic sets a non zero default for this. - **adaptive** (bool): Adapt algorithm parameters to dimensionality of problem. Useful for high-dimensional minimization (:cite:`Gao2012`, p. 259-277). scipy's default is False. @@ -148,12 +148,12 @@ install estimagic. bi-directional search in each parameter's dimension. The argument ``direc``, which is the initial set of direction vectors and which - is part of the scipy interface is not supported by estimagic because it is - incompatible with how estimagic handles constraints. + is part of the scipy interface is not supported by optimagic because it is + incompatible with how optimagic handles constraints. - - **convergence.relative_params_tolerance (float)**: Stop when the relative movement between parameter + - **convergence.xtol_rel (float)**: Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative improvement between two + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. More formally, this is expressed as .. math:: @@ -161,9 +161,9 @@ install estimagic. \frac{(f^k - f^{k+1})}{\\max{{\{|f^k|, |f^{k+1}|, 1\}}}} \leq \text{relative_criterion_tolerance} - - **stopping.max_criterion_evaluations** (int): If the maximum number of function evaluation is reached, + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count thisas convergence. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, the optimization stops, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. ``` @@ -184,8 +184,8 @@ install estimagic. expansion near an optimum. However, BFGS can have acceptable performance even for non-smooth optimization instances. - - **convergence.absolute_gradient_tolerance** (float): Stop if all elements of the gradient are smaller than this. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, the optimization stops, + - **convergence.gtol_abs** (float): Stop if all elements of the gradient are smaller than this. + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. - **norm** (float): Order of the vector norm that is used to calculate the gradient's "score" that is compared to the gradient tolerance to determine convergence. Default is infinite which means that @@ -217,9 +217,9 @@ install estimagic. - the gradient is not too large, e.g., has a norm less than 1000. - The initial guess is reasonably close to the criterion's global minimizer. - - **convergence.absolute_gradient_tolerance** (float): Stop if all elements of the + - **convergence.gtol_abs** (float): Stop if all elements of the gradient are smaller than this. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. - **norm** (float): Order of the vector norm that is used to calculate the gradient's "score" that is compared to the gradient tolerance to determine convergence. @@ -266,10 +266,10 @@ install estimagic. - the gradient is not too large, e.g., has a norm less than 1000. - The initial guess is reasonably close to the criterion's global minimizer. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. Newton CG uses the average relative change in the parameters for determining the convergence. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. @@ -289,16 +289,16 @@ install estimagic. It is derivative-free and supports nonlinear inequality and equality constraints. .. note:: - Cobyla's general nonlinear constraints is not supported yet by estimagic. + Cobyla's general nonlinear constraints is not supported yet by optimagic. Scipy's implementation wraps the FORTRAN implementation of the algorithm. For more information on COBYLA see :cite:`Powell1994`, :cite:`Powell1998` and :cite:`Powell2007`. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. In case of COBYLA this is a lower bound on the size of the trust region and can be seen as the required accuracy in the variables but this accuracy is not guaranteed. @@ -339,25 +339,25 @@ install estimagic. - the gradient is not too large, e.g., has a norm less than 1000. - The initial guess is reasonably close to the criterion's global minimizer. - estimagic does not support the ``scale`` nor ``offset`` argument as they are not - compatible with the way estimagic handles constraints. It also does not support + optimagic does not support the ``scale`` nor ``offset`` argument as they are not + compatible with the way optimagic handles constraints. It also does not support ``messg_num`` which is an additional way to control the verbosity of the optimizer. - **func_min_estimate** (float): Minimum function value estimate. Defaults to 0. - stopping_max_iterations (int): If the maximum number of iterations is reached, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - - **convergence.absolute_params_tolerance** (float): Absolute difference in parameters + - **convergence.xtol_abs** (float): Absolute difference in parameters between iterations after scaling that is tolerated to declare convergence. - - **convergence.absolute_criterion_tolerance** (float): Absolute difference in the + - **convergence.ftol_abs** (float): Absolute difference in the criterion value between iterations after scaling that is tolerated to declare convergence. - - **convergence.absolute_gradient_tolerance** (float): Stop if the value of the + - **convergence.gtol_abs** (float): Stop if the value of the projected gradient (after applying x scaling factors) is smaller than this. - If convergence.absolute_gradient_tolerance < 0.0, - convergence.absolute_gradient_tolerance is set to + If convergence.gtol_abs < 0.0, + convergence.gtol_abs is set to 1e-2 * sqrt(accuracy). - **max_hess_evaluations_per_iteration** (int): Maximum number of hessian*vector evaluations per main iteration. If ``max_hess_evaluations == 0``, the @@ -368,13 +368,13 @@ install estimagic. It may be increased during the optimization. If too small, it will be set to 10.0. By default we use scipy's default. - **line_search_severity** (float): Severity of the line search. If < 0 or > 1, - set to 0.25. Estimagic defaults to scipy's default. + set to 0.25. optimagic defaults to scipy's default. - **finitie_difference_precision** (float): Relative precision for finite difference calculations. If <= machine_precision, set to sqrt(machine_precision). - Estimagic defaults to scipy's default. + optimagic defaults to scipy's default. - **criterion_rescale_factor** (float): Scaling factor (in log10) used to trigger criterion rescaling. If 0, rescale at each iteration. If a large value, - never rescale. If < 0, rescale is set to 1.3. Estimagic defaults to scipy's + never rescale. If < 0, rescale is set to 1.3. optimagic defaults to scipy's default. @@ -396,7 +396,7 @@ install estimagic. with another local optimizer. .. note:: - Its general nonlinear constraints' handling is not supported yet by estimagic. + Its general nonlinear constraints' handling is not supported yet by optimagic. It switches between two implementations depending on the problem definition. It is the most versatile constrained minimization algorithm @@ -415,19 +415,19 @@ install estimagic. It approximates the Hessian using the Broyden-Fletcher-Goldfarb-Shanno (BFGS) Hessian update strategy. - - **convergence.absolute_gradient_tolerance** (float): Tolerance for termination + - **convergence.gtol_abs** (float): Tolerance for termination by the norm of the Lagrangian gradient. The algorithm will terminate when both the infinity norm (i.e., max abs value) of the Lagrangian gradient and the constraint violation are smaller than the - convergence.absolute_gradient_tolerance. + convergence.gtol_abs. For this algorithm we use scipy's gradient tolerance for trust_constr. This smaller tolerance is needed for the sum of squares tests to pass. - - **stopping.max_iterations** (int): If the maximum number of iterations is reached, + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as convergence. - - **convergence.relative_params_tolerance** (float): Tolerance for termination by + - **convergence.xtol_rel** (float): Tolerance for termination by the change of the independent variable. The algorithm will terminate when the radius of the trust region used in the algorithm is smaller than the - convergence.relative_params_tolerance. + convergence.xtol_rel. - **trustregion.initial_radius** (float): Initial value of the trust region radius. The trust radius gives the maximum distance between solution points in consecutive iterations. It reflects the trust the algorithm puts in the @@ -453,11 +453,11 @@ install estimagic. The algorithm supports the following options: - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is below this. - - **convergence.relative_gradient_tolerance** (float): Stop when the gradient, + - **convergence.gtol_rel** (float): Stop when the gradient, divided by the absolute value of the criterion function is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - **tr_solver** (str): Method for solving trust-region subproblems, relevant only @@ -495,11 +495,11 @@ install estimagic. The algorithm supports the following options: - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is below this. - - **convergence.relative_gradient_tolerance** (float): Stop when the gradient, + - **convergence.gtol_rel** (float): Stop when the gradient, divided by the absolute value of the criterion function is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - **tr_solver** (str): Method for solving trust-region subproblems, relevant only @@ -537,11 +537,11 @@ install estimagic. The algorithm supports the following options: - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is below this. - - **convergence.relative_gradient_tolerance** (float): Stop when the gradient, + - **convergence.gtol_rel** (float): Stop when the gradient, divided by the absolute value of the criterion function is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - **tr_solver** (str): Method for solving trust-region subproblems, relevant only @@ -576,9 +576,9 @@ install estimagic. Basin-hopping is a two-phase method that combines a global stepping algorithm with local minimization at each step. Designed to mimic the natural process of energy minimization of clusters of atoms, it works well for similar problems with “funnel-like, but rugged” energy landscapes. - This is mainly supported for completeness. Consider estimagic's built in multistart + This is mainly supported for completeness. Consider optimagic's built in multistart optimization for a similar approach that can run multiple optimizations in parallel, - supports all local algorithms in estimagic (as opposed to just those from scipy) + supports all local algorithms in optimagic (as opposed to just those from scipy) and allows for a better visualization of the multistart history. When provided the derivative is passed to the local minimization method. @@ -587,21 +587,28 @@ install estimagic. - **local_algorithm** (str/callable): Any scipy local minimizer: valid options are. "Nelder-Mead". "Powell". "CG". "BFGS". "Newton-CG". "L-BFGS-B". "TNC". "COBYLA". - "SLSQP". "trust-constr". "dogleg". "trust-ncg". "trust-exact". "trust-krylov". - or a custom function for local minimization, default is "L-BFGS-B". - - **n_local_optimizations**: (int) The number local optimizations. Default is 100 as in scipy's default. - - **temperature**: (float) Controls the randomness in the optimization process. Higher the temperatures the larger jumps in function value will be accepted. Default is 1.0 as in scipy's default. + "SLSQP". "trust-constr". "dogleg". "trust-ncg". "trust-exact". "trust-krylov". + or a custom function for local minimization, default is "L-BFGS-B". + - **n_local_optimizations**: (int) The number local optimizations. Default is 100 as + in scipy's default. + - **temperature**: (float) Controls the randomness in the optimization process. + Higher the temperatures the larger jumps in function value will be accepted. + Default is 1.0 as in scipy's default. - **stepsize**: (float) Maximum step size. Default is 0.5 as in scipy's default. - **local_algo_options**: (dict) Additional keyword arguments for the local minimizer. Check the documentation of the local scipy algorithms for details on what is supported. - - **take_step**: (callable) Replaces the default step-taking routine. Default is None as in scipy's default. - - **accept_test**: (callable) Define a test to judge the acception of steps. Default is None as in scipy's default. - - **interval**: (int) Determined how often the step size is updated. Default is 50 as in scipy's default. + - **take_step**: (callable) Replaces the default step-taking routine. Default is + None as in scipy's default. + - **accept_test**: (callable) Define a test to judge the acception of steps. Default + is None as in scipy's default. + - **interval**: (int) Determined how often the step size is updated. Default is 50 + as in scipy's default. - **convergence.n_unchanged_iterations**: (int) Number of iterations the global - minimum estimate stays the same to stops the algorithm. Default is None as in - scipy's default. - - **seed**: (None, int, numpy.random.Generator,numpy.random.RandomState)Default is None as in scipy's default. + minimum estimate stays the same to stops the algorithm. Default is None as in + scipy's default. + - **seed**: (None, int, numpy.random.Generator,numpy.random.RandomState)Default is + None as in scipy's default. - **target_accept_rate**: (float) Adjusts the step size. Default is 0.5 as in scipy's default. - **stepwise_factor**: (float) Step size multiplier upon each step. Lies between (0,1), default is 0.9 as in scipy's default. @@ -619,7 +626,7 @@ install estimagic. Brute force evaluates the criterion at each point and that is why better suited for problems with very few parameters. The start values are not actually used because the grid is only defined by bounds. - It is still necessary for estimagic to infer the number and format of the + It is still necessary for optimagic to infer the number and format of the parameters. Due to the parallelization, this algorithm cannot collect a history of parameters @@ -627,12 +634,15 @@ install estimagic. The algorithm supports the following options: - - **n_grid_points** (int): the number of grid points to use for the brute force search. Default is 20 as in scipy. - - **polishing_function** (callable): Function to seek a more precise minimum near brute-force' best gridpoint taking brute-force's result at initial guess as a positional argument. Default is None providing no polishing. + - **n_grid_points** (int): the number of grid points to use for the brute force + search. Default is 20 as in scipy. + - **polishing_function** (callable): Function to seek a more precise minimum near + brute-force' best gridpoint taking brute-force's result at initial guess as a + positional argument. Default is None providing no polishing. - **n_cores** (int): The number of cores on which the function is evaluated in - parallel. Default 1. - - **batch_evaluator** (str or callable). An estimagic batch evaluator. Default - 'joblib'. + parallel. Default 1. + - **batch_evaluator** (str or callable). An optimagic batch evaluator. Default + 'joblib'. ``` @@ -645,12 +655,13 @@ install estimagic. Find the global minimum of a multivariate function using differential evolution (DE). DE is a gradient-free method. - Due to estimagic's general parameter format the integrality and vectorized + Due to optimagic's general parameter format the integrality and vectorized arguments are not supported. The algorithm supports the following options: - - **strategy** (str): Measure of quality to improve a candidate solution, can be one of the following keywords + - **strategy** (str): Measure of quality to improve a candidate solution, can be one + of the following keywords (default 'best1bin'.) - ‘best1bin’ - ‘best1exp’ - ‘rand1exp’ @@ -663,25 +674,40 @@ install estimagic. - ‘best2bin’ - ‘rand2bin’ - ‘rand1bin’ - ,default is 'best1bin'. - - **stopping.max_iterations** (int): The maximum number of criterion evaluations without polishing is(stopping.max_iterations + 1) * population_size * number of parameters) - - **population_size_multiplier** (int): A multiplier setting the population size. The number of individuals in the population is population_size * number of parameters. The default 15. - - **convergence.relative_criterion_tolerance** (float): Default 0.01. - - **mutation_constant** (float/tuple): The differential weight denoted by F in literature. Should be within 0 and 2. The tuple form is used to specify (min, max) dithering which can help speed convergence. Default is (0.5, 1). - - **recombination_constant** (float): The crossover probability or CR in the literature determines the probability that two solution vectors will be combined to produce a new solution vector. Should be between 0 and 1. The default is 0.7. + + - **stopping.maxiter** (int): The maximum number of criterion evaluations + without polishing is(stopping.maxiter + 1) * population_size * number of + parameters + - **population_size_multiplier** (int): A multiplier setting the population size. + The number of individuals in the population is population_size * number of + parameters. The default 15. + - **convergence.ftol_rel** (float): Default 0.01. + - **mutation_constant** (float/tuple): The differential weight denoted by F in + literature. Should be within 0 and 2. The tuple form is used to specify + (min, max) dithering which can help speed convergence. Default is (0.5, 1). + - **recombination_constant** (float): The crossover probability or CR in the + literature determines the probability that two solution vectors will be combined + to produce a new solution vector. Should be between 0 and 1. The default is 0.7. - **seed** (int): DE is stochastic. Define a seed for reproducability. - - **polish** (bool): Uses scipy's L-BFGS-B for unconstrained problems and trust-constr for constrained problems to slightly improve the minimization. Default is True. - - **sampling_method** (str/np.array): Specify the sampling method for the initial population. It can be one of the following options - - "latinhypercube" - - "sobol" - - "halton" - - "random" - - an array specifying the initial population of shape (total population size, number of parameters). The initial population is clipped to bounds before use. Default is 'latinhypercube' - - **convergence.absolute_criterion_tolerance** (float): CONVERGENCE_SECOND_BEST_ABSOLUTE_CRITERION_TOLERANCE + - **polish** (bool): Uses scipy's L-BFGS-B for unconstrained problems and + trust-constr for constrained problems to slightly improve the minimization. + Default is True. + - **sampling_method** (str/np.array): Specify the sampling method for the initial + population. It can be one of the following options + - "latinhypercube" + - "sobol" + - "halton" + - "random" + - an array specifying the initial population of shape (total population size, + number of parameters). The initial population is clipped to bounds before use. + Default is 'latinhypercube' + + - **convergence.ftol_abs** (float): + CONVERGENCE_SECOND_BEST_ABSOLUTE_CRITERION_TOLERANCE - **n_cores** (int): The number of cores on which the function is evaluated in - parallel. Default 1. - - **batch_evaluator** (str or callable). An estimagic batch evaluator. Default - 'joblib'. + parallel. Default 1. + - **batch_evaluator** (str or callable). An optimagic batch evaluator. Default + 'joblib'. ``` @@ -697,29 +723,40 @@ install estimagic. The algorithm supports the following options: - **local_algorithm** (str): The local optimization algorithm to be used. Only - COBYLA and SLSQP supports constraints. Valid options are - "Nelder-Mead". "Powell". "CG". "BFGS". "Newton-CG". "L-BFGS-B". "TNC". "COBYLA". - "SLSQP". "trust-constr". "dogleg". "trust-ncg". "trust-exact". "trust-krylov" - or a custom function for local minimization, default is "L-BFGS-B". + COBYLA and SLSQP supports constraints. Valid options are + "Nelder-Mead". "Powell". "CG". "BFGS". "Newton-CG". "L-BFGS-B". "TNC". "COBYLA". + "SLSQP". "trust-constr". "dogleg". "trust-ncg". "trust-exact". "trust-krylov" + or a custom function for local minimization, default is "L-BFGS-B". - **local_algo_options**: (dict) Additional keyword arguments for the local minimizer. Check the documentation of the local scipy algorithms for details on what is supported. - - **n_sampling_points** (int): Specify the number of sampling points to construct the simplical complex. - - **n_simplex_iterations** (int): Number of iterations to construct the simplical complex. Default is 1 as in scipy. - - **sampling_method** (str/callable): The method to use for sampling the search space. Default 'simplicial'. - - **max_sampling_evaluations** (int): The maximum number of evaluations of the criterion function in the sampling phase. - - **convergence.minimum_criterion_value** (float): Specify the global minimum when it is known. Default is - **np.inf. For maximization problems, flip the sign. - - **convergence.minimum_criterion_tolerance** (float): Specify the relative error between the current best minimum and the supplied global criterion_minimum allowed. Default is scipy's default, 1e-4. - - **stopping.max_iterations** (int): The maximum number of iterations. - - **stopping.max_criterion_evaluations** (int): The maximum number of criterion - evaluations. - - **stopping.max_processing_time** (int): The maximum time allowed for the optimization. - - **minimum_homology_group_rank_differential** (int): The minimum difference in the rank of the homology group between iterations. + - **n_sampling_points** (int): Specify the number of sampling points to construct + the simplical complex. + - **n_simplex_iterations** (int): Number of iterations to construct the simplical + complex. Default is 1 as in scipy. + - **sampling_method** (str/callable): The method to use for sampling the search + space. Default 'simplicial'. + - **max_sampling_evaluations** (int): The maximum number of evaluations of the + criterion function in the sampling phase. + - **convergence.minimum_criterion_value** (float): Specify the global minimum when + it is known. Default is - np.inf. For maximization problems, flip the sign. + - **convergence.minimum_criterion_tolerance** (float): Specify the relative error + between the current best minimum and the supplied global criterion_minimum + allowed. Default is scipy's default, 1e-4. + - **stopping.maxiter** (int): The maximum number of iterations. + - **stopping.maxfun** (int): The maximum number of criterion + evaluations. + - **stopping.max_processing_time** (int): The maximum time allowed for the + optimization. + - **minimum_homology_group_rank_differential** (int): The minimum difference in the + rank of the homology group between iterations. - **symmetry** (bool): Specify whether the criterion contains symetric variables. - - **minimize_every_iteration** ()bool: Specify whether the gloabal sampling points are passed to the local algorithm in every iteration. + - **minimize_every_iteration** (bool): Specify whether the gloabal sampling points + are passed to the local algorithm in every iteration. - **max_local_minimizations_per_iteration** (int): The maximum number of local - optimizations per iteration. Default False, i.e. no limit. - - **infinity_constraints** (bool): Specify whether to save the sampling points outside the feasible domain. Default is True. + optimizations per iteration. Default False, i.e. no limit. + - **infinity_constraints** (bool): Specify whether to save the sampling points + outside the feasible domain. Default is True. ``` @@ -734,11 +771,12 @@ install estimagic. The algorithm supports the following options: - - **stopping.max_iterations** (int): Specify the maximum number of global searh iterations. + - **stopping.maxiter** (int): Specify the maximum number of global searh + iterations. - **local_algorithm** (str): The local optimization algorithm to be used. valid - options are. "Nelder-Mead". "Powell". "CG". "BFGS". "Newton-CG". "L-BFGS-B". "TNC". - "COBYLA". "SLSQP". "trust-constr". "dogleg". "trust-ncg". "trust-exact". - "trust-krylov". Default "L-BFGS-B". + options are: "Nelder-Mead", "Powell", "CG", "BFGS", "Newton-CG", "L-BFGS-B", + "TNC", "COBYLA", "SLSQP", "trust-constr", "dogleg", "trust-ncg", "trust-exact", + "trust-krylov", Default "L-BFGS-B". - **local_algo_options**: (dict) Additional keyword arguments for the local minimizer. Check the documentation of the local scipy algorithms for details on what is supported. @@ -746,9 +784,9 @@ install estimagic. - **restart_temperature_ratio** (float): Reanneling starts when the algorithm is decreased to initial_temperature * restart_temperature_ratio. Default is 2e-05. - **visit** (float): Specify the thickness of visiting distribution's tails. Range is (1, 3] and default is scipy's default, 2.62. - **accept** (float): Controls the probability of acceptance. Range is (-1e4, -5] and default is scipy's default, -5.0. Smaller values lead to lower acceptance probability. - - **stopping.max_criterion_evaluations** (int): soft limit for the number of criterion evaluations. + - **stopping.maxfun** (int): soft limit for the number of criterion evaluations. - **seed** (int, None or RNG): Dual annealing is a stochastic process. Seed or - random number generator. Default None. + random number generator. Default None. - **no_local_search** (bool): Specify whether to apply a traditional Generalized Simulated Annealing with no local search. Default is False. ``` @@ -765,10 +803,10 @@ install estimagic. The algorithm supports the following options: - **eps** (float): Specify the minimum difference of the criterion values between the current best hyperrectangle and the next potentially best hyperrectangle to be divided determining the trade off between global and local search. Default is 1e-6 differing from scipy's default 1e-4. - - **stopping_max_criterion_evaluations** (int/None): Maximum number of criterion evaluations allowed. Default is None which caps the number of evaluations at 1000 * number of dimentions automatically. - - **stopping_max_iterations** (int): Maximum number of iterations allowed. + - **stopping.maxfun** (int/None): Maximum number of criterion evaluations allowed. Default is None which caps the number of evaluations at 1000 * number of dimentions automatically. + - **stopping.maxiter** (int): Maximum number of iterations allowed. - **locally_biased** (bool): Determine whether to use the locally biased variant of the algorithm DIRECT_L. Default is True. - - **convergence.minimum_criterion_value** (float): Specify the global minimum when it is known. Default is - **np.inf. For maximization problems, flip the sign. + - **convergence.minimum_criterion_value** (float): Specify the global minimum when it is known. Default is minus infinity. For maximization problems, flip the sign. - **convergence.minimum_criterion_tolerance** (float): Specify the relative error between the current best minimum and the supplied global criterion_minimum allowed. Default is scipy's default, 1e-4. - **volume_hyperrectangle_tolerance** (float): Specify the smallest volume of the hyperrectangle containing the lowest criterion value allowed. Range is (0,1). Default is 1e-16. - **length_hyperrectangle_tolerance** (float): Depending on locally_biased it can refer to normalized side (True) or diagonal (False) length of the hyperrectangle containing the lowest criterion value. Range is (0,1). Default is scipy's default, 1e-6. @@ -803,9 +841,9 @@ We implement a few algorithms from scratch. They are currently considered experi bhhh supports the following options: - - **convergence_absolute_gradient_tolerance** (float): Stopping criterion for the + - **convergence.gtol_abs** (float): Stopping criterion for the gradient tolerance. Default is 1e-8. - - **stopping_max_iterations** (int): Maximum number of iterations. + - **stopping.maxiter** (int): Maximum number of iterations. If reached, terminate. Default is 200. ``` @@ -836,14 +874,14 @@ We implement a few algorithms from scratch. They are currently considered experi - **adaptive** (bool): Adjust parameters of Nelder-Mead algorithm to account for simplex size. The default is True. - - **stopping.max_iterations** (int): Maximum number of algorithm iterations. + - **stopping.maxiter** (int): Maximum number of algorithm iterations. The default is STOPPING_MAX_ITERATIONS. - - **convergence.absolute_criterion_tolerance** (float): maximal difference between + - **convergence.ftol_abs** (float): maximal difference between function value evaluated on simplex points. The default is CONVERGENCE_SECOND_BEST_ABSOLUTE_CRITERION_TOLERANCE. - - **convergence.absolute_params_tolerance** (float): maximal distance between points + - **convergence.xtol_abs** (float): maximal distance between points in the simplex. The default is CONVERGENCE_SECOND_BEST_ABSOLUTE_PARAMS_TOLERANCE. - **batch_evaluator** (string or callable): See :ref:`batch_evaluators` for @@ -883,19 +921,19 @@ We implement a few algorithms from scratch. They are currently considered experi pounders supports the following options: - - **convergence_absolute_gradient_tolerance**: Convergence tolerance for the + - **convergence.gtol_abs**: Convergence tolerance for the absolute gradient norm. Stop if norm of the gradient is less than this. Default is 1e-8. - - **convergence_relative_gradient_tolerance**: Convergence tolerance for the + - **convergence.gtol_rel**: Convergence tolerance for the relative gradient norm. Stop if norm of the gradient relative to the criterion value is less than this. Default is 1-8. - - **convergence_scaled_gradient_tolerance**: Convergence tolerance for the + - **convergence.gtol_scaled**: Convergence tolerance for the scaled gradient norm. Stop if norm of the gradient divided by norm of the gradient at the initial parameters is less than this. Disabled, i.e. set to False, by default. - **max_interpolation_points** (int): Maximum number of interpolation points. Default is `2 * n + 1`, where `n` is the length of the parameter vector. - - **stopping_max_iterations** (int): Maximum number of iterations. + - **stopping.maxiter** (int): Maximum number of iterations. If reached, terminate. Default is 2000. - **trustregion_initial_radius (float)**: Delta, initial trust-region radius. 0.1 by default. @@ -946,7 +984,7 @@ We implement a few algorithms from scratch. They are currently considered experi None of the dictionary keys need to be specified by default, but can be. - **batch_evaluator** (str or callable): Name of a pre-implemented batch evaluator (currently "joblib" and "pathos_mp") or callable with the same interface - as the estimagic batch_evaluators. Default is "joblib". + as the optimagic batch_evaluators. Default is "joblib". - **n_cores (int)**: Number of processes used to parallelize the function evaluations. Default is 1. @@ -1014,17 +1052,17 @@ need to have [petsc4py](https://pypi.org/project/petsc4py/) installed. \frac{||g(X)||}{||g(X0)||} < \epsilon - - **convergence.absolute_gradient_tolerance** (float): Stop if norm of gradient is less than this. - If set to False the algorithm will not consider convergence.absolute_gradient_tolerance. - - **convergence.relative_gradient_tolerance** (float): Stop if relative norm of gradient is less + - **convergence.gtol_abs** (float): Stop if norm of gradient is less than this. + If set to False the algorithm will not consider convergence.gtol_abs. + - **convergence.gtol_rel** (float): Stop if relative norm of gradient is less than this. If set to False the algorithm will not consider - convergence.relative_gradient_tolerance. + convergence.gtol_rel. - **convergence.scaled_gradient_tolerance** (float): Stop if scaled norm of gradient is smaller than this. If set to False the algorithm will not consider convergence.scaled_gradient_tolerance. - **trustregion.initial_radius** (float): Initial value of the trust region radius. It must be :math:`> 0`. - - **stopping.max_iterations** (int): Alternative Stopping criterion. + - **stopping.maxiter** (int): Alternative Stopping criterion. If set the routine will stop after the number of specified iterations or after the step size is sufficiently small. If the variable is set the default criteria will all be ignored. @@ -1053,14 +1091,14 @@ install each of them separately: The DFO-LS algorithm :cite:`Cartis2018b` is designed to solve the nonlinear least-squares minimization problem (with optional bound constraints). - Remember to cite :cite:`Cartis2018b` when using DF-OLS in addition to estimagic. + Remember to cite :cite:`Cartis2018b` when using DF-OLS in addition to optimagic. .. math:: \min_{x\in\mathbb{R}^n} &\quad f(x) := \sum_{i=1}^{m}r_{i}(x)^2 \\ \text{s.t.} &\quad \text{lower_bounds} \leq x \leq \text{upper_bounds} - The :math:`r_{i}` are called root contributions in estimagic. + The :math:`r_{i}` are called root contributions in optimagic. DFO-LS is a derivative-free optimization algorithm, which means it does not require the user to provide the derivatives of f(x) or :math:`r_{i}(x)`, nor does it @@ -1098,7 +1136,7 @@ install each of them separately: 3. when a sufficient reduction to the criterion value at the start parameters has been reached, i.e. when :math:`\frac{f(x)}{f(x_0)} \leq - \text{convergence.scaled_criterion_tolerance}` + \text{convergence.ftol_scaled}` 4. when all evaluations on the interpolation points fall within a scaled version of the noise level of the criterion function. This is only applicable if the @@ -1123,11 +1161,11 @@ install each of them separately: .. warning:: Very small values, as in most other tolerances don't make sense here. - - **convergence.scaled_criterion_tolerance** (float): + - **convergence.ftol_scaled** (float): Terminate if a point is reached where the ratio of the criterion value to the criterion value at the start params is below this value, i.e. if :math:`f(x_k)/f(x_0) \leq - \text{convergence.scaled_criterion_tolerance}`. Note this is + \text{convergence.ftol_scaled}`. Note this is deactivated unless the lowest mathematically possible criterion value (0.0) is actually achieved. - **convergence.slow_progress** (dict): Arguments for converging when the evaluations @@ -1155,7 +1193,7 @@ install each of them separately: Default is no averaging (i.e. ``noise_n_evals_per_point(...) = 1``). - **random_directions_orthogonal** (bool): see :ref:`algo_options`. - - **stopping.max_criterion_evaluations** (int): see :ref:`algo_options`. + - **stopping.maxfun** (int): see :ref:`algo_options`. - **threshold_for_safety_step** (float): see :ref:`algo_options`. - **trustregion.expansion_factor_successful** (float): see :ref:`algo_options`. - **trustregion.expansion_factor_very_successful** (float): see :ref:`algo_options`. @@ -1196,7 +1234,7 @@ install each of them separately: minimization problems. Remember to cite :cite:`Powell2009` and :cite:`Cartis2018` when using pybobyqa in - addition to estimagic. If you take advantage of the ``seek_global_optimum`` option, + addition to optimagic. If you take advantage of the ``seek_global_optimum`` option, cite :cite:`Cartis2018a` additionally. There are two main situations when using a derivative-free algorithm like BOBYQA @@ -1272,7 +1310,7 @@ install each of them separately: - **seek_global_optimum** (bool): whether to apply the heuristic to escape local minima presented in :cite:`Cartis2018a`. Only applies for noisy criterion functions. - - **stopping.max_criterion_evaluations** (int): see :ref:`algo_options`. + - **stopping.maxfun** (int): see :ref:`algo_options`. - **threshold_for_safety_step** (float): see :ref:`algo_options`. - **trustregion.expansion_factor_successful** (float): see :ref:`algo_options`. - **trustregion.expansion_factor_very_successful** (float): see :ref:`algo_options`. @@ -1306,7 +1344,7 @@ install each of them separately: ## PYGMO2 Optimizers -Please cite {cite}`Biscani2020` in addition to estimagic when using pygmo. estimagic +Please cite {cite}`Biscani2020` in addition to optimagic when using pygmo. optimagic supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. ```{eval-rst} @@ -1341,7 +1379,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. number of parameters but at least 64. - **batch_evaluator** (str or Callable): Name of a pre-implemented batch evaluator (currently 'joblib' and 'pathos_mp') or Callable with the same - interface as the estimagic batch_evaluators. See :ref:`batch_evaluators`. + interface as the optimagic batch_evaluators. See :ref:`batch_evaluators`. - **n_cores** (int): Number of cores to use. - **seed** (int): seed used by the internal random number generator. - **discard_start_params** (bool): If True, the start params are not guaranteed @@ -1349,7 +1387,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **kernel_size** (int): Number of solutions stored in the solution archive. - **speed_parameter_q** (float): This parameter manages the convergence speed towards the found minima (the smaller the faster). In the pygmo @@ -1361,7 +1399,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. function's values distances. - **threshold** (int): when the iteration counter reaches the threshold the convergence speed is set to 0.01 automatically. To deactivate this effect - set the threshold to stopping.max_iterations which is the largest allowed + set the threshold to stopping.maxiter which is the largest allowed value. - **speed_of_std_values_convergence** (int): parameter that determines the convergence speed of the standard deviations. This must be an integer @@ -1369,7 +1407,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **stopping.max_n_without_improvements** (int): if a positive integer is assigned here, the algorithm will count the runs without improvements, if this number exceeds the given value, the algorithm will be stopped. - - **stopping.max_criterion_evaluations** (int): maximum number of function + - **stopping.maxfun** (int): maximum number of function evaluations. - **focus** (float): this parameter makes the search for the optimum greedier and more focused on local improvements (the higher the greedier). If the @@ -1393,7 +1431,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. in :cite:`Mernik2015`. The algorithm is only suited for bounded parameter spaces. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **seed** (int): seed used by the internal random number generator. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function @@ -1425,7 +1463,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **weight_coefficient** (float): Weight coefficient. It is denoted by $F$ in the main paper and must lie in [0, 2]. It controls the amplification of the differential variation $(x_{r_2, G} - x_{r_3, G})$. @@ -1446,7 +1484,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **convergence.criterion_tolerance**: stopping criteria on the criterion tolerance. Default is 1e-6. It is not clear whether this is the absolute or relative criterion tolerance. - - **convergence.relative_params_tolerance**: stopping criteria on the x + - **convergence.xtol_rel**: stopping criteria on the x tolerance. In pygmo the default is 1e-6 but we use our default value of 1e-5. ``` @@ -1475,7 +1513,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): number of generations to consider. Each generation + - **stopping.maxiter** (int): number of generations to consider. Each generation will compute the objective function once. ``` @@ -1500,7 +1538,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **crossover_probability** (float): Crossover probability. - **crossover_strategy** (str): the crossover strategy. One of “exponential”,“binomial”, “single” or “sbx”. Default is "exponential". @@ -1549,7 +1587,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. cannot be done in parallel with other evaluations. Default False. - jde (bool): Whether to use the jDE self-adaptation variant to control the $F$ and $CR$ parameter. If True jDE is used, else iDE. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **mutation_variant** (int or str): code for the mutation variant to create a new candidate individual. The default is "rand/1/exp". The first ten are the classical mutation variants introduced in the orginal DE algorithm, the remaining @@ -1594,9 +1632,9 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. CMA-ES is one of the most successful algorithm, classified as an Evolutionary Strategy, for derivative-free global optimization. The version supported by - estimagic is the version described in :cite:`Hansen2006`. + optimagic is the version described in :cite:`Hansen2006`. - In contrast to the pygmo version, estimagic always sets force_bounds to True. This + In contrast to the pygmo version, optimagic always sets force_bounds to True. This avoids that ill defined parameter values are evaluated. - **population_size** (int): Size of the population. If None, it's twice the number of @@ -1606,7 +1644,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **backward_horizon** (float): backward time horizon for the evolution path. It must lie betwen 0 and 1. - **variance_loss_compensation** (float): makes partly up for the small variance loss in @@ -1692,7 +1730,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **omega** (float): depending on the variant chosen, :math:`\omega` is the particles' inertia weight or the construction coefficient. It must lie between 0 and 1. @@ -1758,13 +1796,13 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. parameters but at least 10. - **batch_evaluator (str or Callable)**: Name of a pre-implemented batch evaluator (currently 'joblib' and 'pathos_mp') or Callable with the same interface as the - estimagic batch_evaluators. See :ref:`batch_evaluators`. + optimagic batch_evaluators. See :ref:`batch_evaluators`. - **n_cores** (int): Number of cores to use. - **seed** (int): seed used by the internal random number generator. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **omega** (float): depending on the variant chosen, :math:`\omega` is the particles' inertia weight or the constructuion coefficient. It must lie between 0 and 1. @@ -1869,7 +1907,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **learning_rate_mean_update** (float): learning rate for the mean update (:math:`\eta_\mu`). It must be between 0 and 1 or None. @@ -1895,7 +1933,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. Minimize a scalar function usinng the Grey Wolf Optimizer. The grey wolf optimizer was proposed by :cite:`Mirjalili2014`. The pygmo - implementation that is wrapped by estimagic is pased on the pseudo code provided in + implementation that is wrapped by optimagic is pased on the pseudo code provided in that paper. This algorithm is a classic example of a highly criticizable line of search that led @@ -1914,7 +1952,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. ``` @@ -1937,7 +1975,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_criterion_evaluations** (int): maximum number of function evaluations. + - **stopping.maxfun** (int): maximum number of function evaluations. - **start_range** (float): the start range. Must be in (0, 1]. - **stop_range** (float): the stop range. Must be in (0, start_range]. - **reduction_coeff** (float): the range reduction coefficient. Must be in (0, 1). @@ -1961,7 +1999,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. - **discard_start_params** (bool): If True, the start params are not guaranteed to be part of the initial population. This saves one criterion function evaluation that cannot be done in parallel with other evaluations. Default False. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **choose_from_memory_probability** (float): probability of choosing from memory (similar to a crossover probability). - **min_pitch_adjustment_rate** (float): minimum pitch adjustment rate. (similar to a @@ -1994,7 +2032,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. cannot be done in parallel with other evaluations. Default False. - **jde** (bool): Whether to use the jDE self-adaptation variant to control the $F$ and $CR$ parameter. If True jDE is used, else iDE. - - **stopping.max_iterations** (int): Number of generations to evolve. + - **stopping.maxiter** (int): Number of generations to evolve. - **allowed_variants** (array-like object): allowed mutation variants (can be codes or strings). Each code refers to one mutation variant to create a new candidate individual. The first ten refer to the classical mutation variants introduced in @@ -2033,7 +2071,7 @@ supports the following [pygmo2](https://esa.github.io/pygmo2) optimizers. ## The Interior Point Optimizer (ipopt) -estimagic's support for the Interior Point Optimizer ({cite}`Waechter2005`, +optimagic's support for the Interior Point Optimizer ({cite}`Waechter2005`, {cite}`Waechter2005a`, {cite}`Waechter2005b`, {cite}`Nocedal2009`) is built on [cyipopt](https://cyipopt.readthedocs.io/en/latest/index.html), a Python wrapper for the [Ipopt optimization package](https://coin-or.github.io/Ipopt/index.html). @@ -2073,13 +2111,13 @@ To use ipopt, you need to have ipopt accepts a Python `None`. The following options are not supported: - - `num_linear_variables`: since estimagic may reparametrize your problem + - `num_linear_variables`: since optimagic may reparametrize your problem and this changes the parameter problem, we do not support this option. - derivative checks - - print options. Use estimagic's dashboard to monitor your optimization. + - print options. - - **convergence.relative_criterion_tolerance** (float): The algorithm + - **convergence.ftol_rel** (float): The algorithm terminates successfully, if the (scaled) non linear programming error becomes smaller than this value. @@ -2095,7 +2133,7 @@ To use ipopt, you need to have - **s_max** (float): Scaling threshold for the NLP error. - - **stopping.max_iterations** (int): If the maximum number of iterations is + - **stopping.maxiter** (int): If the maximum number of iterations is reached, the optimization stops, but we do not count this as successful convergence. The difference to ``max_criterion_evaluations`` is that one iteration might need several criterion evaluations, for example in a line @@ -2283,16 +2321,7 @@ To use ipopt, you need to have overrides ``nlp_scaling_max_gradient`` for the objective function. The valid range for this real option is 0 ≤ nlp_scaling_obj_target_gradient and its default value is 0. - - **nlp_scaling_constr_target_gradient** (float): Min value of gradient-based - scaling values. - This is the lower bound for the scaling factors computed by - gradient-based scaling method. If - some derivatives of some functions are huge, the scaling factors will - otherwise become very small, and the (unscaled) final constraint - violation, for example, might then be significant. Note: This option is - only used if ``nlp_scaling_method`` is chosen as "gradient-based". The - valid range for this real option is 0 ≤ nlp_scaling_min_value and its - default value is :math:`1e-08`. + - **nlp_scaling_constr_target_gradient** (float): arget value for constraint function gradient size. If a positive number is chosen, the scaling factors for the constraint functions are computed so that the gradient has the max norm of the given size at the starting point. This overrides nlp_scaling_max_gradient for the constraint functions. The valid range for this real option is 0 ≤ nlp_scaling_constr_target_gradient and its default value is 0. - **nlp_scaling_min_value** (float): Minimum value of gradient-based scaling values. This is the lower bound for the scaling factors computed by gradient-based scaling method. If some derivatives @@ -2842,7 +2871,7 @@ To use ipopt, you need to have option "barrier_strategy"). This option is only used if "mu_strategy" is "adaptive". Changing this option is experimental. The default value for this string option is "yes". Possible values: "yes", "no", True, False - - **corrector_compl_avrg_red_fact** (int): advanced! Complementarity tolerance + - **corrector_compl_avrg_red_fact** (float): advanced! Complementarity tolerance factor for accepting corrector step. This option determines the factor by which complementarity is allowed to increase for a corrector step to be accepted. Changing this option is experimental. The valid range for this @@ -3237,7 +3266,7 @@ To use ipopt, you need to have ## The Fides Optimizer -estimagic supports the +optimagic supports the [Fides Optimizer](https://fides-optimizer.readthedocs.io/en/latest). To use Fides, you need to have [the fides package](https://github.com/fides-dev/fides) installed (`pip install fides>=0.7.4`, make sure you have at least 0.7.1). @@ -3262,7 +3291,7 @@ need to have [the fides package](https://github.com/fides-dev/fides) installed - **hessian_update_strategy** (str): Hessian Update Strategy to employ. You can provide a lowercase or uppercase string or a fides.hession_approximation.HessianApproximation class instance. FX, SSM, TSSM and - GNSBFGS are not supported by estimagic. The available update strategies are: + GNSBFGS are not supported by optimagic. The available update strategies are: - **bb**: Broydens "bad" method as introduced :cite:`Broyden1965`. - **bfgs**: Broyden-Fletcher-Goldfarb-Shanno update strategy. @@ -3277,28 +3306,28 @@ need to have [the fides package](https://github.com/fides-dev/fides) installed - **sr1**: Symmetric Rank 1 update strategy as described in :cite:`Nocedal1999`, Chapter 6.2. - - **convergence.absolute_criterion_tolerance** (float): absolute convergence criterion + - **convergence.ftol_abs** (float): absolute convergence criterion tolerance. This is only the interpretation of this parameter if the relative criterion tolerance is set to 0. Denoting the absolute criterion tolerance by :math:`\alpha` and the relative criterion tolerance by :math:`\beta`, the convergence condition on the criterion improvement is :math:`|f(x_k) - f(x_{k-1})| < \alpha + \beta \cdot |f(x_{k-1})|` - - **convergence.relative_criterion_tolerance** (float): relative convergence criterion + - **convergence.ftol_rel** (float): relative convergence criterion tolerance. This is only the interpretation of this parameter if the absolute criterion tolerance is set to 0 (as is the default). Denoting the absolute criterion tolerance by :math:`\alpha` and the relative criterion tolerance by :math:`\beta`, the convergence condition on the criterion improvement is :math:`|f(x_k) - f(x_{k-1})| < \alpha + \beta \cdot |f(x_{k-1})|` - - **convergence.absolute_params_tolerance** (float): The optimization terminates + - **convergence.xtol_abs** (float): The optimization terminates successfully when the step size falls below this number, i.e. when :math:`||x_{k+1} - x_k||` is smaller than this tolerance. - - **convergence.absolute_gradient_tolerance** (float): The optimization terminates + - **convergence.gtol_abs** (float): The optimization terminates successfully when the gradient norm is less or equal than this tolerance. - - **convergence.relative_gradient_tolerance** (float): The optimization terminates + - **convergence.gtol_rel** (float): The optimization terminates successfully when the norm of the gradient divided by the absolute function value is less or equal to this tolerance. - - **stopping.max_iterations** (int): maximum number of allowed iterations. + - **stopping.maxiter** (int): maximum number of allowed iterations. - **stopping.max_seconds** (int): maximum number of walltime seconds, deactivated by default. @@ -3347,10 +3376,10 @@ need to have [the fides package](https://github.com/fides-dev/fides) installed ## The NLOPT Optimizers (nlopt) -estimagic supports the following [NLOPT](https://nlopt.readthedocs.io/en/latest/) +optimagic supports the following [NLOPT](https://nlopt.readthedocs.io/en/latest/) algorithms. Please add the [appropriate citations](https://nlopt.readthedocs.io/en/latest/Citing_NLopt/) in -addition to estimagic when using an NLOPT algorithm. To install nlopt run +addition to optimagic when using an NLOPT algorithm. To install nlopt run `conda install nlopt`. ```{eval-rst} @@ -3371,15 +3400,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run For details see :cite:`Powell2009`. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3399,15 +3428,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run that the nlopt version supports bounds. This is done by moving all new points that would lie outside the bounds exactly on the bounds. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3443,15 +3472,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run In case of bounded constraints, this method is dominated by `nlopt_bobyqa` and `nlopt_cobyla`. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. @@ -3486,15 +3515,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run - Supports unequal initial-step sizes in the different parameters. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3518,15 +3547,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run of Rowan, is that it explicitly supports bound constraints providing big improvement in the case where the optimum lies against one of the constraints. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3553,15 +3582,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run `NEWUOA` requires the dimension n of the parameter space to be `≥ 2`, i.e. the implementation does not handle one-dimensional optimization problems. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3585,15 +3614,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run Detailed description of algorithms is given in :cite:`Dembo1983`. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3617,15 +3646,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run Detailed description of algorithms is given in :cite:`Nocedal1989`, :cite:`Nocedal1980`. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3649,15 +3678,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run The implementation is based on CCSA algorithm described in :cite:`Svanberg2002`. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3681,15 +3710,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run verge to a local optimum from any feasible starting point. - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3710,15 +3739,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run Detailed explanation of the algorithm, including its two variations of rank-2 and rank-1 methods can be found in the following paper :cite:`Vlcek2006` . - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - **rank_1_update** (bool): Whether I rank-1 or rank-2 update is used. @@ -3740,15 +3769,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run The implementation is based on the procedure described in :cite:`Kraft1988` and :cite:`Kraft1994` . - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3785,15 +3814,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run - "DIRECT_L_RAND_NOSCAL" - "DIRECT_RAND" - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - **locally_biased** (bool): Whether the "L" version of the algorithm is selected. @@ -3816,15 +3845,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run More information on this method can be found in :cite:`DaSilva2010` , :cite:`DaSilva2010a` , :cite:`Beyer2002` and :cite:`Vent1975` . - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3847,15 +3876,15 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run :cite:`PhilipRunarsson2005` and :cite:`Thomas2000` . - - **convergence.relative_params_tolerance** (float): Stop when the relative + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. ``` @@ -3879,149 +3908,21 @@ addition to estimagic when using an NLOPT algorithm. To install nlopt run meter population_size. If the user doesn't specify a value, it is set to the nlopt default of 10*(n+1). - - **convergence.relative_params_tolerance** (float): Stop when the relative movement + - **convergence.xtol_rel** (float): Stop when the relative movement between parameter vectors is smaller than this. - - **convergence.absolute_params_tolerance** (float): Stop when the absolute movement + - **convergence.xtol_abs** (float): Stop when the absolute movement between parameter vectors is smaller than this. - - **convergence.relative_criterion_tolerance** (float): Stop when the relative + - **convergence.ftol_rel** (float): Stop when the relative improvement between two iterations is smaller than this. - - **convergence.absolute_criterion_tolerance** (float): Stop when the change of the + - **convergence.ftol_abs** (float): Stop when the change of the criterion function between two iterations is smaller than this. - - **stopping.max_criterion_evaluations** (int): If the maximum number of function + - **stopping.maxfun** (int): If the maximum number of function evaluation is reached, the optimization stops but we do not count this as convergence. - **population_size** (int): Size of the population. If None, it's set to be 10 * (number of parameters + 1). ``` -## The SimOpt Optimizers (simopt) - -estimagic supports the following [SimOpt](https://github.com/simopt-admin/simopt) -algorithms. Please add the -[appropriate citations](https://github.com/simopt-admin/simopt) in addition to estimagic -when using a SimOpt algorithm. To install simopt run `pip install simoptlib==1.0.1`. - -```{eval-rst} -.. dropdown:: simopt_adam - - .. code-block:: - - "simopt_adam" - - Minimize a scalar function using the ADAM algorithm from SimOpt. - - - **stopping_max_iterations** (int): If the maximum number of iterations is reached, - the optimization stops, but we do not count this as convergence. - - **crn_across_solns** (bool): Use CRN across solutions? Default True. - - **r** (int): Number of replications taken at each solution. Default 1. - - **beta_1** (float): Exponential decay of the rate for the first moment estimates. - Default 0.9. - - **beta_2** (float): Exponential decay rate for the second-moment estimates. - Default 0.999. - - **alpha** (float): Step size. Default 1.0. - - **epsilon** (float): A small value to prevent zero-division. Default 10e-8. - - **sensitivity** (float): Shrinking scale for variable bounds. Default 10e-7. -``` - -```{eval-rst} -.. dropdown:: simopt_astrodf - - .. code-block:: - - "simopt_astrodf" - - Minimize a scalar function using the ASTRODF algorithm from SimOpt. - - - **stopping_max_iterations** (int): If the maximum number of iterations is reached, - the optimization stops, but we do not count this as convergence. - - **bounds_padding** (float): Subtract (add) this value of the bounds which will be - used by ASTRODF internally. Default 1e-8. - - **crn_across_solns** (bool): Use CRN across solutions? Default True. - - **delta_max** (float): Maximum value of the trust-region radius. Default 50.0 - - **eta_1** (float): Threshhold for a successful iteration. Default 0.1. - - **eta_2** (float): Threshhold for a very successful iteration. Default 0.5. - - **gamma_1** (float): Very successful step trust-region radius increase. Default - 2.0. - - **gamma_2** (float): Unsuccessful step trust-region radius decrease. Default 0.5. - - **w** (float): Trust-region radius rate of shrinkage in contracation loop. Default - 0.85. - - **mu** (int): Trust-region radius ratio upper bound in contraction loop. Default - 1000. - - **beta** (int): Trust-region radius ratio lower bound in contraction loop. Default - 10. - - **lambda_min** (int): Minimum sample size value. Default 8. - - **simple_solve** (bool): Solve subproblem with Cauchy point (rough approximate)? - Default False. - - **criticality_select** (bool): Skip contraction loop if not near critical - region? Default True. - - **criticality_threshold** (float): Threshold on gradient norm indicating - near-critical region. Default 0.1. - - .. note:: - To get more accurate results in the case of bounds we revert the subtraction of - a large value from the bounds that is done internally in simopt. - Since the algorithm is numerically instable in the case of binding bounds - without this substraction, we subtract a (small) value defined by - ``bounds_padding``. See the ASTRODF `source code - `_ for details. - -``` - -```{eval-rst} -.. dropdown:: simopt_spsa - - .. code-block:: - - "simopt_spsa" - - Minimize a scalar function using the SPSA algorithm from SimOpt. - - - **stopping_max_iterations** (int): If the maximum number of iterations is reached, - the optimization stops, but we do not count this as convergence. - - **crn_across_solns** (bool): Use CRN across solutions? Default True. - - **alpha** (float): Non-negative coefficient in the SPSA gain sequecence ak. - Default 0.602. - - **gamma** (float): Non-negative coefficient in the SPSA gain sequence ck. Default - 0.101. - - **step** (float): Initial desired magnitude of change in the theta elements. - Default 0.5. - - **gavg** (int): Averaged SP gradients used per iteration. Default 1. - - **n_reps** (int): Number of replications takes at each solution. Default 2. - - **n_loss** (int): Number of loss function evaluations used in this gain - calculation. Default 2. - - **eval_pct** (float): Percentage of the expected number of loss evaluations per - run. Default 2/3. - - **iter_pct** (float): Percentage of the maximum expected number of iterations. - Default 0.1. -``` - -```{eval-rst} -.. dropdown:: simopt_strong - - .. code-block:: - - "simopt_strong" - - Minimize a scalar function using the STRONG algorithm from SimOpt. - - - **stopping_max_iterations** (int): If the maximum number of iterations is reached, - the optimization stops, but we do not count this as convergence. - - **crn_across_solns** (bool): Use CRN across solutions? Default True. - - **n0** (int): Initial sample size Default 10. - - **n_r** (int): Number of replications taken at each solution. Default 1. - - **sensitivity** (float): Shrinking scale for VarBds. Default 10e-7. - - **delta_threshold** (float): Maximum value of the radius. Default 1.2. - - **delta_T** (float): Initial size of trust region. Default 2.0. - - **eta_0** (float): Constant for accepting. Default 0.01. - - **eta_1** (float): Constant for more confident accepting. Default 0.3. - - **gamma_1** (float): Constant for shrinking the trust region. Default 0.9. - - **gamma_2** (float): Constant for expanding the trust region. Default 1.11. - - **lambda** (int): Magnifying factor for n_r inside the finite difference function. - Default 2. - - **lambda_2** (float): Magnifying factor for n_r in stage I and stage II. Default - 1.01. -``` - ## References ```{eval-rst} diff --git a/docs/source/conf.py b/docs/source/conf.py index 1a4bbf374..9ce26408d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # -# estimagic documentation build configuration file, created by +# optimagic documentation build configuration file, created by # sphinx-quickstart on Fri Jan 18 10:59:27 2019. # # This file is execfile()d with the current directory set to its @@ -53,6 +53,7 @@ myst_enable_extensions = [ "colon_fence", "dollarmath", + "html_image", ] copybutton_prompt_text = ">>> " copybutton_only_copy_prompt_lines = False @@ -80,13 +81,13 @@ extlinks = { "ghuser": ("https://github.com/%s", "@"), - "gh": ("https://github.com/OpenSourceEconomics/estimagic/pulls/%s", "#"), + "gh": ("https://github.com/OpenSourceEconomics/optimagic/pulls/%s", "#"), } intersphinx_mapping = { "numpy": ("https://docs.scipy.org/doc/numpy", None), "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), - "python": ("https://docs.python.org/3.6", None), + "python": ("https://docs.python.org/3.12", None), } linkcheck_ignore = [ @@ -105,7 +106,7 @@ master_doc = "index" # General information about the project. -project = "estimagic" +project = "optimagic" copyright = f"2019 - {year}, {author}" # noqa: A001 # The version info for the project you're documenting, acts as replacement for @@ -113,7 +114,7 @@ # built documents. # # The full version, including alpha/beta/rc tags. -release = version("estimagic").split("+")[0] +release = version("optimagic").split("+")[0] version = ".".join(release.split(".")[:2]) # The language for content autogenerated by Sphinx. Refer to documentation @@ -150,7 +151,7 @@ # List of notebooks that will not be executed. nb_execution_excludepatterns = [ # Problem with latex rendering - "how_to_generate_publication_quality_tables.ipynb", + "estimation_tables_overview.ipynb", # too long runtime "bootstrap_montecarlo_comparison.ipynb", ] @@ -192,13 +193,13 @@ # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. html_show_copyright = True -html_title = "estimagic" +html_title = "optimagic" html_theme_options = { "sidebar_hide_name": True, "navigation_with_keys": True, - "light_logo": "images/estimagic_logo.svg", - "dark_logo": "images/estimagic_logo_dark_mode.svg", + "light_logo": "images/optimagic_logo.svg", + "dark_logo": "images/optimagic_logo_dark_mode.svg", "light_css_variables": { "color-brand-primary": "#f04f43", "color-brand-content": "#f04f43", diff --git a/docs/source/development/credits.md b/docs/source/development/credits.md index 9ae9d0607..28693681e 100644 --- a/docs/source/development/credits.md +++ b/docs/source/development/credits.md @@ -1,6 +1,6 @@ # Credits -## The estimagic Team +## The optimagic Team ```{eval-rst} +---------------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ @@ -21,41 +21,47 @@ +---------------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+-------------------------------------------------------------------+ ``` -Janoś is the original developer and architect behind estimagic. All team members are -active contributors in terms of commits, advice or community building. Aida and Bahar -are supported by [TRA Modelling]. Hans-Martin supports estimagic in many ways, including -funding and great feedback from using and teaching estimagic. Ken supports estimagic -with his expertise on all numerical topics, financed a research stay at Standford for -Janoś, Sebi and Tim and organized a workshop on numerical optimization with estimagic at -Hoover Institution. +Janoś is the original developer and architect behind optimagic (formerly estimagic). All +team members are active contributors in terms of commits, advice or community building. +Hans-Martin and Ken support optimagic with funding and their expertise. ## Contributors We are grateful for many contributions from the community. In particular, we want to -thank: - -- Moritz Mendel -- Max Blesch -- Christian Zimpelmann -- Robin Musolff -- Sofia Badini -- Sofya Akimova -- Xuefei Han -- Leiqiong Wan -- Andrew Souther -- Luis Calderon -- Linda Maokomatanda -- Madhurima Chandra -- Vijaybabu Gangaprasad - -If you want to find your name here as well, please contact us or browse through our -Issues and submit a Pull Request. +thank Moritz Mendel, Max Blesch, Christian Zimpelmann, Robin Musolff, Sofia Badini, +Sofya Akimova, Xuefei Han, Leiqiong Wan, Andrew Souther, Luis Calderon, Linda +Maokomatanda, Madhurima Chandra, and Vijaybabu Gangaprasad. ## Acknowledgements -Estimagic is funded by the [TRA Modelling] (University of Bonn) as part of the -Excellence Strategy of the federal and state governments. +We thank all institutions that have funded or supported optimagic (formerly estimagic) -:::\{figure} ../\_static/images/tra_logo.png :width: 200px ::: +```{image} ../_static/images/aai-institute-logo.svg +--- +width: 185px +--- +``` + +```{image} ../_static/images/numfocus_logo.png +--- +width: 200 +--- +``` + +```{image} ../_static/images/tra_logo.png +--- +width: 240px +--- +``` + +```{image} ../_static/images/hoover_logo.png +--- +width: 192px +--- +``` -[tra modelling]: https://www.uni-bonn.de/en/research-and-teaching/research-profile/transdisciplinary-research-areas/tra-1-modelling +```{image} ../_static/images/transferlab-logo.svg +--- +width: 420px +--- +``` diff --git a/docs/source/development/eeps.md b/docs/source/development/eeps.md deleted file mode 100644 index 1165012c2..000000000 --- a/docs/source/development/eeps.md +++ /dev/null @@ -1,17 +0,0 @@ -# EEPs - -Estimagic Enhancement Proposals (EEPs) can be used to discuss and design large changes. -EEP-00 details the EEP process, the estimagic governance model and the estimagic Code of -Conduct. It is the only EEP that gets continuously updated. - -These EEPs are currently in place: - -```{toctree} ---- -maxdepth: 1 ---- -eep-00-governance-model.md -eep-01-pytrees.md -eep-02-typing.md -eep-03-alignment.md -``` diff --git a/docs/source/development/enhancement_proposals.md b/docs/source/development/enhancement_proposals.md new file mode 100644 index 000000000..d8d212aad --- /dev/null +++ b/docs/source/development/enhancement_proposals.md @@ -0,0 +1,17 @@ +# Enhancement Proposals + +optimagic Enhancement Proposals (EPs) can be used to discuss and design large changes. +EP-00 details the EP process, the optimagic governance model and the optimagic Code of +Conduct. It is the only EP that gets continuously updated. + +These EPs are currently in place: + +```{toctree} +--- +maxdepth: 1 +--- +ep-00-governance-model.md +ep-01-pytrees.md +ep-02-typing.md +ep-03-alignment.md +``` diff --git a/docs/source/development/eep-00-governance-model.md b/docs/source/development/ep-00-governance-model.md similarity index 76% rename from docs/source/development/eep-00-governance-model.md rename to docs/source/development/ep-00-governance-model.md index 7cc215c7d..7421553f8 100644 --- a/docs/source/development/eep-00-governance-model.md +++ b/docs/source/development/ep-00-governance-model.md @@ -1,6 +1,6 @@ -(eep-00)= +(ep-00)= -# EEP-00: Governance model & code of conduct +# EP-00: Governance model & code of conduct ```{eval-rst} +------------+------------------------------------------------------------------+ @@ -26,14 +26,14 @@ ## Purpose -This document formalizes the estimagic code of conduct and governance model. In case of -changes, this document can be updated following the estimagic Enhancement Proposal +This document formalizes the optimagic code of conduct and governance model. In case of +changes, this document can be updated following the optimagic Enhancement Proposal process detailed below. ```{include} ../../../CODE_OF_CONDUCT.md ``` -## estimagic governance model +## optimagic governance model ### Summary @@ -41,28 +41,28 @@ The governance model strives to be lightweight and based on [consensus](https://numpy.org/doc/stable/dev/governance/governance.html#consensus-based-decision-making-by-the-community) of all interested parties. Most work happens in GitHub issues and pull requests (regular decision process). Any interested party can voice their concerns or veto on proposed -changes. If this happens, the estimagic Enhancement Proposal (EEP) process can be used -to iterate over proposals until consesus is reached (controversial decision process). If +changes. If this happens, the optimagic Enhancement Proposal (EP) process can be used to +iterate over proposals until consesus is reached (controversial decision process). If necessary, members of the steering council can moderate heated debates and help to broker a consensus. ### Regular decision process -Most changes to estimagic are additions of new functionality or strict improvements of +Most changes to optimagic are additions of new functionality or strict improvements of existing functionality. Such changes can be discussed in GitHub issues and discussions -and implemented in pull requests. They do not require an estimagic Enhancement Proposal. +and implemented in pull requests. They do not require an optimagic Enhancement Proposal. -Before starting to work on estimagic, contributors should read +Before starting to work on optimagic, contributors should read [how to contribute](how-to) and the [styleguide](styleguide). They can also reach out to existing contributors if any help is needed or anything remains unclear. We are all happy to help onboarding new contributors in any way necessary. For example, we have given introductions to git and GitHub in the past to help people make a contribution to -estimagic. +optimagic. Pull requests should be opened as soon as work is started. They should contain a good description of the planned work such that any interested party can participate in the discussion around the changes. If planned changes turn out to be controversial, their -design should be discussed in an estimagic Enhancement Proposal before the actual work +design should be discussed in an optimagic Enhancement Proposal before the actual work starts. When the work is finished, the author of a pull request can request a review. In most cases, previous discussions will show who is a suitable reviewer. If in doubt, tag [janosg](https://github.com/janosg). Pull requests can be merged if there is at least @@ -78,29 +78,29 @@ for an excellent discussion of the burden that review comments place on maintain which might not always be obvious). Video calls can help if a discussion gets stuck. The code of conduct applies to all interactions related to code reviews. -### estimagic Enhancement Proposals (EEPs) / Controversial decision process +### optimagic Enhancement Proposals (EPs) / Controversial decision process -Large changes to estimagic can be proposed in estimagic Enhancement Proposals, short -EEPs. They serve the purpose of summarising discussions that may happen in chats, -issues, pull requests, in person, or by any other means. Simple extensions (like adding -new optimizers) do not need to be discussed with such a formal process. +Large changes to optimagic can be proposed in optimagic Enhancement Proposals, short +EPs. They serve the purpose of summarising discussions that may happen in chats, issues, +pull requests, in person, or by any other means. Simple extensions (like adding new +optimizers) do not need to be discussed with such a formal process. -EEPs are written as markdown documents that become part of the documentation. Opening an -EEP means opening a pull request that adds the markdown document to the documentation. -It is not necessary to already have a working implementations for the planned changes, -even though it might be a good idea to have rough prototypes for solutions to the most +EPs are written as markdown documents that become part of the documentation. Opening an +EP means opening a pull request that adds the markdown document to the documentation. It +is not necessary to already have a working implementations for the planned changes, even +though it might be a good idea to have rough prototypes for solutions to the most challenging parts. -If the author of an EEP feels that it is ready to be accepted they need to make a post -in the relevant [Zulip topic](https://ose.zulipchat.com) and a comment on the PR that +If the author of an EP feels that it is ready to be accepted they need to make a post in +the relevant [Zulip topic](https://ose.zulipchat.com) and a comment on the PR that contains the following information: -1. Summary of all contentious aspects of the EEP and how they have been resolved -1. Every interested party has seven days to comment on the PR proposing the EEP, either +1. Summary of all contentious aspects of the EP and how they have been resolved +1. Every interested party has seven days to comment on the PR proposing the EP, either with approval or objections. While only objections are relevant for the decision making process, approvals are a good way to signal interest in the planned change and recognize the work of the authors. -1. If there are no unresolved objections after seven days, the EEP will automatically be +1. If there are no unresolved objections after seven days, the EP will automatically be accepted and can be merged. Note that the pull requests that actually implement the proposed enhancements still @@ -108,12 +108,12 @@ require a standard review cycle. ### Steering Council -The estimagic Steering Council consists of five people who take responsibility for the -future development of estimagic and the estimagic community. Being a member of the +The optimagic Steering Council consists of five people who take responsibility for the +future development of optimagic and the optimagic community. Being a member of the steering council comes with no special rights. The main roles of the steering council are: -- Facilitate the growth of estimagic and the estimagic community by organizing community +- Facilitate the growth of optimagic and the optimagic community by organizing community events, identifying funding opportunities and improving the experience of all community members. - Develop a roadmap, break down large changes into smaller projects and find @@ -123,7 +123,7 @@ are: - Step in as moderators when discussions get heated, help to achieve consensus on controversial topics and enforce the code of conduct. -The Steering Council is elected by the estimagic community during a community meeting. +The Steering Council is elected by the optimagic community during a community meeting. Candidates need to be active community members and can be nominated by other community members or themselves until the start of the election. Nominated candidates need to @@ -135,7 +135,7 @@ Candidates can vote for themselves. Ties are resolved by a second round of votin each participant casts as many votes as there are positions left. Remaining ties are resolved by randomization. -Current memebers of the estimagic Steering Council are: +Current memebers of the optimagic Steering Council are: - [Janoś Gabler](https://github.com/janosg) - [Annica Gehlen](https://github.com/amageh) @@ -148,7 +148,7 @@ Current memebers of the estimagic Steering Council are: Community meetings can be held to elect a steering council, make changes to the governance model or code of conduct, or to make other decisions that affect the community as a whole. Moreover, they serve to keep the community updated about the -development of estimagic and get feedback. +development of optimagic and get feedback. Community meetings need to be announced via our public channels (e.g. the [zulip workspace](https://ose.zulipchat.com) or GitHub discussions) with sufficient time diff --git a/docs/source/development/eep-01-pytrees.md b/docs/source/development/ep-01-pytrees.md similarity index 99% rename from docs/source/development/eep-01-pytrees.md rename to docs/source/development/ep-01-pytrees.md index c912990ec..c04dd0fb3 100644 --- a/docs/source/development/eep-01-pytrees.md +++ b/docs/source/development/ep-01-pytrees.md @@ -1,6 +1,6 @@ -(eeppytrees)= +(eppytrees)= -# EEP-01: Pytrees +# EP-01: Pytrees ```{eval-rst} +------------+------------------------------------------------------------------+ @@ -206,10 +206,12 @@ The following entries of the output of minimize are affected by the change: - `"solution_criterion"`: The output dictionary of `crit` evaluated solution params - `solution_derivative`: Maybe we should not even have this entry. -:::\{danger} We need to discuss if and in which form we want to have a solution +```{note} +We need to discuss if and in which form we want to have a solution derivative entry. In it's current form it is useless if constraints are used. This gets worse when we allow for pytrees and translating this into a meaningful shape might be -very difficult. ::: +very difficult. +``` ### Add bounds diff --git a/docs/source/development/eep-02-typing.md b/docs/source/development/ep-02-typing.md similarity index 94% rename from docs/source/development/eep-02-typing.md rename to docs/source/development/ep-02-typing.md index 7e15608b1..dd9af67e4 100644 --- a/docs/source/development/eep-02-typing.md +++ b/docs/source/development/ep-02-typing.md @@ -1,6 +1,6 @@ (eeptyping)= -# EEP-02: Static typing +# EP-02: Static typing ```{eval-rst} +------------+------------------------------------------------------------------+ @@ -18,7 +18,7 @@ ## Abstract -This enhancement proposal explains the adoption of static typing in estimagic. The goal +This enhancement proposal explains the adoption of static typing in optimagic. The goal is to reap a number of benefits: - Users will benefit from IDE tools such as easier discoverability of options and @@ -27,7 +27,7 @@ is to reap a number of benefits: - The codebase will become more robust due to static type checking and use of stricter types in internal functions. -Achieving these goals requires more than adding type hints. estimagic is currently +Achieving these goals requires more than adding type hints. optimagic is currently mostly [stringly typed](https://wiki.c2.com/?StringlyTyped). For example, optimization algorithms are selected via strings. Another example are [constraints](https://estimagic.readthedocs.io/en/latest/how_to_guides/optimization/how_to_specify_constraints.html), @@ -91,7 +91,7 @@ updated if this proposal is accepted. consider using an immutable type with copy constructors for modified instances. Example: instances of `Algorithm` are immutable but using `Algorithm.with_option` users can create modified copies. -- The main entry point to estimagic are functions, objects are mostly used for +- The main entry point to optimagic are functions, objects are mostly used for configuration and return types. This takes the best of both worlds: we get the safety and static analysis that (in Python) can only be achieved using objects but the beginner friendliness and freedom provided by functions. Example: Having a `minimize` @@ -144,7 +144,7 @@ def least_squares_sphere(params: np.ndarray) -> dict[str, Any]: ``` Here the `"root_contributions"` are the least-squares residuals. The dictionary key -tells estimagic how to interpret the output. This is needed because estimagic has no way +tells optimagic how to interpret the output. This is needed because optimagic has no way of finding out whether a criterion function that returns a vector (or pytree) is a least-squares function or a likelihood function. Of course all specialized problems can still be solved with scalar optimizers. @@ -159,7 +159,7 @@ def logging_sphere(x: np.ndarray) -> dict[str, Any]: ``` Here `"value"` is the actual scalar criterion value. All other fields are unknown to -estimagic and therefore just logged in the database if logging is active. +optimagic and therefore just logged in the database if logging is active. The specification of likelihood functions is very analogous to least-squares functions and therefore omitted here. @@ -175,7 +175,7 @@ and therefore omitted here. **Problems** -- Most users of estimagic find it hard to write criterion functions that return the +- Most users of optimagic find it hard to write criterion functions that return the correct dictionary. Therefore, they don't use the logging feature and we often get questions about specifying least-squares problems correctly. - Internally we can make almost no assumptions about the output of a criterion function, @@ -198,10 +198,10 @@ will now be solved separately. The simplest way of specifying a least-squares function becomes: ```python -import estimagic as em +import optimagic as om -@em.mark.least_squares +@om.mark.least_squares def ls_sphere(params): return params ``` @@ -209,7 +209,7 @@ def ls_sphere(params): Analogously, the simplest way of specifying a likelihood function becomes: ```python -@em.mark.likelihood +@om.mark.likelihood def ll_sphere(params): return params**2 ``` @@ -218,7 +218,7 @@ The simplest way of specifying a scalar function stays unchanged, but optionally `mark.scalar` decorator can be used: ```python -@em.mark.scalar # this is optional +@om.mark.scalar # this is optional def sphere(params): return params @ params ``` @@ -244,10 +244,10 @@ An example of a least-squares function that also returns additional info for the file would look like this: ```python -from estimagic import FunctionValue +from optimagic import FunctionValue -@em.mark.least_squares +@om.mark.least_squares def least_squares_sphere(params): out = FunctionValue( value=params, info={"p_mean": params.mean, "p_std": params.std()} @@ -291,7 +291,7 @@ class LikelihoodFunctionValue(FunctionValue): A least-squares function could then be specified without decorator as follows: ```python -from estimagic import LeastSquaresFunctionValue +from optimagic import LeastSquaresFunctionValue def least_squares_sphere(params: np.ndarray) -> LeastSquaresFunctionValue: @@ -318,12 +318,12 @@ Currently we have four arguments of `maximize`, `minimize`, and related function let the user specify bounds: ```python -em.minimize( +om.minimize( # ... lower_bounds=params - 1, upper_bounds=params + 1, soft_lower_bounds=params - 2, - soft_lower_bounds=params + 2, + soft_upper_bounds=params + 2, # ... ) ``` @@ -341,13 +341,13 @@ Each of them is a pytree that mirrors the structure of `params` or `None` We bundle the bounds together in a `Bounds` type: ```python -bounds = em.Bounds( +bounds = om.Bounds( lower=params - 1, upper=params + 1, soft_lower=params - 2, - soft_lower=params + 2, + soft_upper=params + 2, ) -em.minimize( +om.minimize( # ... bounds=bounds, # ... @@ -417,11 +417,11 @@ Examples of the new syntax are: ```python constraints = [ - em.constraints.FixedConstraint(selector=lambda x: x[0, 5]), - em.constraints.IncreasingConstraint(selector=lambda x: x[1:4]), + om.constraints.FixedConstraint(selector=lambda x: x[0, 5]), + om.constraints.IncreasingConstraint(selector=lambda x: x[1:4]), ] -res = em.minimize( +res = om.minimize( fun=criterion, params=np.array([2.5, 1, 1, 1, 1, -2.5]), algorithm="scipy_lbfgsb", @@ -436,7 +436,7 @@ During the deprecation phase, `Constraint` will also have `loc` and `query` attr The current `cov` and `sdcorr` constraints apply to flattened covariance matrices, as well as standard deviations and flattened correlation matrices. This comes from a time -where estimagic only supported an essentially flat parameter format (`DataFrames` with +where optimagic only supported an essentially flat parameter format (`DataFrames` with `"value"` column). We can exploit the current deprecation cycle to rename the current `cov` and `sdcorr` constraints to `FlatCovConstraint` and `FlatSdcorrConstraint`. This prepares the introduction of a more natural `CovConstraint` and `SdcorrConstraint` @@ -455,7 +455,7 @@ fuzzy matching of strings. **Things we want to keep** -- Estimagic can be used just like scipy +- optimagic can be used just like scipy **Problems** @@ -485,20 +485,20 @@ algorithm interface. In a simple example, algorithm selection via algorithm classes looks as follows: ```python -em.minimize( +om.minimize( lambda x: x @ x, params=np.arange(5), - algorithm=em.algorithms.scipy_neldermead, + algorithm=om.algorithms.scipy_neldermead, ) ``` Passing a configured instance of an algorithm looks as follows: ```python -em.minimize( +om.minimize( lambda x: x @ x, params=np.arange(5), - algorithm=em.algorithms.scipy_neldermead(adaptive=True), + algorithm=om.algorithms.scipy_neldermead(adaptive=True), ) ``` @@ -538,7 +538,7 @@ sure all generated code is up-to-date in every commit. It can also be executed i [pytest hook](https://docs.pytest.org/en/7.1.x/how-to/writing_hook_functions.html) (before the collection phase) to make sure everything is up-to-date when tests run. -Users of estimagic (and their IDEs) will never know that this code was not typed in by a +Users of optimagic (and their IDEs) will never know that this code was not typed in by a human, which guarantees that autocomplete and static analysis will work without problems. @@ -566,7 +566,7 @@ fictitious list: We want the following behavior: -The user types `em.algorithms.` and autocomplete shows +The user types `om.algorithms.` and autocomplete shows | | | --------------- | @@ -580,7 +580,7 @@ The user types `em.algorithms.` and autocomplete shows A user can either select one of the algorithms (lowercase) directly or filter further by selecting a category (CamelCase). This would look as follows: -The user types `em.algorithms.GradientFree.` and autocomplete shows +The user types `om.algorithms.GradientFree.` and autocomplete shows | | | ------------ | @@ -619,7 +619,7 @@ class GradientBasedAlgorithms: slsqp: Type[SLSQP] = SLSQP @property - def All(self) -> List[em.typing.Algorithm]: + def All(self) -> List[om.typing.Algorithm]: return [LBFGS, SLSQP] @@ -629,7 +629,7 @@ class GradientFreeAlgorithms: bobyqa: Type[Bobyqa] = Bobyqa @property - def All(self) -> List[em.typing.Algorithm]: + def All(self) -> List[om.typing.Algorithm]: return [NelderMead, Bobyqa] @@ -649,15 +649,15 @@ class Algorithms: return GradientFreeAlgorithms() @property - def All(self) -> List[em.typing.Algorithm]: + def All(self) -> List[om.typing.Algorithm]: return [LBFGS, SLSQP, NelderMead, Bobyqa] ``` If implemented by hand, this would require an enormous amount of typing and introduce a -very high maintenance burden. Whenever a new algorithm was added to estimagic, we would +very high maintenance burden. Whenever a new algorithm was added to optimagic, we would have to register it in multiple nested dataclasses. -The code generation approach detailed in the previous section can solve this problem. +The code generation approach detailed in the previous section can solve this problom. While it might have been overkill to achieve basic autocomplete, it is justified to achieve this filtering behavior. How the relevant information for filtering (e.g. whether an algorithm is gradient based) is collected, will be discussed in @@ -673,7 +673,7 @@ later as we see fit. ### Algorithm options -Algorithm options refer to options that are not handled by estimagic but directly by the +Algorithm options refer to options that are not handled by optimagic but directly by the algorithms. Examples are convergence criteria, stopping criteria and advanced configuration of algorithms. Some of them are supported by many algorithms (e.g. stopping after a maximum number of function evaluations is reached), some are supported @@ -687,7 +687,7 @@ options (e.g. there is simply no trustregion radius in a genetic algorithm), we far in harmonizing `algo_options` across optimizers: 1. Options that are the same in spirit (e.g. stop after a specific number of iterations) - get the same name across all optimizers wrapped in estimagic. Most of them even get + get the same name across all optimizers wrapped in optimagic. Most of them even get the same default value. 1. Options that have non-descriptive (and often heavily abbreviated) names in their original implementation get more readable names, even if they appear only in a single @@ -746,7 +746,7 @@ Python variable names. works especially well to distinguish stopping options and convergence criteria from other tuning parameters of the algorithms. However, it would be enough to keep them as a naming convention if we find it hard to support the `.` notation. -- All options are documented in the estimagic documentation, i.e. we do not link to the +- All options are documented in the optimagic documentation, i.e. we do not link to the docs of original packages. Now they will also be discoverable in an IDE. **Problems** @@ -773,7 +773,7 @@ selected algorithm. When creating the instance, they have autocompletion for all supported by the selected algorithm. `Algorithm`s are immutable. ```python -algo = em.algorithms.scipy_lbfgsb( +algo = om.algorithms.scipy_lbfgsb( stopping_max_iterations=1000, stopping_max_criterion_evaluations=1500, convergence_relative_criterion_tolerance=1e-6, @@ -792,7 +792,7 @@ instance by using the `with_option` method. ```python # using copy constructors to create variants -base_algo = em.algorithms.fides(stopping_max_iterations=1000) +base_algo = om.algorithms.fides(stopping_max_iterations=1000) algorithms = [base_algo.with_option(initial_radius=r) for r in [0.1, 0.2, 0.5]] for algo in algorithms: @@ -814,7 +814,7 @@ We can provide additional methods `with_stopping` and `with_convergence` that ca ```python # using copy constructors for better namespaces algo = ( - em.algorithms.scipy_lbfgsb() + om.algorithms.scipy_lbfgsb() .with_stopping( max_iterations=1000, max_criterion_evaluations=1500, @@ -846,7 +846,7 @@ guarantees that the specified options are compatible with the selected algorithm The previous example continues to work. Examples of the new possibilities are: ```python -options = em.AlgorithmOptions( +options = om.AlgorithmOptions( stopping_max_iterations=1000, stopping_max_criterion_evaluations=1500, convergence_relative_criterion_tolerance=1e-6, @@ -858,7 +858,7 @@ options = em.AlgorithmOptions( minimize( # ... - algorithm=em.algorithms.scipy_lbfgsb, + algorithm=om.algorithms.scipy_lbfgsb, algo_options=options, # ... ) @@ -874,7 +874,7 @@ of dynamic signature creation. For more details, see the discussions about the ### Custom derivatives -Providing custom derivatives to estimagic is slightly complicated because we support +Providing custom derivatives to optimagic is slightly complicated because we support scalar, likelihood and least-squares problems in the same interface. Moreover, we allow to either provide a `derivative` function or a joint `criterion_and_derivative` function that allow users to exploit synergies between evaluating the criterion and the @@ -910,10 +910,10 @@ returns a tuple of the criterion value and the derivative instead. **Problems** - A dict with required keys is brittle -- Autodiff needs to be handled completely outside of estimagic +- Autodiff needs to be handled completely outside of optimagic - The names `criterion`, `derivative` and `criterion_and_derivative` are not aligned with scipy and very long. -- Providing derivatives to estimagic is perceived as complicated and confusing. +- Providing derivatives to optimagic is perceived as complicated and confusing. #### Proposal @@ -924,7 +924,7 @@ The following section uses the new names `fun`, `jac` and `fun_and_jac` instead To improve the integration with modern automatic differentiation frameworks, `jac` or `fun_and_jac` can also be a string `"jax"` or a more autocomplete friendly enum -`em.autodiff_backend.JAX`. This can be used to signal that the objective function is jax +`om.autodiff_backend.JAX`. This can be used to signal that the objective function is jax compatible and jax should be used to calculate its derivatives. In the long run we can add PyTorch support and more. Since this is mostly about a signal of compatibility, it would be enough to set one of the two arguments to `"jax"`, the other one can be left at @@ -932,44 +932,44 @@ would be enough to set one of the two arguments to `"jax"`, the other one can be ```python import jax.numpy as jnp -import estimagic as em +import optimagic as om def jax_sphere(x): return jnp.dot(x, x) -res = em.minimize( +res = om.minimize( fun=jax_sphere, params=jnp.arange(5), - algorithm=em.algorithms.scipy_lbfgsb, + algorithm=om.algorithms.scipy_lbfgsb, jac="jax", ) ``` If a custom callable is provided as `jac` or `fun_and_jac`, it needs to be decorated -with `@em.mark.least_squares` or `em.mark.likelihood` if it is not the gradient of a -scalar function values. Using the `em.mark.scalar` decorator is optional. For a simple +with `@om.mark.least_squares` or `om.mark.likelihood` if it is not the gradient of a +scalar function values. Using the `om.mark.scalar` decorator is optional. For a simple least-squares problem this looks as follows: ```python import numpy as np -@em.mark.least_squares +@om.mark.least_squares def ls_sphere(params): return params -@em.mark.least_squares +@om.mark.least_squares def ls_sphere_jac(params): return np.eye(len(params)) -res = em.minimize( +res = om.minimize( fun=ls_sphere, params=np.arange(5), - algorithm=em.algorithms.scipy_ls_lm, + algorithm=om.algorithms.scipy_ls_lm, jac=ls_sphere_jac, ) ``` @@ -977,26 +977,26 @@ res = em.minimize( Note that here we have a least-squares problem and solve it with a least-squares optimizer. However, any least-squares problem can also be solved with scalar optimizers. -While estimagic could convert the least-squares derivative to the gradient of the scalar +While optimagic could convert the least-squares derivative to the gradient of the scalar function value, this is generally inefficient. Therefore, a user can provide multiple callables of the objective function in such a case, so we can pick the best one for the chosen optimizer. ```python -@em.mark.scalar +@om.mark.scalar def sphere_grad(params): return 2 * params -res = em.minimize( +res = om.minimize( fun=ls_sphere, params=np.arange(5), - algorithm=em.algorithms.scipy_lbfgsb, + algorithm=om.algorithms.scipy_lbfgsb, jac=[ls_sphere_jac, sphere_grad], ) ``` -Since a scalar optimizer was chosen to solve the least-squares problem, estimagic would +Since a scalar optimizer was chosen to solve the least-squares problem, optimagic would pick the `sphere_grad` as derivative. If a leas-squares solver was chosen, we would use `ls_sphere_jac`. @@ -1012,7 +1012,7 @@ configure the behavior with an option dictionary. Examples are: - `error_handling` (`Literal["raise", "continue"]`) and `error_penalty` (dict) - `multistart` (`bool`) and `multistart_options` -Moreover we have option dictionaries whenever we have nested invocations of estimagic +Moreover we have option dictionaries whenever we have nested invocations of optimagic functions. Examples are: - `numdiff_options` in `minimize` and `maximize` @@ -1047,7 +1047,7 @@ After the changes, `logging` can be any of the following: - `False` (or anything Falsy): No logging is used. - A `str` or `pathlib.Path`: Logging is used at default options. -- An instance of `estimagic.Logger`. There will be multiple subclasses, e.g. +- An instance of `optimagic.Logger`. There will be multiple subclasses, e.g. `SqliteLogger` which allow us to switch out the logging backend. Each subclass might have different optional arguments. @@ -1057,7 +1057,7 @@ supported during a deprecation cycle. ##### Scaling, error handling and multistart In contrast to logging, scaling, error handling and multistart are deeply baked into -estimagic's minimize function. Therefore, it does not make sense to create abstractions +optimagic's minimize function. Therefore, it does not make sense to create abstractions for these features that would make them replaceable components that can be switched out for other implementations by advanced users. Most of these features are already perceived as advanced and allow for a lot of configuration. @@ -1083,8 +1083,8 @@ dataclasses as alternative. #### Current situation Currently, algorithms are defined as `minimize` functions that are decorated with -`em.mark_minimizer`. The `minimize` function returns a dictionary with a few mandatory -and several optional keys. Algorithms can provide information to estimagic in two ways: +`om.mark_minimizer`. The `minimize` function returns a dictionary with a few mandatory +and several optional keys. Algorithms can provide information to optimagic in two ways: 1. The signature of the minimize function signals whether the algorithm needs derivatives and whether it supports bounds and nonlinear constraints. Moreover, it @@ -1176,7 +1176,7 @@ class AlgoInfo(NamedTuple): - Since we read a lot of information from function signatures (as opposed to registering options somewhere), there is no duplicated information. If we change the approach to collecting information, we still need to ensure there is no duplication or possibility - to provide wrong information to estimagic. + to provide wrong information to optimagic. **Problems** @@ -1193,10 +1193,10 @@ class AlgoInfo(NamedTuple): We first show the proposed new algorithm interface and discuss the changes later. ```python -@em.mark.minimizer( +@om.mark.minimizer( name="scipy_neldermead", needs_scaling=False, - problem_type=em.ProblemType.Scalar, + problem_type=om.ProblemType.Scalar, is_available=IS_SCIPY_AVAILABLE, is_global=False, disable_history=False, @@ -1222,7 +1222,6 @@ class ScipyNelderMead(Algorithm): def _solve_internal_problem( self, problem: InternalProblem, x0: NDArray[float] ) -> InternalOptimizeResult: - options = { "maxiter": self.stopping_max_iterations, "maxfev": self.stopping_max_criterion_evaluations, @@ -1232,9 +1231,9 @@ class ScipyNelderMead(Algorithm): } res = minimize( - fun=problem.scalar.fun, + fun=problom.scalar.fun, x0=x, - bounds=_get_scipy_bounds(problem.bounds), + bounds=_get_scipy_bounds(problom.bounds), method="Nelder-Mead", options=options, ) @@ -1258,7 +1257,7 @@ class ScipyNelderMead(Algorithm): 1. The minimize function returns an `InternalOptimizeResult` instead of a dictionary. The copy constructors (`with_option`, `with_convergence`, and `with_stopping`) are -inherited from `estimagic.Algorithm`. This means, that they will have `**kwargs` as +inherited from `optimagic.Algorithm`. This means, that they will have `**kwargs` as signature and thus do not support autocomplete. However, they can check that all specified options are actually in the `__dataclass_fields__` and thus provide feedback before an optimization is run. @@ -1284,7 +1283,7 @@ the objective function and its derivatives. from numpy.typing import NDArray from dataclasses import dataclass from typing import Callable, Tuple -import estimagic as em +import optimagic as om @dataclass(frozen=True) @@ -1313,9 +1312,9 @@ class InternalProblem: scalar: ScalarProblemFunctions least_squares: LeastSquaresProblemFunctions likelihood: LikelihoodProblemFunctions - bounds: em.Bounds | None - linear_constraints: list[em.LinearConstraint] | None - nonlinear_constraints: list[em.NonlinearConstraint] | None + bounds: om.Bounds | None + linear_constraints: list[om.LinearConstraint] | None + nonlinear_constraints: list[om.NonlinearConstraint] | None ``` The `InternalOptimizeResult` formalizes the current dictionary solution: @@ -1347,9 +1346,9 @@ following advantages and disadvantages: - Easier for beginners as no subtle concepts (such as the difference between instance and class variables) are involved - Very easy way to provide default values for some of the collected variables -- Every user of estimagic is familiar with `mark` decorators +- Every user of optimagic is familiar with `mark` decorators - Autocomplete while filling out the arguments of the mark decorator -- Very clear visual separation of algorithm options and attributes estimagic needs to +- Very clear visual separation of algorithm options and attributes optimagic needs to know about. **Advantages of class variable approach** @@ -1363,7 +1362,7 @@ welcome. ## Numerical differentiation -#### Current situation +### Current situation The following proposal applies to the functions `first_derivative` and `second_derivative`. Both functions have an interface that has grown over time and both @@ -1388,7 +1387,7 @@ but has not produced convincing results in benchmarks. **Things we want to keep** - `params` and function values can be pytrees -- support for estimagic `criterion` functions (now functions that return +- support for optimagic `criterion` functions (now functions that return `FunctionValue`) - Many optional arguments to influence the details of the numerical differentiation - Rich output format that helps to get insights on the precision of the numerical @@ -1407,9 +1406,9 @@ but has not produced convincing results in benchmarks. - Many users expect the output of a function for numerical differentiation to be just the gradient, jacobian or hessian, not a more complex result object. -#### Proposal +### Proposal -##### Separation of calculations and pytree handling +#### Separation of calculations and pytree handling As in numerical optimization, we should implement the core functionality for first and second derivative for functions that map from 1-Dimensional numpy arrays to @@ -1417,7 +1416,7 @@ second derivative for functions that map from 1-Dimensional numpy arrays to (e.g. functions that return a `FunctionValue`) should be done outside of the core functions. -##### Deprecate Richardson Extrapolation (and prepare alternatives) +#### Deprecate Richardson Extrapolation (and prepare alternatives) The goal of implementing Richardson Extrapolation was to get more precise estimates of numerical derivatives when it is hard to find an optimal step size. Example use-cases we @@ -1457,14 +1456,14 @@ Richardson extrapolation was only completed for first derivatives, even though i already prepared in the interface for second derivatives. ``` -##### Better `NumdiffResult` object +#### Better `NumdiffResult` object The result dictionary will be replaced by a `NumdiffResult` object. All arguments that govern which results are stored will be removed. If some of the formerly optional results require extra computation that we wanted to avoid by making them optional, they can be properties or methods of the result object. -##### Jax inspired high-level interfaces +#### Jax inspired high-level interfaces Since our `first_derivative` and `second_derivative` functions need to fulfill very specific requirements for use during optimization, they need to return a complex result @@ -1490,7 +1489,7 @@ All of these will be very simple wrappers around `first_derivative` and #### Current situation -As other functions in estimagic, `get_benchmark_problems` follows a design where +As other functions in optimagic, `get_benchmark_problems` follows a design where behavior can be switched on by a bool and configured by an options dictionary. The following arguments are related to this: @@ -1540,7 +1539,6 @@ FvalType = TypeVar("FvalType", bound=float | NDArray[float]) class BenchmarkNoise(ABC): - @abstractmethod def draw_noise( self, fval: FvalType, params: NDArray, size: int, rng: np.random.Generator @@ -1713,12 +1711,12 @@ the realease of `0.5.0`. - Returning a `dict` in the objective function io deprecated. Return `FunctionValue` instead. In addition, likelihood and least-squares problems need to be decorated with - `em.mark.likelihood` and `em.mark_least_squares`. + `om.mark.likelihood` and `om.mark_least_squares`. - The arguments `lower_bounds`, `upper_bounds`, `soft_lower_bounds` and `soft_upper_bounds` are deprecated. Use `bounds` instead. `bounds` can be - `estimagic.Bounds` or `scipy.optimize.Bounds` objects. + `optimagic.Bounds` or `scipy.optimize.Bounds` objects. - Specifying constraints with dictionaries is deprecated. Use the corresponding subclass - of `em.constraints.Constraint` instead. In addition, all selection methods except for + of `om.constraints.Constraint` instead. In addition, all selection methods except for `selector` are deprecated. - The `covariance` constraint is renamed to `FlatCovConstraint` and the `sdcorr` constraint is renamed to `FlatSdcorrConstraint` to prepare the introduction of more diff --git a/docs/source/development/eep-03-alignment.md b/docs/source/development/ep-03-alignment.md similarity index 94% rename from docs/source/development/eep-03-alignment.md rename to docs/source/development/ep-03-alignment.md index fe699e4fb..7c8d03ed6 100644 --- a/docs/source/development/eep-03-alignment.md +++ b/docs/source/development/ep-03-alignment.md @@ -1,6 +1,6 @@ (eepalignment)= -# EEP-03: Alignment with SciPy +# EP-03: Alignment with SciPy ```{eval-rst} +------------+------------------------------------------------------------------+ @@ -18,22 +18,22 @@ ## Abstract -This enhancement proposal explains how we will better align estimagic with +This enhancement proposal explains how we will better align optimagic with `scipy.minimize`. Scipy is the most widely used optimizer library in Python and most of our new users are switching over from SciPy. The goal is therefore simple: Make it as easy as possible for SciPy users to use -estimagic. In most cases this means that the only thing that has to be changed is the +optimagic. In most cases this means that the only thing that has to be changed is the import statement for the `minimize` function: ```python # from scipy.optimize import minimize -from estimagic import minimize +from optimagic import minimize ``` ## Design goals -- If we can make code written for SciPy run with estimagic, we should do so +- If we can make code written for SciPy run with optimagic, we should do so - If we cannot make it run, the user should get a helpful error message that explains how the code needs to be adjusted. @@ -75,7 +75,7 @@ Instead we can provide aliases for those. ## Additional aliases -To make it even easier for SciPy users to switch to estimagic, we can provide additional +To make it even easier for SciPy users to switch to optimagic, we can provide additional aliases in `minimize` and `maximize` that let them used their SciPy code without changes or help to adjust it by showing good error messages. The following arguments are relevant: @@ -105,7 +105,7 @@ relevant: Currently we try to align default values for convergence criteria and other algorithm options across algorithms and even across optimizer packages. This means that sometimes -algorithms that are used via estimagic produce different results than the same algorithm +algorithms that are used via optimagic produce different results than the same algorithm used via SciPy or other packages. Moreover, it is possible that we deviate from algorithm options that the original diff --git a/docs/source/development/how-to.md b/docs/source/development/how_to_contribute.md similarity index 82% rename from docs/source/development/how-to.md rename to docs/source/development/how_to_contribute.md index 9bf2d3866..a34a6ec24 100644 --- a/docs/source/development/how-to.md +++ b/docs/source/development/how_to_contribute.md @@ -1,17 +1,19 @@ +(how-to-contribute)= + # How to contribute ## 1. Intro We welcome and greatly appreciate contributions of all forms and sizes! Whether it's -updating the online documentation, adding small extensions, or implementing new -features, every effort is valued. +updating the documentation, adding small extensions, or implementing new features, every +effort is valued. For substantial changes, please contact us in advance. This allows us to discuss your ideas and guide the development process from the beginning. You can start a conversation by posting an issue on GitHub or by emailing [janosg](https://github.com/janosg). To get familiar with the codebase, we recommend checking out our -[issue tracker](https://github.com/OpenSourceEconomics/estimagic/issues) for some +[issue tracker](https://github.com/OpenSourceEconomics/optimagic/issues) for some immediate and clearly defined tasks. ## 2. Before you start @@ -20,7 +22,7 @@ Once you've decided to contribute, please review the {ref}`style_guide` (see the page) to ensure your work aligns with the project's coding standards. We manage new features through Pull Requests (PRs). Contributors work on their local -copy of estimagic, modifying and extending the codebase there, before opening a PR to +copy of optimagic, modifying and extending the codebase there, before opening a PR to propose merging their changes into the main branch. Regular contributors gain push access to unprotected branches, which simplifies the @@ -28,26 +30,26 @@ contribution process (see Notes below). ## 3. Step-by-step guide -1. Fork the [estimagic repository](https://github.com/OpenSourceEconomics/estimagic/). +1. Fork the [optimagic repository](https://github.com/OpenSourceEconomics/optimagic/). This action creates a copy of the repository with write access for you. ```{note} -For regular contributors: **Clone** the [repository](https://github.com/OpenSourceEconomics/estimagic/) to your local machine and create a new branch for implementing your changes. You can push your branch directly to the remote estimagic repository and open a PR from there. +For regular contributors: **Clone** the [repository](https://github.com/OpenSourceEconomics/optimagic/) to your local machine and create a new branch for implementing your changes. You can push your branch directly to the remote optimagic repository and open a PR from there. ``` 2. Clone your forked repository to your disk. This is where you'll make all your changes. 1. Open your terminal and execute the following commands from the root directory of your - local estimagic repository: + local optimagic repository: ```console $ conda env create -f environment.yml - $ conda activate estimagic + $ conda activate optimagic $ pre-commit install ``` - These commands install estimagic in editable mode and activate pre-commit hooks for + These commands install optimagic in editable mode and activate pre-commit hooks for linting and style formatting. 1. Implement your fix or feature. Use git to add, commit, and push your changes to the @@ -59,7 +61,7 @@ For regular contributors: **Clone** the [repository](https://github.com/OpenSour ensure compatibility with the existing codebase and employ [pre-commit hooks](https://effective-programming-practices.vercel.app/git/pre_commits/objectives_materials.html) to maintain quality and adherence to our style guidelines. Opening a PR (see - paragraph 7 below) triggers estimagic's + paragraph 7 below) triggers optimagic's [Continuous Integration (CI)](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration) workflow, which runs the full `pytest` suite, pre-commit hooks, and other checks on a remote server. @@ -80,12 +82,12 @@ Skip the next paragraph if you haven't worked on the documentation. ``` 6. Assuming you have updated the documentation, verify that it builds correctly. From - the root directory of your local estimagic repo, navigate to the docs folder and set - up the estimagic-docs environment: + the root directory of your local optimagic repo, navigate to the docs folder and set + up the optimagic-docs environment: ```console $ conda env create -f rtd_environment.yml - $ conda activate estimagic-docs + $ conda activate optimagic-docs ``` Inside the `docs` folder, run: @@ -104,11 +106,11 @@ Skip the next paragraph if you haven't worked on the documentation. your fork. A banner on your fork's GitHub repository will prompt you to open a PR. ```{note} - Regular contributors with push access can directly push their local branch to the remote estimagic repository and initiate a PR from there. + Regular contributors with push access can directly push their local branch to the remote optimagic repository and initiate a PR from there. ``` - Follow the steps outlined in the estimagic - [PR template](https://github.com/OpenSourceEconomics/estimagic/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md) + Follow the steps outlined in the optimagic + [PR template](https://github.com/OpenSourceEconomics/optimagic/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md) to describe your contribution, the problem it addresses, and your proposed solution. Opening a PR initiates a complete CI run, including the `pytest` suite, linters, code @@ -120,4 +122,4 @@ Skip the next paragraph if you haven't worked on the documentation. any feedback or suggestions by making the necessary changes and committing them. 1. After your PR is approved, one of the main contributors will merge it into - estimagic's main branch. + optimagic's main branch. diff --git a/docs/source/development/index.md b/docs/source/development/index.md index ff8313761..4a3be1987 100644 --- a/docs/source/development/index.md +++ b/docs/source/development/index.md @@ -5,9 +5,9 @@ maxdepth: 1 --- code_of_conduct -how-to +how_to_contribute styleguide -eeps +enhancement_proposals credits changes ``` diff --git a/docs/source/development/styleguide.md b/docs/source/development/styleguide.md index 398b1f79a..e8cfc8dfb 100644 --- a/docs/source/development/styleguide.md +++ b/docs/source/development/styleguide.md @@ -9,12 +9,6 @@ Your contribution should fulfill the criteria provided below. - Functions have no side effect. : If you modify a mutable argument, make a copy at the beginning of the function. -- Deep modules. : This is a term coined by - [John Ousterhout](https://www.youtube.com/watch?v=bmSAYlu0NcY). A deep module is a - module that has just one public function. This function calls the private functions - (i.e. functions that start with an underscore) defined further down in the module and - reads almost like a table of contents to the whole module. - - Use good names for functions and variables : *"You should name a variable using the same care with which you name a first-born child."*, Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship. @@ -34,6 +28,50 @@ Your contribution should fulfill the criteria provided below. and `minimize` can have very short names. At a lower level of abstraction you typically need more words to describe what a function does. +- User facing functions should be generous regarding their input type. Example: the + `algorithm` argument can be a string, `Algorithm` class or `Algorithm` instance. The + `algo_options` can be an `AlgorithmOptions` object or a dictionary of keyword + arguments. + +- User facing functions should be strict about their output types. A strict output type + does not just mean that the output type is known (and not a generous Union), but that + it is a proper type that enables static analysis for available attributes. Example: + whenever possible, public functions should not return dicts but proper result types + (e.g. `OptimizeResult`, `NumdiffResult`, ...) + +- Internal functions should be strict about input and output types; Typically, a public + function will check all arguments, convert them to a proper type and then call an + internal function. Example: `minimize` will convert any valid value for `algorithm` + into an `Algorithm` instance and then call an internal function with that type. + +- Fixed field types should only be used if all fields are known. An example where this + is not the case are collections of benchmark problems, where the set of fields depends + on the selected benchmark sets and other things. In such situations, dictionaries that + map strings to BenchmarkProblem objects are a good idea. + +- Think about autocomplete! If want to accept a string as argument (e.g. an algorithm + name) also accept input types that are more amenable to static analysis and offer + better autocomplete. + +- Whenever possible, use immutable types. Whenever things need to be changeable, + consider using an immutable type with copy constructors for modified instances. + Example: instances of `Algorithm` are immutable but using `Algorithm.with_option` + users can create modified copies. + +- The main entry point to optimagic are functions, objects are mostly used for + configuration and return types. This takes the best of both worlds: we get the safety + and static analysis that (in Python) can only be achieved using objects but the + beginner friendliness and freedom provided by functions. Example: Having a `minimize` + function, it is very easy to add the possibility of running minimizations with + multiple algorithms in parallel and returning the best value. Having a `.solve` method + on an algorithm object would require a whole new interface for this. + +- Deep modules. : This is a term coined by + [John Ousterhout](https://www.youtube.com/watch?v=bmSAYlu0NcY). A deep module is a + module that has just one public function. This function calls the private functions + (i.e. functions that start with an underscore) defined further down in the module and + reads almost like a table of contents to the whole module. + - Never import a private function in another module : By following this strictly, you can be sure that you can rename or refactor private functions without looking at other modules. Of course it is also not a solution to copy paste the function! If you would @@ -45,13 +83,12 @@ Your contribution should fulfill the criteria provided below. are in doubt. Example: ```python - def ordered_logit(formula, data, dashboard=False): + def ordered_logit(formula, data): """Estimate an ordered probit model with maximum likelihood. Args: formula (str): A patsy formula. data (str): A pandas DataFrame. - dashboard (bool): Switch on the dashboard. Returns: res: optimization result. @@ -64,15 +101,13 @@ Your contribution should fulfill the criteria provided below. concisely what the function does. The one liner should be in imperative mode, i.e. not "This function does" ..." , but "Do ..." and end with a period. -- Unit tests. : If you write a small helper whose interface might change during +- Unit tests : If you write a small helper whose interface might change during refactoring, it is sufficient if the function that calls it is tested. But all functions that are exposed to the user must have unit tests. -- PEP8 compliant and black formatted (we check this automatically). : We make this such - a hard requirement because it's boring and we don't want to bother about it in code - reviews. Not because we think that all PEP8 compliant code is automatically good. - Watch [this video](https://www.youtube.com/watch?v=wf-BqAjZb8M) if you haven't seen it - yet. +- Enable pre-commit hooks by executing `pre-commit install` in a terminal in the root of + the optimagic repository. This makes sure that your formatting is consistent with what + we expect. - Use `pathlib` for all file paths operations. : You can find the pathlib documentation [here](https://docs.python.org/3/library/pathlib.html) @@ -80,10 +115,6 @@ Your contribution should fulfill the criteria provided below. - Object serialization. : Pickling and unpickling of DataFrames should be done with `pd.read_pickle` and `pd.to_pickle`. -- We prefer a functional style over object oriented programming. : Unless you have very - good reasons for writing a class, we prefer you don't do it. You might want to watch - [this](https://www.youtube.com/watch?v=o9pEzgHorH0) - - Don't use global variables unless absolutely necessary : Exceptions are global variables from a config file that replace magic numbers. Never use mutable global variables! @@ -94,15 +125,4 @@ Your contribution should fulfill the criteria provided below. [Sphinx](https://www.sphinx-doc.org/en/master/) and written in **Markedly Structured Text.** How-to guides are usually Jupyter notebooks. -- Purpose of documents. : Our documentation is inspired by the - [system](https://documentation.divio.com/) developed by Daniele Procida. - - > - How-to guides are problem-oriented and show how to achieved specific tasks. - > - Explanations contain information on theoretical concepts underlying estimagic, - > such as numerical differentiation and moment-based estimation. - > - The API Reference section contains auto-generated API reference documentation and - > provides additional details about the implementation. - -- Headings. : Only the first letter of a title is capitalized. - -- Format. : The code formatting in .md files is ensured by blacken-docs. +- The documentation follows the [diataxis](https://diataxis.fr) framework. diff --git a/docs/source/explanations/inference/bootstrap_ci.md b/docs/source/estimagic/explanation/bootstrap_ci.md similarity index 100% rename from docs/source/explanations/inference/bootstrap_ci.md rename to docs/source/estimagic/explanation/bootstrap_ci.md diff --git a/docs/source/explanations/inference/bootstrap_montecarlo_comparison.ipynb b/docs/source/estimagic/explanation/bootstrap_montecarlo_comparison.ipynb similarity index 100% rename from docs/source/explanations/inference/bootstrap_montecarlo_comparison.ipynb rename to docs/source/estimagic/explanation/bootstrap_montecarlo_comparison.ipynb diff --git a/docs/source/explanations/inference/cluster_robust_likelihood_inference.md b/docs/source/estimagic/explanation/cluster_robust_likelihood_inference.md similarity index 100% rename from docs/source/explanations/inference/cluster_robust_likelihood_inference.md rename to docs/source/estimagic/explanation/cluster_robust_likelihood_inference.md diff --git a/docs/source/explanations/inference/index.md b/docs/source/estimagic/explanation/index.md similarity index 61% rename from docs/source/explanations/inference/index.md rename to docs/source/estimagic/explanation/index.md index d96a559f8..6cd5f49b9 100644 --- a/docs/source/explanations/inference/index.md +++ b/docs/source/estimagic/explanation/index.md @@ -1,4 +1,4 @@ -# Inference +# Explanation ```{toctree} --- @@ -6,5 +6,5 @@ maxdepth: 1 --- bootstrap_ci bootstrap_montecarlo_comparison -cluster_robust_likelihood_inference.md +cluster_robust_likelihood_inference ``` diff --git a/docs/source/estimagic/index.md b/docs/source/estimagic/index.md new file mode 100644 index 000000000..faa92c381 --- /dev/null +++ b/docs/source/estimagic/index.md @@ -0,0 +1,95 @@ +(estimagic)= + +# Estimagic + +*estimagic* is a subpackage of *optimagic* that helps you to fit nonlinear statistical +models to data and perform inference on the estimated parameters. + +As a user, you need to code up the objective function that defines the estimator. This +is either a likelihood (ML) function or a Method of Simulated Moments (MSM) objective +function. Everything else is done by *estimagic*. + +Everything else means: + +- Optimize your objective function +- Calculate asymptotic or bootstrapped standard errors and confidence intervals +- Create publication quality tables +- Perform sensitivity analysis on MSM models + +`````{grid} 1 2 2 2 +--- +gutter: 3 +--- +````{grid-item-card} +:text-align: center +:img-top: ../_static/images/light-bulb.svg +:class-img-top: index-card-image +:shadow: md + +```{button-link} tutorials/index.html +--- +click-parent: +ref-type: ref +class: stretched-link index-card-link sd-text-primary +--- +Tutorials +``` + +New users of estimagic should read this first. + +```` + + + +````{grid-item-card} +:text-align: center +:img-top: ../_static/images/books.svg +:class-img-top: index-card-image +:shadow: md + +```{button-link} explanation/index.html +--- +click-parent: +ref-type: ref +class: stretched-link index-card-link sd-text-primary +--- +Explanations +``` + +Background information on key topics central to the package. + +```` + +````{grid-item-card} +:text-align: center +:columns: 12 +:img-top: ../_static/images/coding.svg +:class-img-top: index-card-image +:shadow: md + +```{button-link} reference/index.html +--- +click-parent: +ref-type: ref +class: stretched-link index-card-link sd-text-primary +--- +API Reference +``` + +Detailed description of the estimagic API. + +```` + + + +````` + +```{toctree} +--- +hidden: true +maxdepth: 1 +--- +tutorials/index +explanation/index +reference/index +``` diff --git a/docs/source/estimagic/reference/index.md b/docs/source/estimagic/reference/index.md new file mode 100644 index 000000000..aec1c4100 --- /dev/null +++ b/docs/source/estimagic/reference/index.md @@ -0,0 +1,95 @@ +# estimagic API + +```{eval-rst} +.. currentmodule:: estimagic +``` + +(estimation)= + +## Estimation + +```{eval-rst} +.. dropdown:: estimate_ml + + .. autofunction:: estimate_ml + +``` + +```{eval-rst} +.. dropdown:: estimate_msm + + .. autofunction:: estimate_msm + +``` + +```{eval-rst} +.. dropdown:: get_moments_cov + + .. autofunction:: get_moments_cov + +``` + +```{eval-rst} +.. dropdown:: lollipop_plot + + .. autofunction:: lollipop_plot + +``` + +```{eval-rst} +.. dropdown:: estimation_table + + .. autofunction:: estimation_table + +``` + +```{eval-rst} +.. dropdown:: render_html + + .. autofunction:: render_html + +``` + +```{eval-rst} +.. dropdown:: render_latex + + .. autofunction:: render_latex + +``` + +```{eval-rst} +.. dropdown:: LikelihoodResult + + .. autoclass:: LikelihoodResult + :members: + +``` + +```{eval-rst} +.. dropdown:: MomentsResult + + .. autoclass:: MomentsResult + :members: + + + +``` + +(bootstrap)= + +## Bootstrap + +```{eval-rst} +.. dropdown:: bootstrap + + .. autofunction:: bootstrap +``` + +```{eval-rst} +.. dropdown:: BootstrapResult + + .. autoclass:: BootstrapResult + :members: + + +``` diff --git a/docs/source/estimagic/tutorials/bootstrap_overview.ipynb b/docs/source/estimagic/tutorials/bootstrap_overview.ipynb new file mode 100644 index 000000000..7d5121f41 --- /dev/null +++ b/docs/source/estimagic/tutorials/bootstrap_overview.ipynb @@ -0,0 +1,413 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Bootstrap Tutorial\n", + "\n", + "This notebook contains a tutorial on how to use the bootstrap functionality provided by estimagic. We start with the simplest possible example of calculating standard errors and confidence intervals for an OLS estimator without as well as with clustering. Then we progress to more advanced examples.\n", + "\n", + "In the example here, we will work with the \"exercise\" example dataset taken from the seaborn library.\n", + "\n", + "The working example will be a linear regression to investigate the effects of exercise time on pulse." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import estimagic as em\n", + "import numpy as np\n", + "import pandas as pd\n", + "import seaborn as sns\n", + "import statsmodels.api as sm" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prepare the dataset" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "df = sns.load_dataset(\"exercise\", index_col=0)\n", + "replacements = {\"1 min\": 1, \"15 min\": 15, \"30 min\": 30}\n", + "df = df.replace({\"time\": replacements})\n", + "df[\"constant\"] = 1\n", + "\n", + "df.head()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Doing a very simple bootstrap" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The first thing we need is a function that calculates the bootstrap outcome, given an empirical or re-sampled dataset. The bootstrap outcome is the quantity for which you want to calculate standard errors and confidence intervals. In most applications those are just parameter estimates.\n", + "\n", + "In our case, we want to regress \"pulse\" on \"time\" and a constant. Our outcome function looks as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def ols_fit(data):\n", + " y = data[\"pulse\"]\n", + " x = data[[\"constant\", \"time\"]]\n", + " params = sm.OLS(y, x).fit().params\n", + "\n", + " return params" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In general, the user-specified outcome function may return any pytree (e.g. numpy.ndarray, pandas.DataFrame, dict etc.). In the example here, it returns a pandas.Series." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now we are ready to calculate confidence intervals and standard errors." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "results_without_cluster = em.bootstrap(data=df, outcome=ols_fit)\n", + "results_without_cluster.ci()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "results_without_cluster.se()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The above function call represents the minimum that a user has to specify, making full use of the default options, such as drawing a 1_000 bootstrap draws, using the \"percentile\" bootstrap confidence interval, not making use of parallelization, etc.\n", + "\n", + "If, for example, we wanted to take 10_000 draws, while parallelizing on two cores, and using a \"bc\" type confidence interval, we would simply call the following:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "results_without_cluster2 = em.bootstrap(\n", + " data=df, outcome=ols_fit, n_draws=10_000, n_cores=2\n", + ")\n", + "\n", + "results_without_cluster2.ci(ci_method=\"bc\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Doing a clustered bootstrap" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In the cluster robust variant of the bootstrap, the original dataset is divided into clusters according to the values of some user-specified variable, and then clusters are drawn uniformly with replacement in order to create the different bootstrap samples. \n", + "\n", + "In order to use the cluster robust boostrap, we simply specify which variable to cluster by. In the example we are working with, it seems sensible to cluster on individuals, i.e. on the column \"id\" of our dataset." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "results_with_cluster = em.bootstrap(data=df, outcome=ols_fit, cluster_by=\"id\")\n", + "\n", + "results_with_cluster.se()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can see that the estimated standard errors are indeed of smaller magnitude when we use the cluster robust bootstrap. \n", + "\n", + "Finally, we can compare our bootstrap results to a regression on the full sample using statsmodels' OLS function.\n", + "We see that the cluster robust bootstrap yields standard error estimates very close to the ones of the cluster robust regression, while the regular bootstrap seems to overestimate the standard errors of both coefficients.\n", + "\n", + "**Note**: We would not expect the asymptotic statsmodels standard errors to be exactly the same as the bootstrapped standard errors.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "y = df[\"pulse\"]\n", + "x = df[[\"constant\", \"time\"]]\n", + "\n", + "\n", + "cluster_robust_ols = sm.OLS(y, x).fit(cov_type=\"cluster\", cov_kwds={\"groups\": df[\"id\"]})" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Splitting up the process" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In many situations, the above procedure is enough. However, sometimes it may be important to split the bootstrapping process up into smaller steps. Examples for such situations are:\n", + "\n", + "1. You want to look at the bootstrap estimates\n", + "2. You want to do a bootstrap with a low number of draws first and add more draws later without duplicated calculations\n", + "3. You have more bootstrap outcomes than just the parameters\n", + "\n", + "### 1. Accessing bootstrap outcomes\n", + "\n", + "The bootstrap outcomes are stored in the results object you get back when calling the bootstrap function. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "result = em.bootstrap(data=df, outcome=ols_fit, seed=1234)\n", + "my_outcomes = result.outcomes\n", + "\n", + "my_outcomes[:5]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To further compare the cluster bootstrap to the uniform bootstrap, let's plot the sampling distribution of the parameters on time. We can again see that the standard error is smaller when we cluster on the subject id. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "result_clustered = em.bootstrap(data=df, outcome=ols_fit, seed=1234, cluster_by=\"id\")\n", + "my_outcomes_clustered = result_clustered.outcomes" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# clustered distribution in blue\n", + "sns.histplot(\n", + " pd.DataFrame(my_outcomes_clustered)[\"time\"], kde=True, stat=\"density\", linewidth=0\n", + ")\n", + "\n", + "# non-clustered distribution in orange\n", + "sns.histplot(\n", + " pd.DataFrame(my_outcomes)[\"time\"],\n", + " kde=True,\n", + " stat=\"density\",\n", + " linewidth=0,\n", + " color=\"orange\",\n", + ");" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Calculating standard errors and confidence intervals from existing bootstrap result" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If you've already run ``bootstrap`` once, you can simply pass the existing result object to a new call of ``bootstrap``. Estimagic reuses the existing bootstrap outcomes and now only draws ``n_draws`` - ``n_existing`` outcomes instead of drawing entirely new ``n_draws``. Depending on the ``n_draws`` you specified (this is set to 1_000 by default), this may save considerable computation time. \n", + "\n", + "We can go on and compute confidence intervals and standard errors, just the same way as before, with several methods (e.g. \"percentile\" and \"bc\"), yet without duplicated evaluations of the bootstrap outcome function. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "my_results = em.bootstrap(\n", + " data=df,\n", + " outcome=ols_fit,\n", + " existing_result=result,\n", + ")\n", + "my_results.ci(ci_method=\"t\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can use this to calculate confidence intervals with several methods (e.g. \"percentile\" and \"bc\") without duplicated evaluations of the bootstrap outcome function." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 2. Extending bootstrap results with more draws\n", + "\n", + "It is often the case that, for speed reasons, you set the number of bootstrap draws quite low, so you can look at the results earlier and later decide that you need more draws. \n", + "\n", + "As an example, we will take an initial sample of 500 draws. We then extend it with another 1500 draws. \n", + "\n", + "*Note*: It is very important to use a different random seed when you calculate the additional outcomes!!!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "initial_result = em.bootstrap(data=df, outcome=ols_fit, seed=5471, n_draws=500)\n", + "initial_result.ci(ci_method=\"t\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "combined_result = em.bootstrap(\n", + " data=df, outcome=ols_fit, existing_result=initial_result, seed=2365, n_draws=2000\n", + ")\n", + "combined_result.ci(ci_method=\"t\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 3. Using less draws than totally available bootstrap outcomes" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You have a large sample of bootstrap outcomes but want to compute summary statistics only on a subset? No problem! Estimagic got you covered. You can simply pass any number of ``n_draws`` to your next call of ``bootstrap``, regardless of the size of the existing sample you want to use. We already covered the case where ``n_draws`` > ``n_existing`` above, in which case estimagic draws the remaining bootstrap outcomes for you.\n", + "\n", + "If ``n_draws`` <= ``n_existing``, estimagic takes a random subset of the existing outcomes - and voilà! " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "subset_result = em.bootstrap(\n", + " data=df, outcome=ols_fit, existing_result=combined_result, seed=4632, n_draws=500\n", + ")\n", + "subset_result.ci(ci_method=\"t\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Accessing the bootstrap samples" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "It is also possible to just access the bootstrap samples. You may do so, for example, if you want to calculate your bootstrap outcomes in parallel in a way that is not yet supported by estimagic (e.g. on a large cluster or super-computer)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from estimagic.bootstrap_samples import get_bootstrap_samples\n", + "\n", + "rng = np.random.default_rng(1234)\n", + "my_samples = get_bootstrap_samples(data=df, rng=rng)\n", + "my_samples[0]" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "estimagic", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + }, + "vscode": { + "interpreter": { + "hash": "e8a16b1bdcc80285313db4674a5df2a5a80c75795379c5d9f174c7c712f05b3a" + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/source/how_to_guides/miscellaneous/how_to_generate_publication_quality_tables.ipynb b/docs/source/estimagic/tutorials/estimation_tables_overview.ipynb similarity index 99% rename from docs/source/how_to_guides/miscellaneous/how_to_generate_publication_quality_tables.ipynb rename to docs/source/estimagic/tutorials/estimation_tables_overview.ipynb index a08e7fb74..632fd9c29 100644 --- a/docs/source/how_to_guides/miscellaneous/how_to_generate_publication_quality_tables.ipynb +++ b/docs/source/estimagic/tutorials/estimation_tables_overview.ipynb @@ -175,7 +175,7 @@ "\n", "`estimate_ml` and `estimate_msm` can both generate summaries of estimation results. Those summaries are either DataFrames with the columns `\"value\"`, `\"standard_error\"`, `\"p_value\"` and `\"stars\"` or pytrees containing such DataFrames. \n", "\n", - "For examples, check out our tutorials on [`estimate_ml`](../../getting_started/first_likelihood_estimation_with_estimagic.ipynb) and [`estimate_msm`](../../getting_started/first_msm_estimation_with_estimagic.ipynb).\n", + "For examples, check out our tutorials on [`estimate_ml`](likelihood_overview.ipynb) and [`estimate_msm`](msm_overview.ipynb).\n", "\n", "\n", "Assume we got the following DataFrame from an estimation summary:" diff --git a/docs/source/how_to_guides/miscellaneous/example_estimation_table_tex.pdf b/docs/source/estimagic/tutorials/example_estimation_table_tex.pdf similarity index 100% rename from docs/source/how_to_guides/miscellaneous/example_estimation_table_tex.pdf rename to docs/source/estimagic/tutorials/example_estimation_table_tex.pdf diff --git a/docs/source/getting_started/estimation/index.md b/docs/source/estimagic/tutorials/index.md similarity index 75% rename from docs/source/getting_started/estimation/index.md rename to docs/source/estimagic/tutorials/index.md index 54ef5fa29..b579d0da1 100644 --- a/docs/source/getting_started/estimation/index.md +++ b/docs/source/estimagic/tutorials/index.md @@ -1,4 +1,4 @@ -# Estimation with estimagic +# Estimagic Tutorials Estimagic hast functions to estimate the parameters of maximum likelihood or simulation models. You provide a likelihood or moment simulation function. Estimagic produces @@ -9,6 +9,8 @@ publication quality latex or html tables. --- maxdepth: 1 --- -first_likelihood_estimation_with_estimagic -first_msm_estimation_with_estimagic +likelihood_overview +msm_overview +bootstrap_overview +estimation_tables_overview ``` diff --git a/docs/source/getting_started/estimation/first_likelihood_estimation_with_estimagic.ipynb b/docs/source/estimagic/tutorials/likelihood_overview.ipynb similarity index 97% rename from docs/source/getting_started/estimation/first_likelihood_estimation_with_estimagic.ipynb rename to docs/source/estimagic/tutorials/likelihood_overview.ipynb index 92b859d60..46820fe1b 100644 --- a/docs/source/getting_started/estimation/first_likelihood_estimation_with_estimagic.ipynb +++ b/docs/source/estimagic/tutorials/likelihood_overview.ipynb @@ -21,7 +21,7 @@ "To be very clear: Estimagic is not a package to estimate linear models or other models that are implemented in Stata, statsmodels or anywhere else. Its purpose is to estimate parameters with custom likelihood or method of simulated moments functions. We just use an ordered logit model as an example of a very simple likelihood function.\n", "\n", "\n", - "### Model:\n", + "## Model:\n", "\n", "$$ y = \\beta_0 + \\beta_1 x + \\epsilon, \\text{ where } \\epsilon \\sim N(0, \\sigma^2)$$\n", "\n", @@ -190,6 +190,11 @@ } ], "metadata": { + "kernelspec": { + "display_name": "optimagic", + "language": "python", + "name": "python3" + }, "language_info": { "codemirror_mode": { "name": "ipython", @@ -200,7 +205,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.9.13" + "version": "3.10.14" } }, "nbformat": 4, diff --git a/docs/source/getting_started/estimation/first_msm_estimation_with_estimagic.ipynb b/docs/source/estimagic/tutorials/msm_overview.ipynb similarity index 87% rename from docs/source/getting_started/estimation/first_msm_estimation_with_estimagic.ipynb rename to docs/source/estimagic/tutorials/msm_overview.ipynb index 1fb6df4c3..0687884f9 100644 --- a/docs/source/getting_started/estimation/first_msm_estimation_with_estimagic.ipynb +++ b/docs/source/estimagic/tutorials/msm_overview.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "private-handle", + "id": "0", "metadata": {}, "source": [ "# Method of Simulated Moments (MSM)\n", @@ -38,7 +38,7 @@ { "cell_type": "code", "execution_count": null, - "id": "dirty-slovakia", + "id": "1", "metadata": {}, "outputs": [], "source": [ @@ -51,7 +51,7 @@ }, { "cell_type": "markdown", - "id": "annoying-guard", + "id": "2", "metadata": {}, "source": [ "## 1. Simulate data" @@ -60,7 +60,7 @@ { "cell_type": "code", "execution_count": null, - "id": "fdaf1542", + "id": "3", "metadata": {}, "outputs": [], "source": [ @@ -74,7 +74,7 @@ { "cell_type": "code", "execution_count": null, - "id": "f965ccdc", + "id": "4", "metadata": {}, "outputs": [], "source": [ @@ -89,7 +89,7 @@ }, { "cell_type": "markdown", - "id": "20a94f52", + "id": "5", "metadata": {}, "source": [ "## 2. Calculate Moments" @@ -98,7 +98,7 @@ { "cell_type": "code", "execution_count": null, - "id": "diverse-validation", + "id": "6", "metadata": {}, "outputs": [], "source": [ @@ -116,7 +116,7 @@ { "cell_type": "code", "execution_count": null, - "id": "short-flood", + "id": "7", "metadata": {}, "outputs": [], "source": [ @@ -126,7 +126,7 @@ }, { "cell_type": "markdown", - "id": "italic-baptist", + "id": "8", "metadata": {}, "source": [ "## 3. Calculate the covariance matrix of empirical moments\n", @@ -142,7 +142,7 @@ { "cell_type": "code", "execution_count": null, - "id": "rocky-willow", + "id": "9", "metadata": {}, "outputs": [], "source": [ @@ -155,16 +155,16 @@ }, { "cell_type": "markdown", - "id": "hearing-dairy", + "id": "10", "metadata": {}, "source": [ - "``get_moments_cov`` mainly just calls estimagic's bootstrap function. See our [bootstrap_tutorial](../../how_to_guides/inference/how_to_do_bootstrap_inference.ipynb) for background information. \n", + "``get_moments_cov`` mainly just calls estimagic's bootstrap function. See our [bootstrap_tutorial](bootstrap_overview.ipynb) for background information. \n", "\n" ] }, { "cell_type": "markdown", - "id": "worldwide-whole", + "id": "11", "metadata": {}, "source": [ "## 4. Define a function to calculate simulated moments\n", @@ -175,7 +175,7 @@ { "cell_type": "code", "execution_count": null, - "id": "creative-pittsburgh", + "id": "12", "metadata": {}, "outputs": [], "source": [ @@ -189,7 +189,7 @@ { "cell_type": "code", "execution_count": null, - "id": "casual-stream", + "id": "13", "metadata": {}, "outputs": [], "source": [ @@ -198,7 +198,7 @@ }, { "cell_type": "markdown", - "id": "sustainable-collectible", + "id": "14", "metadata": {}, "source": [ "## 5. Estimate the model parameters\n", @@ -217,7 +217,7 @@ { "cell_type": "code", "execution_count": null, - "id": "finite-david", + "id": "15", "metadata": {}, "outputs": [], "source": [ @@ -235,7 +235,7 @@ { "cell_type": "code", "execution_count": null, - "id": "outside-volleyball", + "id": "16", "metadata": {}, "outputs": [], "source": [ @@ -244,7 +244,7 @@ }, { "cell_type": "markdown", - "id": "incident-government", + "id": "17", "metadata": {}, "source": [ "## What's in the result?\n", @@ -257,7 +257,7 @@ { "cell_type": "code", "execution_count": null, - "id": "caring-scale", + "id": "18", "metadata": {}, "outputs": [], "source": [ @@ -267,7 +267,7 @@ { "cell_type": "code", "execution_count": null, - "id": "9fc88986", + "id": "19", "metadata": {}, "outputs": [], "source": [ @@ -277,7 +277,7 @@ { "cell_type": "code", "execution_count": null, - "id": "d7dbe79c", + "id": "20", "metadata": {}, "outputs": [], "source": [ @@ -286,24 +286,20 @@ }, { "cell_type": "markdown", - "id": "blind-tractor", + "id": "21", "metadata": {}, "source": [ - "## How to visualize sensitivity measures?\n", - "\n", - "For more background on the sensitivity measures and their interpretation, check out the [how to guide](../../how_to_guides/miscellaneous/how_to_visualize_and_interpret_sensitivity_measures.ipynb) on sensitivity measures. \n", - "\n", - "Here, we just show you how to plot them:" + "## How to visualize sensitivity measures?" ] }, { "cell_type": "code", "execution_count": null, - "id": "fleet-qatar", + "id": "22", "metadata": {}, "outputs": [], "source": [ - "from estimagic.visualization.lollipop_plot import lollipop_plot # noqa: E402\n", + "from estimagic import lollipop_plot\n", "\n", "sensitivity_data = res.sensitivity(kind=\"bias\").abs().T\n", "\n", @@ -330,7 +326,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.8 | packaged by conda-forge | (main, Nov 22 2022, 08:27:35) [Clang 14.0.6 ]" + "version": "3.10.14" }, "vscode": { "interpreter": { diff --git a/docs/source/explanations/optimization/explanation_of_numerical_optimizers.md b/docs/source/explanation/explanation_of_numerical_optimizers.md similarity index 98% rename from docs/source/explanations/optimization/explanation_of_numerical_optimizers.md rename to docs/source/explanation/explanation_of_numerical_optimizers.md index 73b4483e9..45f99fa93 100644 --- a/docs/source/explanations/optimization/explanation_of_numerical_optimizers.md +++ b/docs/source/explanation/explanation_of_numerical_optimizers.md @@ -14,7 +14,7 @@ The main principles we describe here are: - Derivative free trust region algorithms - Derivative free direct search algorithms -This covers a large range of the algorithms that come with estimagic. We do currently +This covers a large range of the algorithms that come with optimagic. We do currently not cover: - Conjugate gradient methods diff --git a/docs/source/explanations/optimization/implementation_of_constraints.md b/docs/source/explanation/implementation_of_constraints.md similarity index 96% rename from docs/source/explanations/optimization/implementation_of_constraints.md rename to docs/source/explanation/implementation_of_constraints.md index 2836252d7..06bc39f22 100644 --- a/docs/source/explanations/optimization/implementation_of_constraints.md +++ b/docs/source/explanation/implementation_of_constraints.md @@ -2,7 +2,7 @@ # How constraints are implemented -Most of the optimizers wrapped in estimagic cannot deal natively with anything but box +Most of the optimizers wrapped in optimagic cannot deal natively with anything but box constraints. So the problem they can solve is: $$ @@ -23,9 +23,9 @@ box constraints, into constrained optimizers: Reparametrization and penalties. B explain what both approaches are, why we chose the reparametrization approach over penalties, and which reparametrizations we are using for each type of constraint. -In this text, we focus on constraints that can be solved by estimagic via bijective and +In this text, we focus on constraints that can be solved by optimagic via bijective and differentiable transformations. General nonlinear constraints do not fall into this -category. If you want to use nonlinear constraints, you can still do so, but estimagic +category. If you want to use nonlinear constraints, you can still do so, but optimagic will simply pass the constraints to your chosen optimizer. See {ref}`constraints` for more details. @@ -67,14 +67,14 @@ g(\tilde{x}) = (\tilde{x}, 5 - \tilde{x}) $$ Typically, users implement such reparametrizations manually and write functions to -convert between the parameters of interest and their reparametrized version. Estimagic +convert between the parameters of interest and their reparametrized version. optimagic does this for you, for a large number of constraints that are typically used in econometric applications. For this approach to be efficient, it is crucial that the reparametrizations preserve desirable properties of the original problem. In particular, the mapping $g$ should be differentiable and if possible linear. Moreover, the dimensionality of $\tilde{x}$ -should be chosen as small as possible. Estimagic only implements constraints that can be +should be chosen as small as possible. optimagic only implements constraints that can be enforced with differentiable transformations and always achieves full dimensionality reduction. @@ -89,7 +89,7 @@ While the generality and conceptual simplicity of this approach is attractive, i has its drawbacks. Applying penalties in a naive way can introduce kinks, discontinuities, and even local optima into the penalized criterion. -## What estimagic does +## What optimagic does We chose to implement constraints via reparametrizations for the following reasons: @@ -215,6 +215,6 @@ or other constraints on any of the involved parameters. **References** ```{eval-rst} -.. bibliography:: ../../refs.bib +.. bibliography:: ../refs.bib :filter: docname in docnames ``` diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md new file mode 100644 index 000000000..05f576f1b --- /dev/null +++ b/docs/source/explanation/index.md @@ -0,0 +1,16 @@ +# Explanation + +This section provides background information on numerical topics and details of +optimagic. It is completely optional and not necessary if you are just starting out. + +```{toctree} +--- +maxdepth: 1 +--- +implementation_of_constraints +internal_optimizers +why_optimization_is_hard.ipynb +explanation_of_numerical_optimizers +tests_for_supported_optimizers +numdiff_background +``` diff --git a/docs/source/explanations/optimization/internal_optimizers.md b/docs/source/explanation/internal_optimizers.md similarity index 88% rename from docs/source/explanations/optimization/internal_optimizers.md rename to docs/source/explanation/internal_optimizers.md index eb72ecb4a..3ee33f806 100644 --- a/docs/source/explanations/optimization/internal_optimizers.md +++ b/docs/source/explanation/internal_optimizers.md @@ -1,21 +1,20 @@ (internal_optimizer_interface)= -# Internal optimizers for estimagic +# Internal optimizers for optimagic -estimagic provides a large collection of optimization algorithm that can be used by +optimagic provides a large collection of optimization algorithm that can be used by passing the algorithm name as `algorithm` into `maximize` or `minimize`. Advanced users -can also use estimagic with their own algorithm, as long as it conforms with the +can also use optimagic with their own algorithm, as long as it conforms with the internal optimizer interface. -The advantages of using the algorithm with estimagic over using it directly are: +The advantages of using the algorithm with optimagic over using it directly are: -- estimagic turns an unconstrained optimizer into constrained ones. +- optimagic turns an unconstrained optimizer into constrained ones. - You can use logging. -- You get a real time dashboard to monitor your optimization. - You get great error handling for exceptions in the criterion function or gradient. - You get a parallelized and customizable numerical gradient if the user did not provide a closed form gradient. -- You can compare your optimizer with all the other estimagic optimizers by changing +- You can compare your optimizer with all the other optimagic optimizers by changing only one line of code. All of this functionality is achieved by transforming a more complicated user provided @@ -29,7 +28,7 @@ few conditions. In our experience, it is not hard to wrap any optimizer into thi interface. The mandatory conditions for an internal optimizer function are: 1. It is decorated with the `mark_minimizer` decorator and thus carries information that - tells estimagic how to use the internal optimizer. + tells optimagic how to use the internal optimizer. 1. It uses the standard names for the arguments that describe the optimization problem: @@ -57,8 +56,8 @@ should return a dictionary with the following entries: - solution_x: The best parameter achieved so far - solution_criterion: The value of the criterion at solution_x. This can be a scalar or dictionary. -- n_criterion_evaluations: The number of criterion evaluations. -- n_derivative_evaluations: The number of derivative evaluations. +- n_fun_evals: The number of criterion evaluations. +- n_jac_evals: The number of derivative evaluations. - n_iterations: The number of iterations - success: True if convergence was achieved - message: A string with additional information. @@ -79,8 +78,8 @@ Since some optimizers support many tuning parameters we group some of them by th part of their name (e.g. all convergence criteria names start with `convergence`). See {ref}`list_of_algorithms` for the signatures of the provided internal optimizers. -The preferred default values can be imported from `estimagic.optimization.algo_options` -which are documented in {ref}`algo_options`. If you add a new optimizer to estimagic you +The preferred default values can be imported from `optimagic.optimization.algo_options` +which are documented in {ref}`algo_options`. If you add a new optimizer to optimagic you should only deviate from them if you have good reasons. Note that a complete harmonization is not possible nor desirable, because often @@ -91,7 +90,7 @@ the exact meaning of all options for all optimizers. ## Algorithms that parallelize Algorithms can evaluate the criterion function in parallel. To make such a parallel -algorithm fully compatible with estimagic (including history collection and benchmarking +algorithm fully compatible with optimagic (including history collection and benchmarking functionality), the following conditions need to be fulfilled: - The algorithm has an argument called `n_cores` which determines how many cores are @@ -112,7 +111,7 @@ collection by using `mark_minimizer(..., disable_history=True)`. ## Nonlinear constraints -Estimagic can pass nonlinear constraints to the internal optimizer. The internal +optimagic can pass nonlinear constraints to the internal optimizer. The internal interface for nonlinear constraints is as follows. A nonlinear constraint is a `list` of `dict` 's, where each `dict` represents a group of diff --git a/docs/source/explanations/differentiation/background_numerical_differentiation.md b/docs/source/explanation/numdiff_background.md similarity index 98% rename from docs/source/explanations/differentiation/background_numerical_differentiation.md rename to docs/source/explanation/numdiff_background.md index b3538c397..2f55627bf 100644 --- a/docs/source/explanations/differentiation/background_numerical_differentiation.md +++ b/docs/source/explanation/numdiff_background.md @@ -70,6 +70,6 @@ central differences. **References:** ```{eval-rst} -.. bibliography:: ../../refs.bib +.. bibliography:: ../refs.bib :filter: docname in docnames ``` diff --git a/docs/source/explanations/optimization/tests_for_supported_optimizers.md b/docs/source/explanation/tests_for_supported_optimizers.md similarity index 98% rename from docs/source/explanations/optimization/tests_for_supported_optimizers.md rename to docs/source/explanation/tests_for_supported_optimizers.md index 5e9afa897..503e91bb4 100644 --- a/docs/source/explanations/optimization/tests_for_supported_optimizers.md +++ b/docs/source/explanation/tests_for_supported_optimizers.md @@ -1,6 +1,6 @@ # How supported optimization algorithms are tested -estimagic provides a unified interface that supports a large number of optimization +optimagic provides a unified interface that supports a large number of optimization algorithms from different libraries. Additionally, it allows putting constraints on the optimization problem. To test the external interface of all supported algorithms, we consider different criterion (benchmark) functions and test each algorithm with every @@ -42,7 +42,7 @@ for rotated hyper ellipsoid, we implement the following functions: - rotated_hyper_ellipsoid_criterion_and_gradient These criterion functions are specified in the `examples` directory. For an overview of -all constraints supported in estimagic, please see [this how-to guide]. +all constraints supported in optimagic, please see [this how-to guide]. We write several test functions, each corresponding to the case of one constraint. Given the constraint, the test function considers all possible combinations of the algorithm, @@ -457,4 +457,4 @@ Global minima: $x* = (1, 1, 1)$ > No solution available. > ``` -[this how-to guide]: ../../how_to_guides/optimization/how_to_specify_constraints.md +[this how-to guide]: ../how_to/how_to_constraints.md diff --git a/docs/source/explanation/why_optimization_is_hard.ipynb b/docs/source/explanation/why_optimization_is_hard.ipynb new file mode 100644 index 000000000..caf6a8519 --- /dev/null +++ b/docs/source/explanation/why_optimization_is_hard.ipynb @@ -0,0 +1,262 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Why optimization is difficult\n", + "\n", + "This tutorial shows why optimization is difficult and why you need some knowledge in order to solve optimization problems efficiently. It is meant for people who have no previous experience with numerical optimization and wonder why there are so many optimization algorithms and still none that works for all problems. For each potential problem we highlight, we also give some ideas on how to solve it. \n", + "\n", + "\n", + "If you simply want to learn the mechanics of doing optimization with optimagic, check out the [quickstart guide](../tutorials/optimization_overview.ipynb)\n", + "\n", + "\n", + "The take-home message of this notebook can be summarized as follows:\n", + "\n", + "- The only algorithms that are guaranteed to solve all problems are grid search or other algorithms that evaluate the criterion function almost everywhere in the parameter space.\n", + "- If you have more than a hand full of parameters, these methods would take too long.\n", + "- Thus, you have to know the properties of your optimization problem and have knowledge about different optimization algorithms in order to choose the right algorithm for your problem. \n", + "\n", + "This tutorial uses variants of the sphere function from the [quickstart guide](../tutorials/optimization_overview.ipynb)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om\n", + "import seaborn as sns" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere(x):\n", + " return x @ x\n", + "\n", + "\n", + "def sphere_gradient(x):\n", + " return 2 * x" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Why grid search is infeasible\n", + "\n", + "Sampling based optimizers and grid search require the parameter space to be bounded in all directions. Let's assume we know that the optimum of the sphere function lies between -0.5 and 0.5, but don't know where it is exactly. \n", + "\n", + "In order to get a precision of 2 digits with grid search, we require the following number of function evaluations (depending on the number of parameters):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dimensions = np.arange(10) + 1\n", + "n_evals = 100**dimensions\n", + "sns.lineplot(x=dimensions, y=n_evals);" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If you have 10 dimensions and evaluating your criterion function takes one second, you need about 3 billion years on a 1000 core cluster. Many of the real world criterion functions have hundreds of parameters and take minutes to evaluate once. This is called the curse of dimensionality." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Sampling based algorithms typically fix the number of criterion evaluations and apply them a bit smarter than algorithms that rummage the search space randomly. However, these smart tricks only work under additional assumptions. Thus, either you need to make assumptions on your problem or you will get the curse of dimensionality through the backdoor again. For easier analysis, assume we fix the number of function evaluations in a grid search instead of a sampling based algorithm and want to know which precision we can get, depending on the dimension:\n", + "\n", + "For 1 million function evaluations, we can expect the following precision:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dimensions = np.arange(10) + 1\n", + "precision = 1e-6 ** (1 / dimensions)\n", + "sns.lineplot(x=dimensions, y=precision);" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## How derivatives can solve the curse of dimensionality\n", + "\n", + "Derivative based methods do not try to evaluate the criterion function everywhere in the search space. Instead, they start at some point and go \"downhill\" from there. The gradient of the criterion function indicates which direction is downhill. Then there are different ways of determining how far to go in that direction. The time it takes to evaluate a derivative increases at most linearly in the number of parameters. Using the derivative information, optimizers can often find an optimum with very few function evaluations." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## How derivative based methods can fail\n", + "\n", + "To see how derivative based methods can fail, we use simple modifications of the sphere function. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "rng = np.random.default_rng(seed=0)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere_with_noise(x, rng):\n", + " return sphere(x) + rng.normal(scale=0.02)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "start_params = np.arange(5)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "grid = np.linspace(-1, 1, 1000)\n", + "sns.lineplot(\n", + " x=grid,\n", + " y=(grid**2) + rng.normal(scale=0.02, size=len(grid)),\n", + ");" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=sphere_with_noise,\n", + " params=start_params,\n", + " algorithm=\"scipy_lbfgsb\",\n", + " logging=False,\n", + " fun_kwargs={\"rng\": rng},\n", + ")\n", + "\n", + "res.success" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res.params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res.message" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "So the algorithm failed, but at least tells you that it did not succed. Let's look at a different kind of numerical noise that could come from rounding. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def piecewise_constant_sphere(x):\n", + " return sphere(x.round(2))" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sns.lineplot(x=grid, y=grid.round(2) ** 2);" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=piecewise_constant_sphere,\n", + " params=start_params,\n", + " algorithm=\"scipy_lbfgsb\",\n", + ")\n", + "\n", + "res" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This time, the algorithm failed silently." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/source/explanations/differentiation/index.md b/docs/source/explanations/differentiation/index.md deleted file mode 100644 index 8c00c1043..000000000 --- a/docs/source/explanations/differentiation/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# Differentiation - -```{toctree} ---- -maxdepth: 1 ---- -background_numerical_differentiation -richardson_extrapolation -``` diff --git a/docs/source/explanations/differentiation/richardson_extrapolation.md b/docs/source/explanations/differentiation/richardson_extrapolation.md deleted file mode 100644 index 2c732fe6b..000000000 --- a/docs/source/explanations/differentiation/richardson_extrapolation.md +++ /dev/null @@ -1,232 +0,0 @@ -# Richardson Extrapolation - -In this section we introduce the mathematical machinery of *Richardson's method*. - -## Motivation - -Say you want to compute the value of some function -$g: \mathbb{R}_+ \to -\mathbb{R}^{m\times n}, h \mapsto g(h)$ as $h \to 0$; however, -$\lim_{h\to\infty} g(h)\neq g(0)$. We can approximate the limit by evaluating the -function at values close to zero on a computer. The error of our approximation naturally -depends on $g$. In certain cases it is possible to express this error in a specific way, -in which case we can improve upon the order of our error using Richardson's method. - -### Example - -Lets start with an easy case where $f: \mathbb{R} \to \mathbb{R}$ is the function of -interest. Using central differences we can approximate $f'$ at some point -$x \in \mathbb{R}$ by $g(h) := \frac{f(x+h) - f(x-h)}{2h}$. Note that $g(h) \to f'(x)$ -as $h \to 0$ if $f$ is differentiable at $x$; however, $g(0)$ is not defined and hence -in particular unequal to $f'(x)$. To quantify the error of using $g(h)$ instead of -$f'(x)$ we can rely on Taylor's Theorem (assuming that $f$ has a Taylor representation): - -$$ -f(x+h) &= f(x) + f'(x)h + f''(x)\frac{h^2}{2} + f'''(x)\frac{h^3}{6} + -\dots\\ f(x-h) &= f(x) - f'(x)h + f''(x)\frac{h^2}{2} - -f'''(x)\frac{h^3}{6} - \dots\\[1em] \implies& f(x+h) - f(x-h) = 2hf'(x) + -2\frac{h^3}{6} f'''(x) + 2\frac{h^5}{5!} f^{(5)}(x) + \dots \\ \implies& -g(h) \stackrel{def}{=} \frac{f(x+h) - f(x-h)}{2h} = f'(x) + h^2 -\frac{f'''(x)}{3!} + h^4 \frac{f^{(5)}(x)}{5!} + \dots \\ \implies& g(h) = -f'(x) + \sum_{i=0}^{\infty} a_i h^{2+2i} = f'(x) + \mathcal{O}(h^2) -$$ - -where $\mathcal{O}(\cdot)$ denotes the Landau notation. Richardson's method can be used -to improve the error rate $\mathcal{O}(h^2)$. - -## General case - -In general Richardson's method considers sequences that can be written as: - -$$ -g(h) = L + \sum_{i=0}^{\infty} a_i h^{\theta +i \phi,} -$$ - -where $L \in \mathbb{R}$ denotes the limit of interest, $\theta$ the *base order of the -approximation* and $\phi$ the *exponential step*. Allthough Richardson's method works -for general sequences, we are mostly interested in the sequences arising when estimating -derivatives. - -### Example (contd.) - -For standard derivative estimates we have - -| Method | $L$ | $\theta$ | $\phi$ | -| -------------- | ------- | -------- | ------ | -| forward diff. | $f'(x)$ | 1 | 1 | -| backward diff. | $f'(x)$ | 1 | 1 | -| central diff. | $f'(x)$ | 2 | 2 | - -## Richardson Extrapolation - -From the above table we see that, in general, central differences have a lower -approximation error $\mathcal{O}(h^2)$ than forward or backward differences -$\mathcal{O}(h)$. - -> **Question**: Can we improve upon this further? - -Let us evaluate $g$ at multiple values $h_0, h_1, h_2, \dots$, where it will turn out to -be useful to choose values $h, h/2, h/4, h/8, \dots$ given some prechosen $h > 0$. More -generally $\{ h_n \}_n, h_n = h/2^n$ for $n -\in \mathbb{N}$. This allows us to write - -$$ -g(h) &= L + \sum_{i=0}^{\infty} a_i h^{\theta +i \phi}\\ g(h/2) &= L + -\sum_{i=0}^{\infty} a_i h^{\theta +i \phi} \frac{1}{2^{\theta +i \phi}}\\ g(h/4) &= -L + \sum_{i=0}^{\infty} a_i h^{\theta +i \phi} \frac{1}{4^{\theta +i \phi}}\\ -&\vdots -$$ - -Now approximate the $g(h_n)$ by dropping all elements in the infinite sum after $i=1$ -and collect the approximation error using the term $\eta(h_n)$: - -$$ -g(h) &= \tilde{g}(h) + \eta(h) := L + \sum_{i=0}^{1} a_i h^{\theta +i \phi} -\\ g(h/2) &= \tilde{g}(h/2) + \eta(h/2) := L + \sum_{i=0}^{1} a_i h^{\theta -+i \phi} \frac{1}{2^{\theta +i \phi}}\\ g(h/4) &= \tilde{g}(h/4) + -\eta(h/4) := L + \sum_{i=0}^{1} a_i h^{\theta +i \phi} \frac{1}{4^{\theta -+i \phi}}\\ &\vdots -$$ - -Notice that we are now able to summarize the equations as - -$$ -\begin{bmatrix} -g(h) \\ -g(h/2) \\ -g(h/4) -\end{bmatrix} -= - \begin{bmatrix} - 1 & h^\theta & h^{\theta + \phi} \\ - 1 & {h^\theta}/{2^\theta} & {h^{\theta + \phi}}/{(2^{\theta + \phi})} \\ - 1 & {h^\theta}/{4^\theta} & {h^{\theta + \phi}}/{(4^{\theta + \phi})} \\ - \end{bmatrix} - \begin{bmatrix} - L \\ a_0 \\ a_1 - \end{bmatrix} -+ - \begin{bmatrix} - \eta (h)\\ - \eta (h/2) \\ - \eta (h/4) - \end{bmatrix} -$$ - -which we write in shorthand notation as - -$$ -(\ast): \,\,\, -g = H - \begin{bmatrix} - L \\ a_0 \\ a_1 - \end{bmatrix} -+ \eta \,. -$$ - -From looking at equation ($\ast$) we see that an improved estimate of $L$ can be -obtained by projecting $g$ onto $H$. - -### Remark - -To get a better intuition for ($\ast$) consider $H$ in more detail. For the sake of -clarity let $\theta = \phi = 2$. - -$$ -H = -\begin{bmatrix} - 1 & h^2 & h^4 \\ - 1 & h^2/2^2 & h^4/2^4 \\ - 1 & h^2/4^2 & h^4/4^4 \\ -\end{bmatrix} = -\begin{bmatrix} - 1 & h^2 & h^4 \\ - 1 & (h/2)^2 & (h/2)^4 \\ - 1 & (h/4)^2 & (h/4)^4 \\ -\end{bmatrix} -$$ - -Hence $H$ is a design matrix constructed from polynomial terms of degree $0,2,4,\dots$ -(in general: $0,\theta, \theta + \phi, \theta + 2\phi,\dots$) evaluated at the observed -points $h, h/2,h/4,h/8, \dots$. - -In other words, dependant on the step-size of the derivative ($h$), we fit a polynomial -model to the derivative estimate and approximate the true derivative using the fitted -intercept. - -The usual estimate is then given by $\hat{L} := e_1^T (H^T H)^{-1} H^T g$ which is equal -to $e_1^T H^{-1} g = \sum_{i} \{H^{-1}\}_{1,i} g_i$ in case $H$ is regular. - -## Did we improve the error rate? - -Let us first consider the error function $\eta: h \to \eta (h)$ in more detail. We see -that - -$$ -\eta(h) = g(h) - \tilde{g}(h) = L + \sum_{i=0}^{\infty} a_i h^{\theta +i -\phi} - (L + \sum_{i=0}^{1} a_i h^{\theta +i \phi}) = \sum_{i=2}^{\infty} -h^{\theta +i \phi} = \mathcal{O}(h^{\theta +2 \phi}) \,. -$$ - -Now consider the case where $H$ is regular (which happens here when $H$ is quadratic). -We then have, using ($\ast$) - -$$ -g = H - \begin{bmatrix} - L \\ a_0 \\ a_1 - \end{bmatrix} -+ \eta \implies H^{-1} g = -\begin{bmatrix} - L \\ a_0 \\ a_1 -\end{bmatrix} -+ H^{-1} \eta -$$ - -To get a better view on the error rate consider our ongoing example again. - -### Example (contd.) - -With - -$$ -H = -\begin{bmatrix} - 1 & h^2 & h^4 \\ - 1 & (h/2)^2 & (h/2)^4 \\ - 1 & (h/4)^2 & (h/4)^4 \\ -\end{bmatrix} -$$ - -we get - -$$ -H^{-1} = \frac{1}{45} - \begin{bmatrix} - 1 & -20 & 64\\ - -20/h^2 & 340/h^2 & -320/h^2\\ - 64/h^4 & -320/h^4 & 256/h^4 - \end{bmatrix} -$$ - -Further, since for central differences $\theta = \phi = 2$ we have -$\eta -(h_n) = \mathcal{O}(h^6)$ for all $n$ and thus: - -$$ -H^{-1} \eta = H^{-1} -\begin{bmatrix} - \eta(h) \\ - \eta (h/2) \\ - \eta (h/4) \\ -\end{bmatrix} -= -\begin{bmatrix} - \mathcal{O}(h^6) \\ - \dots \\ - \dots \\ -\end{bmatrix} -\implies \hat{L} = \{H^{-1} g \}_1 = L + \mathcal{O}(h^6) -$$ - -And so indeed we improved the error rate. diff --git a/docs/source/explanations/index.md b/docs/source/explanations/index.md deleted file mode 100644 index 9162e2066..000000000 --- a/docs/source/explanations/index.md +++ /dev/null @@ -1,77 +0,0 @@ -# Explanations - -Explanations contain background information on important topics. They are not needed to -get started, but very helpful for advanced users and developers of estimagic. - -`````{grid} 1 2 2 2 ---- -gutter: 3 ---- -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/optimization.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} optimization/index.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Optimization -``` - -Learn how to use constraints, parallelize function evaluations, and configure every aspect of your optimization. - -```` - -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/differentiation.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} differentiation/index.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Differentiation -``` - -Learn how to influence step sizes, parallelize function evaluations, and use advanced options for numerical differentiation. - -```` - -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/bullseye.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} inference/index.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Estimation -``` - -Learn how to calculate different types of standard errors and do sensitivity analysis. - -```` - -````` - -```{toctree} ---- -hidden: true -maxdepth: 1 ---- -optimization/index -differentiation/index -inference/index -``` diff --git a/docs/source/explanations/optimization/index.md b/docs/source/explanations/optimization/index.md deleted file mode 100644 index 3925f07cb..000000000 --- a/docs/source/explanations/optimization/index.md +++ /dev/null @@ -1,12 +0,0 @@ -# Optimization - -```{toctree} ---- -maxdepth: 1 ---- -implementation_of_constraints -internal_optimizers -why_optimization_is_hard.ipynb -explanation_of_numerical_optimizers -tests_for_supported_optimizers -``` diff --git a/docs/source/explanations/optimization/why_optimization_is_hard.ipynb b/docs/source/explanations/optimization/why_optimization_is_hard.ipynb deleted file mode 100644 index 680c3e3ef..000000000 --- a/docs/source/explanations/optimization/why_optimization_is_hard.ipynb +++ /dev/null @@ -1,478 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Why optimization is difficult\n", - "\n", - "This tutorial shows why optimization is difficult and why you need some knowledge in order to solve optimization problems efficiently. It is meant for people who have no previous experience with numerical optimization and wonder why there are so many optimization algorithms and still none that works for all problems. For each potential problem we highlight, we also give some ideas on how to solve it. \n", - "\n", - "\n", - "If you simply want to learn the mechanics of doing optimization with estimagic, check out the [quickstart guide](../../getting_started/first_optimization_with_estimagic.ipynb)\n", - "\n", - "\n", - "The take-home message of this notebook can be summarized as follows:\n", - "\n", - "- The only algorithms that are guaranteed to solve all problems are grid search or other algorithms that evaluate the criterion function almost everywhere in the parameter space.\n", - "- If you have more than a hand full of parameters, these methods would take too long.\n", - "- Thus, you have to know the properties of your optimization problem and have knowledge about different optimization algorithms in order to choose the right algorithm for your problem. \n", - "\n", - "This tutorial uses variants of the sphere function from the [quickstart guide](../../getting_started/first_optimization_with_estimagic.ipynb)." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np\n", - "import pandas as pd\n", - "import seaborn as sns" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(params):\n", - " return (params[\"value\"] ** 2).sum()\n", - "\n", - "\n", - "def sphere_gradient(params):\n", - " return params * 2" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Why grid search is infeasible\n", - "\n", - "Sampling based optimizers and grid search require the parameter space to be bounded in all directions. Let's assume we know that the optimum of the sphere function lies between -0.5 and 0.5, but don't know where it is exactly. \n", - "\n", - "In order to get a precision of 2 digits with grid search, we require the following number of function evaluations (depending on the number of parameters):" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAAhYAAAGsCAYAAACB/u5dAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjYuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8o6BhiAAAACXBIWXMAAA9hAAAPYQGoP6dpAAArrElEQVR4nO3de3RU5b3/8c9kkkzugwnkBgEiBi/cJWi5eGuVlipLTlvbWi+grUv6Q4Hya6vUXtQCEdu67E+WWDgWsYh47BH1nFYt2gLeaAOIF7BJwAgRCeEiM7mQSTKzf38kMyRAIJOZyd4z836ttZfMZM/sb5yl8+HZz/d5bIZhGAIAAAiDBLMLAAAAsYNgAQAAwoZgAQAAwoZgAQAAwoZgAQAAwoZgAQAAwoZgAQAAwoZgAQAAwoZgAQAAwoZgAQAAwsa0YLF582ZNnz5dhYWFstlsevHFF4N6fXNzs2bNmqVRo0YpMTFRM2bMOO15zzzzjMaMGaO0tDQVFBTotttu05EjR0L/BQAAwClMCxaNjY0aM2aMli1b1qvXe71epaamau7cubr66qtPe85bb72lW2+9Vd///ve1c+dOPf/88yovL9cPfvCDUEoHAADdMC1YTJs2TYsWLdI3vvGN0/68paVFP/3pTzVw4EClp6fr0ksv1caNGwM/T09P1/Lly3XHHXcoPz//tO+xZcsWDR06VHPnzlVxcbGmTJmiO++8U1u3bo3ErwQAQNyz7ByL2267TW+//bbWrVunDz74QDfccIO+9rWvqaqqqsfvMWnSJH322Wf661//KsMwdPDgQf35z3/WtddeG8HKAQCIX5YMFnv27NGzzz6r559/XpdddpmGDRumH//4x5oyZYpWrVrV4/eZNGmSnnnmGX3nO99RcnKy8vPz1a9fPz322GMRrB4AgPhlyWCxfft2GYah4cOHKyMjI3Bs2rRJe/bs6fH77Nq1S3PnztUvf/lLbdu2Ta+++qqqq6s1e/bsCFYPAED8SjS7gNPx+Xyy2+3atm2b7HZ7l59lZGT0+H3Kyso0efJk/eQnP5EkjR49Wunp6brsssu0aNEiFRQUhLVuAADinSWDxbhx4+T1elVXV6fLLrus1+/T1NSkxMSuv6I/qBiGEVKNAADgVKYFi4aGBu3evTvwuLq6Wjt27FB2draGDx+um266Sbfeeqt+97vfady4cTp8+LD+/ve/a9SoUfr6178uqf1WR0tLi44ePar6+nrt2LFDkjR27FhJ0vTp03XHHXdo+fLl+upXv6oDBw5o/vz5uuSSS1RYWNjXvzIAADHPZpj0V/eNGzfqqquuOuX5mTNn6qmnnlJra6sWLVqkp59+Wvv371dOTo4mTpyoBx54QKNGjZIkDR06VHv37j3lPTr/So899pieeOIJVVdXq1+/fvryl7+spUuXauDAgZH75QAAiFOmBQsAABB7LNkVAgAAohPBAgAAhE2fT970+Xz6/PPPlZmZKZvN1teXBwAAvWAYhurr61VYWKiEhO7HJfo8WHz++ecqKirq68sCAIAwqKmp0aBBg7r9eZ8Hi8zMTEnthWVlZfX15QEAQC+43W4VFRUFvse7E1SwaGtr0/33369nnnlGtbW1Kigo0KxZs/Tzn//8jMMinflvf2RlZREsAACIMmebxhBUsFi6dKmeeOIJrV69WiNGjNDWrVt12223yel0at68eSEVCgAAol9QweLdd9/V9ddfH9h2fOjQoXr22We1devWiBQHAACiS1DtplOmTNEbb7yhyspKSdL777+vt956K7DE9ul4PB653e4uBwAAiE1BjVjcc889crlcuuCCC2S32+X1erV48WLdeOON3b6mrKxMDzzwQMiFAgAA6wtqxOK5557TmjVrtHbtWm3fvl2rV6/Wb3/7W61evbrb1yxcuFAulytw1NTUhFw0AACwpqD2CikqKtK9996rOXPmBJ5btGiR1qxZo3//+989eg+32y2n0ymXy0VXCAAAUaKn399BjVg0NTWd0lZqt9vl8/l6VyUAAIgpQc2xmD59uhYvXqzBgwdrxIgReu+99/TII4/o9ttvj1R9AAAgigR1K6S+vl6/+MUvtH79etXV1amwsFA33nijfvnLXyo5OblH78GtEAAAok9Pv7+DChbhQLAAACD6RGSOBQAAwJkQLAAAQNj0+e6mAAAgMn710kdypibplolDNSDTYUoNBAsAAGJAc6tXa/65T16foZu+NMS0OrgVAgBADPjkUKO8PkPO1CTlmjRaIREsAACICZUH6yVJw/MyZLPZTKuDYAEAQAyoCASLTFPrIFgAABADKmvbg8X5+QQLAAAQoso6RiwAAEAYNHraVHP0uCSCBQAACFFVXYMkqX+GQ9npPdu7K1IIFgAARLkT8ysyTK6EYAEA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\n", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "dimensions = np.arange(10) + 1\n", - "n_evals = 100**dimensions\n", - "sns.lineplot(x=dimensions, y=n_evals);" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "If you have 10 dimensions and evaluating your criterion function takes one second, you need about 3 billion years on a 1000 core cluster. Many of the real world criterion functions have hundreds of parameters and take minutes to evaluate once. This is called the curse of dimensionality." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Sampling based algorithms typically fix the number of criterion evaluations and apply them a bit smarter than algorithms that rummage the search space randomly. However, these smart tricks only work under additional assumptions. Thus, either you need to make assumptions on your problem or you will get the curse of dimensionality through the backdoor again. For easier analysis, assume we fix the number of function evaluations in a grid search instead of a sampling based algorithm and want to know which precision we can get, depending on the dimension:\n", - "\n", - "For 1 million function evaluations, we can expect the following precision:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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Zo127dqlF198UQ0bNjQ7Wp01Y8YMvf7665o9e7Z2796tF154Qf/4xz/06quvmh2tTsjPz1ePHj00e/bs837/hRde0EsvvaTZs2dr27ZtCg4O1sCBA8s+z686cVlzHXP8+HE1a9ZM69at07XXXmt2nDorLy9PvXv31pw5c/Tss8+qZ8+emjlzptmx6pzHHntMX375pTZs2GB2FJxz++23KygoSAsXLiwbu/vuu+Xr66ulS5eamKzusVgsWrlypYYMGSKpdHWlRYsWiouL06OPPipJKiwsVFBQkGbMmKEHHnigWvOwwlLH5OTkSJICAwNNTlK3TZw4Ubfddptuuukms6PUaatWrVJERIR+//vfq1mzZurVq5fmz59vdqw67ZprrtHnn3+uvXv3SpJ27NihjRs36tZbbzU5GQ4ePKisrCzFxMSUjdlsNl133XXatGlTtf/8WvPhh/h1hmFo8uTJuuaaa9StWzez49RZb7/9tr766itt27bN7Ch13oEDBzR37lxNnjxZjz/+uLZu3aqHH35YNptNo0aNMjtenfToo48qJydHnTp1koeHhxwOh5577jndc889Zker87KysiRJQUFB5caDgoL0ww8/VPvPp7DUIQ8++KC+/vprbdy40ewodVZGRoYmTZqkzz77TD4+PmbHqfOcTqciIiL0/PPPS5J69eqlnTt3au7cuRQWkyQmJmrZsmVasWKFunbtqrS0NMXFxalFixYaPXq02fGg0reK/pdhGBXGqgOFpY546KGHtGrVKq1fv14tW7Y0O06dlZKSomPHjik8PLxszOFwaP369Zo9e7YKCwvl4eFhYsK6pXnz5urSpUu5sc6dO+u9994zKRH+8pe/6LHHHtMf/vAHSdLVV1+tH374QfHx8RQWkwUHB0sqXWlp3rx52fixY8cqrLpUB85hqeUMw9CDDz6o999/X//5z38UFhZmdqQ67cYbb9Q333yjtLS0si0iIkLDhw9XWloaZeUK69+/f4XL/Pfu3avQ0FCTEuHMmTOyWsu/NHl4eHBZsxsICwtTcHCwkpKSysaKioq0bt069evXr9p/PisstdzEiRO1YsUKffjhh/Lz8yt7DzIgIED16tUzOV3d4+fnV+H8ofr166tx48acV2SCRx55RP369dPzzz+voUOHauvWrZo3b57mzZtndrQ6a/DgwXruuefUqlUrde3aVampqXrppZc0ZswYs6PVCXl5edq/f3/Z1wcPHlRaWpoCAwPVqlUrxcXF6fnnn1f79u3Vvn17Pf/88/L19dWwYcOqP5yBWk3SebdFixaZHQ3nXHfddcakSZPMjlFnffTRR0a3bt0Mm81mdOrUyZg3b57Zkeo0u91uTJo0yWjVqpXh4+NjtGnTxpg6dapRWFhodrQ64Ysvvjjva8bo0aMNwzAMp9NpPP3000ZwcLBhs9mMa6+91vjmm2+uSDbuwwIAANwe57AAAAC3R2EBAABuj8ICAADcHoUFAAC4PQoLAABwexQWAADg9igsAADA7VFYAACA26OwAAAAt0dhAQAAbo/CAgAA3B6FBQAAuL3/B87MV3u+2z/EAAAAAElFTkSuQmCC\n", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "dimensions = np.arange(10) + 1\n", - "precision = 1e-6 ** (1 / dimensions)\n", - "sns.lineplot(x=dimensions, y=precision);" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## How derivatives can solve the curse of dimensionality\n", - "\n", - "Derivative based methods do not try to evaluate the criterion function everywhere in the search space. Instead, they start at some point and go \"downhill\" from there. The gradient of the criterion function indicates which direction is downhill. Then there are different ways of determining how far to go in that direction. The time it takes to evaluate a derivative increases at most linearly in the number of parameters. Using the derivative information, optimizers can often find an optimum with very few function evaluations." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## How derivative based methods can fail\n", - "\n", - "To see how derivative based methods can fail, we use simple modifications of the sphere function. " - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "rng = np.random.default_rng(seed=0)" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere_with_noise(params, rng):\n", - " return sphere(params) + rng.normal(scale=0.02)" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
value
x_01
x_12
x_23
x_34
x_45
\n", - "
" - ], - "text/plain": [ - " value\n", - "x_0 1\n", - "x_1 2\n", - "x_2 3\n", - "x_3 4\n", - "x_4 5" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "start_params = pd.DataFrame(\n", - " data=np.arange(5) + 1,\n", - " columns=[\"value\"],\n", - " index=[f\"x_{i}\" for i in range(5)],\n", - ")\n", - "start_params" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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FXIsuqeXSTkReSdOYCWiFnHbjUyr/RNCjeaJyC1kSSUiAtgzQkQtZOHdPTG0YzjGdo9qNNMrEZEYgxEiahGBGh/D0tny6hpDuX2znBCRJ+AwDRG1OKXEpFUiInP4F4OIWpx40qq9M8ASkftjMEJELU4mEwcjTmwIEbkFBiNERETkVAxGiMiuBE5hJaJGMBghIrviMA0RNYbBCBHZVUK4v7ObQEQujnlGiMguvn9yCC4UlKFv21bObgoRuTgGI0RkF33iQtAnLsTZzSAiN8BhGiIiInIqBiNERETkVAxGiIiIyKkYjBAREZFTMRghIiIip2IwQkRERE7FYISIiIicisEIERERORWDESIiInIqBiNERETkVAxGiIiIyKkYjBAREZFTMRghIiIip3KLXXsFQQAAFBcXO7klREREZK26z+26z3Fz3CIYKSkpAQDExcU5uSVERERkq5KSEgQHB5s9LhMaC1dcgF6vx5UrVxAYGAiZTNZij1tcXIy4uDhcvHgRQUFBLfa4rsTTr5HX5/48/Ro9/foAz79GXl/TCYKAkpISxMTEQC43PzPELXpG5HI5YmNj7fb4QUFBHvkLJubp18jrc3+efo2efn2A518jr69pLPWI1OEEViIiInIqBiNERETkVF4djKjVarz88stQq9XObordePo18vrcn6dfo6dfH+D518jrsz+3mMBKREREnsure0aIiIjI+RiMEBERkVMxGCEiIiKnYjBCRERETuXxwcjf//53DB48GH5+fggJCbHqHEEQ8MorryAmJga+vr4YOXIk/vjjD6M6VVVVePrppxEeHg5/f3/ccccduHTpkh2uwLLr16/joYceQnBwMIKDg/HQQw+hsLDQ4jkymUzy56233jLUGTlypMnx++67z85XY6op1/fwww+btH3gwIFGdVzl9QNsv0atVou//e1v6NmzJ/z9/RETE4PJkyfjypUrRvWc9RouXboUCQkJ0Gg0SEpKws6dOy3W3759O5KSkqDRaNC+fXssX77cpM7atWvRrVs3qNVqdOvWDevXr7dX861iyzWuW7cOt9xyC1q3bo2goCAMGjQImzdvNqqzevVqyfdkZWWlvS9Fki3Xt23bNsm2nzhxwqieK72Gtlyf1N8TmUyG7t27G+q40uu3Y8cO3H777YiJiYFMJsP333/f6Dku8R4UPNxLL70kLF68WJg7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\n", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "grid = np.linspace(-1, 1, 1000)\n", - "sns.lineplot(\n", - " x=grid,\n", - " y=(grid**2) + rng.normal(scale=0.02, size=len(grid)),\n", - ");" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "False" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere_with_noise,\n", - " params=start_params,\n", - " algorithm=\"scipy_lbfgsb\",\n", - " logging=False,\n", - " criterion_kwargs={\"rng\": rng},\n", - ")\n", - "\n", - "res.success" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
value
x_01.0
x_12.0
x_23.0
x_34.0
x_45.0
\n", - "
" - ], - "text/plain": [ - " value\n", - "x_0 1.0\n", - "x_1 2.0\n", - "x_2 3.0\n", - "x_3 4.0\n", - "x_4 5.0" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res.params" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "'ABNORMAL_TERMINATION_IN_LNSRCH'" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res.message" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "So the algorithm failed, but at least tells you that it did not succed. Let's look at a different kind of numerical noise that could come from rounding. " - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [], - "source": [ - "def piecewise_constant_sphere(params):\n", - " params = params.copy(deep=True)\n", - " params[\"value\"] = params[\"value\"].round(2)\n", - " return sphere(params)" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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\n", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "sns.lineplot(x=grid, y=grid.round(2) ** 2);" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "Minimize with 5 free parameters terminated successfully after 1 criterion evaluations, 1 derivative evaluations and 0 iterations.\n", - "\n", - "The value of criterion improved from 55.0 to 55.0.\n", - "\n", - "The scipy_lbfgsb algorithm reported: CONVERGENCE: NORM_OF_PROJECTED_GRADIENT_<=_PGTOL" - ] - }, - "execution_count": 14, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=piecewise_constant_sphere,\n", - " params=start_params,\n", - " algorithm=\"scipy_lbfgsb\",\n", - " logging=False,\n", - ")\n", - "\n", - "res" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "This time, the algorithm failed silently." - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/source/getting_started/first_derivative_with_estimagic.ipynb b/docs/source/getting_started/first_derivative_with_estimagic.ipynb deleted file mode 100644 index 8be3d10fc..000000000 --- a/docs/source/getting_started/first_derivative_with_estimagic.ipynb +++ /dev/null @@ -1,538 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Numerical differentiation\n", - "\n", - "Using simple examples, This tutorial shows you how to numerical differentiation with estimagic. More details on the topics covered here can be found in the [how to guides](../how_to_guides/index.md)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np\n", - "import pandas as pd" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Basic usage of `first_derivative`" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(params):\n", - " return params @ params" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([0., 2., 4., 6., 8.])" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(\n", - " func=sphere,\n", - " params=np.arange(5),\n", - ")\n", - "\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Basic usage of `second_derivative`" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[2.001, 0. , 0. , 0. , 0. ],\n", - " [0. , 2. , 0. , 0. , 0. ],\n", - " [0. , 0. , 2. , 0. , 0. ],\n", - " [0. , 0. , 0. , 2. , 0. ],\n", - " [0. , 0. , 0. , 0. , 2. ]])" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(\n", - " func=sphere,\n", - " params=np.arange(5),\n", - ")\n", - "\n", - "sd[\"derivative\"].round(3)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## `params` do not have to be vectors\n", - "\n", - "In estimagic, params can be arbitrary [pytrees](https://jax.readthedocs.io/en/latest/pytrees.html). Examples are (nested) dictionaries of numbers, arrays and pandas objects. " - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "def dict_sphere(params):\n", - " return params[\"a\"] ** 2 + params[\"b\"] ** 2 + (params[\"c\"] ** 2).sum()" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'a': array(0.),\n", - " 'b': array(2.),\n", - " 'c': 0 4.0\n", - " 1 6.0\n", - " 2 8.0\n", - " dtype: float64}" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(\n", - " func=dict_sphere,\n", - " params={\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])},\n", - ")\n", - "\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Description of the output\n", - "\n", - "The output of `first_derivative` when using a general pytree is straight-forward. Nevertheless, this explanation requires terminolgy of pytrees. Please refer to the [JAX documentation of pytrees](https://jax.readthedocs.io/en/latest/pytrees.html).\n", - "\n", - "The output tree of `first_derivative` has the same structure as the params tree. Equivalent to the numpy case, where the gradient is a vector of shape `(len(params),)`. If, however, the params tree contains non-scalar entries like `numpy.ndarray`'s, `pandas.Series`', or `pandas.DataFrame`'s, the output is not expanded but a block is created instead. In the above example, the entry `params[\"c\"]` is a `pandas.Series` with 3 entries. Thus, the first derivative output contains the corresponding 3x1-block of the gradient at the position `[\"c\"]`:" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "0 4.0\n", - "1 6.0\n", - "2 8.0\n", - "dtype: float64" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd[\"derivative\"][\"c\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'a': {'a': array(2.00072215),\n", - " 'b': array(0.),\n", - " 'c': 0 0.0\n", - " 1 0.0\n", - " 2 0.0\n", - " dtype: float64},\n", - " 'b': {'a': array(0.),\n", - " 'b': array(1.9999955),\n", - " 'c': 0 0.0\n", - " 1 0.0\n", - " 2 0.0\n", - " dtype: float64},\n", - " 'c': {'a': 0 0.0\n", - " 1 0.0\n", - " 2 0.0\n", - " dtype: float64,\n", - " 'b': 0 0.0\n", - " 1 0.0\n", - " 2 0.0\n", - " dtype: float64,\n", - " 'c': 0 1 2\n", - " 0 1.999995 0.000004 -0.000003\n", - " 1 0.000004 2.000001 0.000000\n", - " 2 -0.000003 0.000000 1.999997}}" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(\n", - " func=dict_sphere,\n", - " params={\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])},\n", - ")\n", - "\n", - "sd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Description of the output\n", - "\n", - "The output of `second_derivative` when using a general pytrees looks more complex but is easy once we remember that the second derivative is equivalent to applying the first derivative twice. This explanation requires terminolgy of pytrees. Please refer to the [JAX documentation of pytrees](https://jax.readthedocs.io/en/latest/pytrees.html).\n", - "\n", - "The output tree is a product of the params tree with itself. This is equivalent to the numpy case, where the hessian is a matrix of shape `(len(params), len(params))`. If, however, the params tree contains non-scalar entries like `numpy.ndarray`'s, `pandas.Series`', or `pandas.DataFrame`'s, the output is not expanded but a block is created instead. In the above example, the entry `params[\"c\"]` is a 3-dimensional `pandas.Series`. Thus, the second derivative output contains the corresponding 3x3-block of the hessian at the position `[\"c\"][\"c\"]`:" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
012
02.00.0-0.0
10.02.00.0
2-0.00.02.0
\n", - "
" - ], - "text/plain": [ - " 0 1 2\n", - "0 2.0 0.0 -0.0\n", - "1 0.0 2.0 0.0\n", - "2 -0.0 0.0 2.0" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd[\"derivative\"][\"c\"][\"c\"].round(3)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## There are many options\n", - "\n", - "You can choose which finite difference method to use, whether we should respect parameter bounds, or whether to evaluate the function in parallel. Let's go through some basic examples. " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## You can choose the difference method" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([-0. , 2. , 4. , 6. , 7.99999994])" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(\n", - " func=sphere, params=np.arange(5), method=\"backward\" # default: 'central'\n", - ")\n", - "\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[2.006, 0. , 0. , 0. , 0. ],\n", - " [0. , 2. , 0. , 0. , 0. ],\n", - " [0. , 0. , 2. , 0. , 0. ],\n", - " [0. , 0. , 0. , 2. , 0. ],\n", - " [0. , 0. , 0. , 0. , 2. ]])" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(\n", - " func=sphere, params=np.arange(5), method=\"forward\" # default: 'central_cross'\n", - ")\n", - "\n", - "sd[\"derivative\"].round(3)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## You can add bounds " - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([0. , 2. , 4. , 6. , 8.00000006])" - ] - }, - "execution_count": 12, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "params = np.arange(5)\n", - "\n", - "fd = em.first_derivative(\n", - " func=sphere,\n", - " params=params,\n", - " lower_bounds=params, # forces first_derivative to use forward differences\n", - " upper_bounds=params + 1,\n", - ")\n", - "\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[2.006, 0. , 0. , 0. , 0. ],\n", - " [0. , 2. , 0. , 0. , 0. ],\n", - " [0. , 0. , 2. , 0. , 0. ],\n", - " [0. , 0. , 0. , 2. , 0. ],\n", - " [0. , 0. , 0. , 0. , 2. ]])" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(\n", - " func=sphere,\n", - " params=params,\n", - " lower_bounds=params, # forces first_derivative to use forward differences\n", - " upper_bounds=params + 1,\n", - ")\n", - "\n", - "sd[\"derivative\"].round(3)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Or use parallelized numerical derivatives" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([0., 2., 4., 6., 8.])" - ] - }, - "execution_count": 14, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(\n", - " func=sphere,\n", - " params=np.arange(5),\n", - " n_cores=4,\n", - ")\n", - "\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[2.001, 0. , 0. , 0. , 0. ],\n", - " [0. , 2. , 0. , 0. , 0. ],\n", - " [0. , 0. , 2. , 0. , 0. ],\n", - " [0. , 0. , 0. , 2. , 0. ],\n", - " [0. , 0. , 0. , 0. , 2. ]])" - ] - }, - "execution_count": 15, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(\n", - " func=sphere,\n", - " params=params,\n", - " n_cores=4,\n", - ")\n", - "\n", - "sd[\"derivative\"].round(3)" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - }, - "vscode": { - "interpreter": { - "hash": "40d3a090f54c6569ab1632332b64b2c03c39dcf918b08424e98f38b5ae0af88f" - } - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/source/getting_started/first_optimization_with_estimagic.ipynb b/docs/source/getting_started/first_optimization_with_estimagic.ipynb deleted file mode 100644 index 4e2f95677..000000000 --- a/docs/source/getting_started/first_optimization_with_estimagic.ipynb +++ /dev/null @@ -1,713 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Numerical optimization\n", - "\n", - "Using simple examples, this tutorial shows how to do an optimization with estimagic. More details on the topics covered here can be found in the [how to guides](../how_to_guides/index.md)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np\n", - "import pandas as pd" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Basic usage of `minimize`" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(params):\n", - " return params @ params" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0., -0., -0., -0., -0.])" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - ")\n", - "\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## `params` do not have to be vectors\n", - "\n", - "In estimagic, params can by arbitrary [pytrees](https://jax.readthedocs.io/en/latest/pytrees.html). Examples are (nested) dictionaries of numbers, arrays and pandas objects. " - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [], - "source": [ - "def dict_sphere(params):\n", - " return params[\"a\"] ** 2 + params[\"b\"] ** 2 + (params[\"c\"] ** 2).sum()" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'a': -6.821706323446569e-25,\n", - " 'b': 2.220446049250313e-16,\n", - " 'c': 0 8.881784e-16\n", - " 1 8.881784e-16\n", - " 2 1.776357e-15\n", - " dtype: float64}" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=dict_sphere,\n", - " params={\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])},\n", - " algorithm=\"scipy_powell\",\n", - ")\n", - "\n", - "res.params" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## The result contains all you need to know" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "Minimize with 5 free parameters terminated successfully after 805 criterion evaluations and 507 iterations.\n", - "\n", - "The value of criterion improved from 30.0 to 1.6760003634613059e-16.\n", - "\n", - "The scipy_neldermead algorithm reported: Optimization terminated successfully.\n", - "\n", - "Independent of the convergence criteria used by scipy_neldermead, the strength of convergence can be assessed by the following criteria:\n", - "\n", - " one_step five_steps \n", - "relative_criterion_change 1.968e-15*** 2.746e-15***\n", - "relative_params_change 9.834e-08* 1.525e-07* \n", - "absolute_criterion_change 1.968e-16*** 2.746e-16***\n", - "absolute_params_change 9.834e-09** 1.525e-08* \n", - "\n", - "(***: change <= 1e-10, **: change <= 1e-8, *: change <= 1e-5. Change refers to a change between accepted steps. The first column only considers the last step. The second column considers the last five steps.)" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=dict_sphere,\n", - " params={\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])},\n", - " algorithm=\"scipy_neldermead\",\n", - ")\n", - "res" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## You can visualize the convergence" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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pkztdEtYG5OLI4AAAggggEDlBc6cOWMGvcaNGyddunSRWbNmyZo1a+Tll1+u/EUpGRECMRN4S2rn5OTIgw8+KO+8845Mnz5ddAR45MiR5rTPPvtMRo0aJYsXLw4q8DpLkZUczXU2oHi588CIaHQeAgEEEEAAAQTOFdi8ebP57e+CBQvMN7/55hvp2LGjrFy5Us4//3zIolggJgPvwYMHzac3/VXFAw88IKNHj5arrrpKbrzxRtOURUVF5u+ZmZkBBV4dxdU1d5d+8d/zde5ufO04X1kCbxT/C+HREUAAAQTCKqArGVXFocuFljyWLFliRnQnT57s+9bNN98sTz75pKSkpFTFY3LPEAnEVODNzc2Vm266STTwdu7cWZ599llp3LixDB8+XHr06CG9e/f2ser83OzsbKlWrZr5ms7/LXn8/ve/l24zni725f4t0qR7s1bFvjZq/RI5WFR4ThAOURtyGQQQQAABBKJWwBkUcrsCpf3Wdf78+ZKVlWXe43GO2267zfxGuEOHDm4/IvcLoUBMBV7HTUdwly1bJtOmTZO3335bnnrqKWnbtq3079/fnFJQUGA69pYtW3zUpU1vePTRR32BV6cx3JncsdjIrlP42YyVZvOJ4SndJblBQgibj0shgAACCCAQ3QKRNML71ltvyQcffGBeVHOOvn37yvjx401O4IhegZgMvE5z/fCHPzSrM+jKDXl5eWberh76huYTTzwhS5cuLbdly1qHt2QhAm/0/gPhyRFAAAEEYkdg69at5v//ziDX6dOnpX379rJq1Spp2LBh7EB4sKYxE3h37twpcXFxkpDw3xFWfVntmWeeMZ/k9u7dKwMHDpTXX3/dt0pDUlKS+RVGeUewgXdI6y6SGp/owW5ElRBAAAEEEIh+AX1J7brrrpOxY8eaqY+6SoO+sDZ79uzor1yM1yBmAq9OQteAe+jQIalRo4Zcdtll8vjjj0tycrLpAjrFQSepnzhxQrp27SqTJk2SWrVqhSTw6stsbC8c4//SqD4CCCCAQFQIbNu2TR577DHZt2+ftGzZ0rzv07x586h4dh6ybIGYCbzh6ASBjvASeMOhzzURQAABBBBAAIHABAi8gTmVehaB1wKPoggggAACCCCAgEsCBF4L6EAD76b8XJmWtVraxifKA627WNyRoggggAACCCCAAALBChB4gxXzOz/QwLv9SJ48l5EuJXdgs7g1RRFAAAEEEEAAAQQCFCDwBghV2mkEXgs8iiKAAAIIIIAAAi4JEHgtoAMNvLr18CNrF0rd6jVlaqdbLO5IUQQQQAABBBBAAIFgBQi8wYr5nR9o4NUiw9YskONnTsnzHW+WejXKX+7M4pEoigACCCCAAAIIIFBCgMBr0SWCCbzstmYBTVEEEEAAAQQQQMBCgMBrgRdM4J2/Y4Os2rdd+rdIk+7NWlnclaIIIIAAAggggAACwQgQeIPRKnFuMIE3fe82eWPnRul2UbIMaNnO4q4URQABBBBAAAEEEAhGgMAbjJZF4PVfmqx5XCMz2psanyhDWJfXogUoigACCCCAAAIIVCxA4K3YqMwzghnh9V+pQS+oL7DpMTyluyQ3SLB4CooigAACCCCAAAIIlCdA4LXoH8EEXr2Ns1KD/y3ja8fJmLRerNxg0Q4URQABBBBAAAEECLxh6gPBBl5npQZ9HH15bU3eTsktPCyDkzpIp4QWYXpKLosAAggggAACCMS2ACO8Fu0fbOB1VmrQW05q31e2H86TWdnrREd59e8cCCCAAAIIIIAAAqEXIPBamAYbeJ2VGhLjGsrYtN7mzqPWL5GDRYXM5bVoB4oigAACCCCAAALlCRB4LfpHsIHXuZW+wObstrb0i0xZtjtTOiZcKnckdbR4GooigAACCCCAAAIIlCZA4LXoF5UNvP63zC8qlNHrl5gvvdx5oMXTUBQBBBBAAAEEEECAwBviPhCKwKuPNGHjcvPyGkuUhbiBuBwCCCCAAAIIICAijPBadINQBd6Z2Wtlbd4uVmuwaAuKIoAAAggggAACZQkQeC36RqgCrzOPt8/FbeT6S9pYPBFFEUAAAQQQQAABBEoKEHgt+kSoAq//tsMjU3pYPBFFEUAAAQQQQAABBAi8IewDoQq8zotrdavXlKmdbgnhE3IpBBBAAAEEEEAAAUZ4LfpAqAKvPsL9H841T/J8x5vZZtiiTSiKAAIIIIAAAggwwhvCPhDKwOtsO8xKDSFsIC6FAAIIIIAAAgiwSoNdHwhl4HVWaujfIk26N2tl92CURgABBBBAAAEEEPAJMKXBojOEMvA6KzV0uyhZBrRsZ/FUFEUAAQQQQAABBBDwFyDwWvSHUAZeZ6WGxLhG8sCVXSS+dpzFk1EUAQQQQAABBBBAwBEg8Fr0hVAGXv8thvWRmNpg0TAURQABBBBAAAEE/AQIvBbdIZSBVx9DR3nT926Xzfm5cnmDJsKavBaNQ1EEEEAAAQQQQOBbAQKvRVcIdeDVR9lTeEgmblwhOrVhbFovi6ejKAIIIIAAAggggIAKEHgt+kE4Aq8+jrMm78udB1o8HUURQAABBBBAAAEECLyWfSDcgZdNKCwbiOIIIIAAAggggAAjvHZ9IFyBl00o7NqF0ggggAACCCCAgL8AUxos+kO4A++Q1l0kNT7R4gkpigACCCCAAAIIIEDgtegD4Qq8ziYUfS5uI9df0sbiCSmKAAIIIIAAAgggQOC16AMEXgs8iiKAAAIIIIAAAi4JxEzgPXXqlEybNk0WLlwoZ86ckaSkJJk0aZI0bdrUULdu3Vpq1KjhY586dap069at3GYIV+B1dl1jLV6X/hVwGwQQQAABBBDwtEDMBN7Dhw/L3LlzZdCgQVK/fn158cUXJScnR1544QXR7916662yYsWKoBqbwBsUFycjgAACCCCAAAJVIhAzgbekblZWljz22GOybNky2bFjh4wbN05mz54dVCOEK/DqQ7AWb1BNwckIIIAAAggggECZAjEbeOfMmSNbt2410xoyMzPNyG+TJk3k9OnTcu2118qIESOkXr16PrjCwsJzEFNTU80ocTgOAm84VLkmAggggAACCMSiQEwG3v3798vtt98uM2fOlGbNmpl2LygoMFMdjh49Kk8++aQ0btzY/Okc/fr1O6d/aGAOV+BlLd5Y/OdInRFAAAEEEEAgHAIxF3gPHTokgwcPlkcffVQ6d+5cqumuXbvknnvukfT09HLNwzmlgcAbju7ONRFAAAEEEEAgFgViKvB+/fXXcuedd8rdd98tvXr1KrO9P//8cxk2bJiZ31veEc7AO3/HBlm1b7t0uyhZBrRsF4t9kzojgAACCCCAAAIhEYiZwKtzcHXUVqcy9O7duxieTk3QKQy6RNmxY8fk8ccfN8uWPfTQQ1UWeDfl58q0rNVSt3pNmdS+r9SrUSskDc5FEEAAAQQQQACBWBOImcA7b948GTt2rJx33nnF2nj+/Plm3u748eNFQ3HdunVNIB46dKjUqlV+yAznCK8+pDOtQbcX1m2GORBAAAEEEEAAAQSCF4iZwBs8TcUlwh1484sKZcKG5XL8zCkZk9ZLmsc1qvihOAMBBBBAAAEEEECgmACB16JDhDvw+o/y6givjvRyIIAAAggggAACCAQnQOANzqvY2W4E3qVfZMqy3ZnS5+I2cv0lbSyelqIIIIAAAggggEBsChB4LdqdwGuBR1EEEEAAAQQQQMAlAQKvBbQbgTd97zZ5Y+dGliezaCeKIoAAAggggEBsCxB4LdrfjcC7/UiePJeRLpc3aCIjU3pYPC1FEUAAAQQQQACB2BQg8Fq0O4HXAo+iCCCAAAIIIICASwIEXgtoNwLvnsJDMnHjCkmMayRj08reHc6iGhRFAAEEEEAAAQQ8LUDgtWheNwKvPt79H841T/ly54EWT0tRBBBAAAEEEEAgNgUIvBbt7nbg1S2GZ25fa554BPN5LVqOoggggAACCCAQSwIEXovWdivwDluzwOy2Njipg8zKXsdor0WbURQBBBBAAAEEYk+AwGvR5m4F3mczVkrOkQPSNj5RNufnmicentJdkhskWDw9RRFAAAEEEEAAgdgQIPBatLPbgVeXJtPgq4eO9nZKaGHx9BRFAAEEEEAAAQRiQ4DAa9HObgXemdlrZW3ermJPylbDFg1HUQQQQAABBBCIKQECr0VzuxV4l36RKct2ZxZ7Up3e8EDrLhZPT1EEEEAAAQQQQCA2BAi8Fu1clYGXdXktGo6iCCCAAAIIIBBTAgRei+Z2K/CuydvpW52hce04OVhUaJ6adXktGo+iCCCAAAIIIBAzAgRei6Z2K/BuP5Inz2WkmyfVF9fyTxSa0Kvr8sbXjrOoAUURQAABBBBAAAHvCxB4Ldq4KgJvt4uSRbcb1tUaWJrMovEoigACCCCAAAIxI0DgtWhqtwLvsdMn5ZG1C82T9m+RJl+dKJRV+7YLKzVYNB5FEUAAAQQQQCBmBAi8Fk3tVuDVR7z/w7nmSXVUN/vwAbNqg472DmjZzqIGFEUAAQQQQAABBLwvQOC1aGM3A6/utqbHnckd5asTBWZOr87nHZnSw6IGFEUAAQQQQAABBLwvQOC1aGM3A6//YzovsRF4LRqPoggggAACCCAQMwIEXoumrqrAq4/sTHFgaTKLBqQoAggggAACCMSEAIHXopkJvBZ4FEUAAQQQQAABBFwSIPBaQFdl4B21fglr8Vq0HUURQAABBBBAIHYECLwWbV2VgVdfYmMtXovGoygCCCCAAAIIxIwAgdeiqQm8FngURQABBBBAAAEEXBIg8FpAV2XgXfpFplmLl80nLBqQoggggAACCCAQEwIEXotmJvBa4FEUAQQQQAABBBBwSYDAawFdlYF3Td5OmZW9TjomXCp3JHW0qAVFEUAAAQQQQAABbwu4GnhPnTolX331lTRt2tQTqlUZeNl8whNdiEoggAACCCCAgAsCrgTeI0eOyFNPPSVvv/22nD17VrZv326qtmTJEvniiy9k6NChLlQ19Lcg8IbelCsigAACCCCAAAKhFnAl8I4cOVKKiopMsO3Xr59s3brV1EOD73333ScffPBBqOvlyvWqMvBqBdltzZVm5iYIIIAAAgggEOUCrgTeq666St59911p3LixXHnllb7AqyO/HTt2lKysrKhkJPBGZbPx0AgggAACCCAQYwKuBN527drJ8uXLJSEhoVjgXb9+vQwfPlw++uijqGSv6sDLbmtR2W14aAQQQAABBBBwWcCVwPv000/Lvn37ZNy4cdKjRw/5+OOPZcOGDebvvXv3lhEjRoS92vrC3LRp02ThwoVy5swZSUpKkkmTJvleoFu0aJFMnTpVTp48KT179hR95urVq5f7XFUdeNltLezdhhsggAACCCCAgAcEXAm8GiI1TM6ePVtOnDhh2GrVqiV33nmnDBs2TGrUqBF2ysOHD8vcuXNl0KBBUr9+fXnxxRclJydHXnjhBdm1a5f5+rx586RJkyYmgKempspdd90VFYF3SOsukhqfGHZDboAAAggggAACCESjgCuB14HRUda9e/eaEdbmzZub0FtVh84bfuyxx2TZsmUyffp0OXr0qOjLdXp89tlnMmrUKFm8eHFEB152W6uq3sN9EUAAAQQQQCCaBFwNvJEEM2fOHPPynE5rGD16tOiLdTfeeKN5RF1RQv+emZlJ4I2kRuNZEEAAAQQQQACBSgi4EngrmqM7ZcqUSjx65Yvs379fbr/9dpk5c6Y0a9bMvDinc4t1PrFz6Pzc7OxsqVatmvmSzv8teTz33HNmWkRVHYzwVpU890UAAQQQQACBaBJwJfDqPFn/Q0dQd+/eLatWrTJr895///2umR06dEgGDx4sjz76qHTu3Nnc94knnpC2bdtK//79zd8LCgqkQ4cOsmXLFt9zvfnmm+c84+OPP16lgZfd1lzrNtwIAQQQQAABBKJYwJXAW5aPrtTwl7/8pdTR03CYfv311+ZFubvvvlt69erlu8WMGTMkLy/PzNvV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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.criterion_plot(res, max_evaluations=300)\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAArwAAAH0CAYAAADfWf7fAAAgAElEQVR4XuzdCXyNV/4/8I8lxJIgtBK71r63qCW0RdW+dNBhFI22tv+MrS1p/RTVTulULdOR0ilaFMWMrSqUaIktGEGCqCXWWEpEkFj/r++5OdeT/d48Nzc31+d5veZVbp7lPO/zxHxy8n3OyfPo0aNH4EYBClCAAhSgAAUoQAE3FcjDwOumPcvbogAFKEABClCAAhRQAgy8fBAoQAEKUIACFKAABdxagIHXrbuXN0cBClCAAhSgAAUowMDLZ4ACFKAABShAAQpQwK0FGHjdunt5cxSgAAUoQAEKUIACDLx8BihAAQpQgAIUoAAF3FqAgdetu5c3RwEKUIACFKAABSjAwMtngAIUoAAFKEABClDArQUYeN26e3lzFKAABShAAQpQgAIMvHwGKEABClCAAhSgAAXcWoCB1627lzdHAQpQgAIUoAAFKMDAy2eAAhSgAAUoQAEKUMCtBRh43bp7eXMUoAAFKEABClCAAgy8fAYoQAEKUIACFKAABdxagIHXrbuXN0cBClCAAhSgAAUowMDLZ4ACFKAABShAAQpQwK0FGHjdunt5cxSgAAUoQAEKUIACDLx8BihAAQpQgAIUoAAF3FqAgdetu5c3RwEKUIACFKAABSjAwMtngAIUoAAFKEABClDArQUYeN26e3lzFKAABShAAQpQgAIMvHwGKEABClCAAhSgAAXcWoCB1627lzdHAQpQgAIUoAAFKMDAy2eAAhSgAAUoQAEKUMCtBRh43bp7eXMUoAAFKEABClCAAgy8fAYoQAEKUIACFKAABdxagIHXrbuXN0cBClCAAhSgAAUowMDLZ4ACFKAABShAAQpQwK0FGHjdunt5cxSgAAUoQAEKUIACDLx8BihAAQpQgAIUoAAF3FqAgdetu5c3RwEKUIACFKAABSjAwMtngAIUoAAFKEABClDArQUYeN26e3lzFKAABShAAQpQgAIMvHwGKEABClCAAhSgAAXcWoCB1627lzdHAQpQgAIUoAAFKMDAy2eAAhSgAAUoQAEKUMCtBRh43bp7eXMUoAAFKEABClCAAgy8fAYoQAEKUIACFKAABdxagIHXrbuXN0cBClCAAhSgAAUowMDLZ4ACFKAABShAAQpQwK0FGHjdunt5cxSgAAUoQAEKUIACDLx8BihAAQpQgAIUoAAF3FqAgdetu5c3RwEKUIACFKAABSjAwMtngAIUoAAFKEABClDArQUYeN26e3lzFKAABShAAQpQgAIMvHwGKEABClCAAhSgAAXcWoCB1627lzdHAQpQgAIUoAAFKMDAy2eAAhSgAAUoQAEKUMCtBRh43bp7eXMUoAAFKEABClCAAgy8fAYoQAEKUIACFKAABdxagIHXrbuXN0cBClCAAhSgAAUowMDLZ4ACFKAABShAAQpQwK0FGHjdunt5cxSgAAUoQAEKUIACDLx8BihAAQpQgAIUoAAF3FqAgdetu5c3RwEKUIACFKAABSjAwMtngAIUoAAFKEABClDArQUYeN26e3lzFKAABShAAQpQgAIMvHwGKEABClCAAhSgAAXcWoCB1627lzdHAQpQgAIUoAAFKMDAy2eAAhSgAAUoQAEKUMCtBRh43bp7eXMUoAAFKEABClCAAgy8fAYoQAEKUIACFKAABdxagIHXrbuXN0cBClCAAhSgAAUowMDLZ4ACFKAABShAAQpQwK0FGHjdunt5cxSgAAUoQAEKUIACDLx8BihAAQpQgAIUoAAF3FqAgdetu5c3RwEKUIACFKAABSjAwMtngAIUoAAFKEABClDArQUYeN26e3lzFKAABShAAQpQgAIMvHwGKEABClCAAhSgAAXcWoCB1627lzdHAQpQgAIUoAAFKMDAy2eAAhSgAAUoQAEKUMCtBRh43bp7eXMUoAAFKEABClCAAgy8fAYoQAEKUIACFKAABdxagIHXrbuXN0cBClCAAhSgAAUowMDLZ4ACFKAABShAAQpQwK0FGHjdunt5cxSgAAUoQAEKUIACDLx8BihAAQpQgAIUoAAF3FqAgdetu5c3RwEKUIACFKAABSjAwMtngAIUoAAFKEABClDArQUYeN26e3lzFKAABShAAQpQgAIMvHwGKEABClCAAhSgAAXcWoCB1627lzdHAQpQgAIUoAAFKMDAy2eAAhSgAAUoQAEKUMCtBRh43bp7eXMUoAAFKEABClCAAgy8fAYoQAEKUIACFKAABdxagIHXrbuXN0cBClCAAhSgAAUowMDLZ4ACFKAABShAAQpQwK0FGHjdunt5cxSgAAUoQAEKUIACDLx8BihAAQpQgAIUoAAF3FqAgdetu5c3RwEKUIACFKAABSjAwMtngAIUoAAFKEABClDA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BZ0tF8jC4hPv/hiugq6smnYz4b41rGalxXqeXj1KrOf1NS5fnJXz8hgKUIACFKAABZwj4JTA+/DhQyxbtgzr1q3DpUuX8Msvv6i72759O27duoV27do5524dfBVXD7zjto/DmhNrMNl/MrpX6e7gu3fg6YyBV8oZdMg1vsxm5+V0Ta4+TEobRrWtZudZLLtLuYMsViEBd/vY1tYX4uRrsriFLFVcq4w3Xq1VOkvn50EUoAAFKEABCmSvgFMC71dffaXC7htvvIG///3viIy0LO26d+9efPTRR1i/fn323mU2nd3VA+/sA7MRFB6EofWHYlgD+6b2yiaytE+7azaw4QNAVls7lvQsyKhukD9w6TAwZBvga98MH3o6MUcEXjmHXoBCFqUwLk0sIVhWcZPtp+EtUbuMC8+G4dRO5cUoQAEKUIACriPglMDbsmVLfPfdd3jmmWdQu3ZtREREKIHr169Dvnb48OEcF3n06BH+9a9/Yf78+di37/Eysxk1jIHXQd2Wcu5dvcywsba3Uku7LqanE9MH6WWG7TqJYWddIiHTlp2PvaNegtt96lqy00kYllkcVu47h5p+XpjQpXZWL8fjKEABClCAAhRwoIBTAm+dOnWwa9cuFC1aNFng/f333/H6669j//79Drwl+0917949jBo1Ck8//TTWrl2LsLAwm07CwGsTU+Y7pQy83WcDDfoCS/pYRnz13zM/k3WPlMsFG1dPs+M01l1TjhhLuJ23/ZQKvxJupaxBXmKTbVPkpUxnhchKG3gMBShAAQpQgAJZE3BK4H3nnXfUohN/+9vfrIE3NjYWo0ePRrFixTB9+vSstd6BR/32229o0aIFGjZsiP/97382nZmB1yamzHdKiAWmVLTsV6w8MCppxN9Y22vn4hNyqvSWC868Qan3SCtAyxRmMpWZt6cHOs3apmp8dXmDnCGjld2y0gYeQwEKUIACFKBA1gScEngvXryowq6UMJw9exYy4iujuzVq1MDs2bNRqlSprLXewUfdv38fjRs3dpvAu/nMZowMGYlW5VthVutZDtZy8On0C2rGldV04JUpyjpMtfuCjgy8KQN0ykUodI2vsZFcqMLuLuMBFKAABShAgWwRcErg1S2X2lgJug8ePECVKlXwwgsvZMtNZfWkGQXerVu3pjqtjFwfP348q5fL9uPCYsIwMHggGpVuhPnt52f79UxdQF5cux5tWUbYs7jlVLrUIYuLT+j5ctWppnQy1Tw5WJ8v5fLD8jVd42u8iNkyCtMN5gkoQAEKUIACFFACTgm8spLaq6++moo8MTFRTVHWqZP5MOKI/swo8H7yySepLiEv4jHwOkI+nXO4WODNaPlhPVev3InU8kod7z961UevhuWyEYinpgAFKEABClDAFgGnBF4pE0jrRTAJmA0aNHCJWRoEy91KGnLVCG9aT6uu7fUsBgSeseV5TraPXiFNPnTECG9Gyw/H3bmHiItxqp53Y0SMWs7YzNy/dt8sD6AABShAAQpQIF2BbA28UVFR6sK9e/fG0qVLkzVCyhqkTODHH39ESEiIS3SRuwbe6j7VsaLLCpcwtrsRDlh8Iq0SBLvbYccBerSXSw/bgcZdKUABClCAAtkokK2BNzAwEKGhoYiJiUGBAgWS3UbevHlRrlw5jBs3Ts2O4AqbuwVeMa37XV1Fe2jAIVcgtr8Nn5UHEuOAkQeB4kkzOdh4luX7zuH95eFOnyJMzwGslyK2sbncjQIUoAAFKECBbBLI1sArbb579y569uyJNWvWZNMt5NxpXX1aMmPgDe0TCu8CuXAVMBOLT0gJwoq9Z1HOp7DTa2n1DBFSSiHlDrIgBTcKUIACFKAABXJGINsDr9yWjJzmz58fssDD1atX4efnlzN36+Cr5qbAKzM17L20F/PazUNj38YOlsjG05kIvNnYqkxPXXdiMG4m3IcsUDHzlyhsH9uaoTdTNe5AAQpQgAIUyB4BpwTeGzduYMKECdiwYQNkCd9jx46pu1m9ejWio6MxfPjw7Lm7bD5rbgq8XgW8cPPuTQytPxTDGgzLUGbKnimIuh6FMY3HoIZPjWxWzOT0JhefkLOv+n0V1pxYg67PdkX3Kt2dcj/GKdHkggH+lbjUsFPkeREKUIACFKBAagGnBN733nsPMgWZBNvu3bsjIiJCtUSC76BBg/Drr7/myr7JDYH31RWv4uKti1ZfWwJvwIYA1xkNdkDgnX1gNoLCg1Tg/bTFp1l+1s7Hn1eWfkX8ULZo2QzPw3l5s8zMAylAAQpQgAIOF3BK4G3UqBFkLl4fHx/r0sJyJzLy26xZM0RGRjr8xpxxwtwQeHV41R65LvAeXQcs7QtU7wj0WZKlbtWB1+wCHPacR+qHZXoyqd09d+22mqasXIlCqrRBb7LP+et3ULZEIZQvUShL98aDKEABClCAAhTIXMApgbdhw4ZYv349SpcunSzw7tmzB6NHj8b27dszb6kL7sHA64ROMbn4hLTQnqCa0R1JqcfiI4uztHKdXnr4p+EtUbuM5eVBvZAF5+t1wnPES1CAAhSgwBMt4JTAO2nSJFy4cAETJ07EK6+8ohahkGWG5e8dO3bEu+++mys7wV0Db/MlzVW9r0u84BZzEPi6JVC8AjAya1Or6VFusyO8Zs6jSxzkJba3WlRWz7uu8+V8vbny25+NpgAFKECBXCTglMArU5PNmDEDCxcuREJCguKReXkDAgIwcuRINYNDbtxyY+BtVb4VZrWelSG3nrvXJQKvtNTE4hNyuJmgaoQyc55vt5/C5HWR6PF8OUx7vX6ywOvo+XrnhZ5C3J376NGwHEslcuM/LGwzBShAAQo4XMApgVe3WqYlO3/+PGSVtfLly6dajMLhd5fNJ8wNgVf/Gl5T2DLK6a6BVwzMLMChXWwxTPnoRVyIQ6dZ25LV8eoR3pS1vWYfWz0H8JJBTdHsmZJmT8fjKUABClCAArlewKmBN9drpbiB3BB4df1qrg68ei7eBn8BYs8Ab/5k16NkfHHPEYG3TNEyCO4RbFcbZGcdRA9OeFW9zKb/Ll+TBSoctTHwOkqS56EABShAAXcRcErgPXv2LKZNm4YjR47g1q1bqez40lr2PU468Bb1KIr4e/E2vXDlciO8OvBqJjuXGe65tieOXbPM/ZzVwBsWE4aBwQOtHZWV8+gR3Tn9GqJdbd9kgVeHYLNPgsz80HLqFnUajvCa1eTxFKAABSjgLgJOCbx9+vRB5cqV0a5dO3h6eqaya9KkSa70zA0jvDJ37IX4C5D/jg8db1fgtWUKM6d03IHFwPUzgPz3xlngzXVApZY2X1oH+IwCr/jI4hzpLb/siMCbclYG4wivo8LpzpN/oM/cXQy8Nj8d3JECFKAABZ4EAacE3pYtW2Lbtm1u55kbAq9GP3rtKHqt7YXqPtWxosuKDPtCB0SXCby6tVlcZtgYeJd3WZ7m6nGZLU6RsjQkKyO8wRExGLxwH+QltZFtq1mDqSNHYxl43e6fGd4QBShAAQo4QMApgVdGdtesWYOCBQs6oMmuc4rcFHhFTQe/zMKaOwfe9GaeGL5lOELOhqQ7Au6IwBt35x7qTdpoHX3VI7HygaPm4tWzQTgyRLvOdxxbQgEKUIACFMiagFMC7/Lly7F582a8/fbb8PPzQ758+ZK11tfXN2utz+GjGHid3AH/HQKELwG6zwYa9LX54sYR3vQCb2ZTjulArC8a2ic03fKHjBpmfKEsOwKvLptg4LX58eCOFKAABSjwBAg4JfDKssKjRo2CzMeb1nb8+PFcSc3A6+RuC/kM+HUK8FIg0OoDmy4edzcO/kv8rfumF3gzm3Is5RLNWZ2jWL+4JmUNu09dQ9nihXA+9k6y+XlturF0dpq0NgLzQ0+rrzpq1NhMe1IdGxsNrBpmqcF+OdChp+bJKEABhPT60QAAIABJREFUClCAAukJOCXwtm7dGoMHD0b79u3TfGktt5Y6MPCm/Vit+n0V1pxYg67PdkX3Kt0d992XhcCb8mWzyf6TU7VJXlhrv7K9tZ1plXzo1ef8ivjh4q2LWV6F7p3v92JT5CXU9PPCkYs3VT2vBF9HLT6hA7XLBl69VLQ0cOINxz0bPBMFKEABClAgAwGnBN4XX3wRv/32m9t1BANv2l2q610d/tKbAwJvWm1KcwYGWdI4IQ7wrQN4FrfWP8uiE3sv7c1y4DWWHIieLCssAbiWnzfWjzDMPJEQa5lz2LeeXd83Lh94dR8y8NrVr9yZAhSgAAXMCTgl8Pbu3RszZ85E6dKlzbXWxY7ObYG3x5oeiLoehfRmKtC8Zl9a07/+d3jgPboOWNoXqN4R6LPEpqchZZhNq00LIxfi87DPk4/wzqibtMjFOhz1fkrNcCGju2WLljUVeI0vlckFZToyXcubbPEJGQmVe23/mV31yi2mbsG563fUvbhkSYOuw5YGDtlmd6C3qdO5EwUoQAEKUCCFgFMC77p16zB9+nS89tprKFOmTKolhTt37pwrOya3BV4dRDOrP3XZwKt/HV7RHwhYb9MzY0vgTTkDw4YeG1D2i1qW87+5Dqvu/6HmMG5VvhVu3r1pKvAapw3LNPAuSPq+qNHJ8qKeZ/FM79k4t6+jAq+ts3tARqVjDgOe3ukHWeMiInbOp5zpzXMHClCAAhSgQDoCTgm83btnXMe5atWqXNlBDLxpd1tmMx5kubOzEHilnljCqt7SGuFN9UJaq1loPC/pmX1zHcad26Bqksc0HqMCb1B4ELI6em1cCU0H3o/XRqh63mSLTxh/9S872viinqnAKwt7HPgBqNjC+lKgsb5Z/SBQtGz63WdLfe7EYo+PZ+DN8rcCD6QABShAAfsEnBJ47WtS7tmbgdf1A68evdW1t/Lf+e3nJ2t4u5Xt1Gp0evnlefVHofGqUZZ93lyH5jvHqqArgW/176tNBV45pTGUShmDrrs1G3gjLsSh06zHC7zYPcKryw0MI+jGEfLMfjOAXbOBDUmzZ6T1QprM0DDDUJNsY4jXnSUzbsgPG2Mbj809/0iwpRSgAAUo4BICDLwmusHdA6/8Cn9W61l2C2XbCK+0RI8Q2viGvy2BV//KXu5XFp+YUXsQ2qz7P3XfR7v+A70O/VPV727suRGOeCGvw8zf1IiubBJ43/0xHCv3n8M/etVHr4blLN76V/9NhgC7vwZsKONIWS5hd+DV18xq4DXW5448CBSvaLkXGfk9HQo8emSZVk5vdgReCbsDgwfi2LVjmNFqBtpUaGP3c8kDKEABClDgyRVwSuA9efIkPvvsM0RFRSExMTGZtixCERoamit7ILcFXr14QmaBIbM5aTPrrNwUePWSy9VKVFMhSpUrlGyEYXv/o25zdv2OCIo7jL41+yLwhUCHBF7jTAoSePXMDcaAGje/HaIuH0DRBgNQY+ecLAVemQHim/6NMusu69dnz6iAoBLF0CrhHmYNPmq5/wOzlYlsmY7wplef+3ULIOZQ6nZImO8wNdP2GcOu7CzT3X3a4tNMj+MOFKAABShAAS3glMArszRIOJRa3rFjx+Lvf/87Tp06hQULFmDatGmoVSvpBaFc1i+5LfDaOjrpqMBbpmgZBPcIdmyvOniEV//KXkodGvs2tgRe7zoYFm55Ka5n9Xo4djfWOqpoq2FGN60Xh9Bz7+qZGwL8K2FCl9rq0LAvn8HAkkXQyKsy5h/8FfCtCwzZnqGlDs42ze07pQKQcEOVbKhFIGKjMfyH1ggpUhiN7iRg/hDLYjDGwJtp3bKxPrf3YqBG0kt3xs/lpPX7WFbMq+iPVS0HqfpoGV3vV6tfmvc3bvs4tY+eA9mrgBd29Nnh2OeKZ6MABShAAbcWcErgrVu3LsLCwtSiEzIjg8zaINv+/fvx+eefY+nSpbkS2R0Dr/ElpbTqXW3pKF0TK/umtYiDLedId5/PygOJcUBgtE2zFuiwJC+cydRjKcNSmoG3cFUMi9ismlC3cgX1X30f+iU4W8s90poZwxhMlw1uBl2KYFx8YuGX5fB5yRKW9h6LsHBkUsaRMvB61bSsZJZqGWSZTWFKUrmBDrxHk2qV8+aF18OHiI+agIDWDXC10HcqbMqWYeCVeYu/NswjrMsVUtbtyonka1LaUNEfAX6l1awX1X2qY0WXFZb7NBwT9+FZ60p5UkMtnrLwh/4thYzQLzqyCGWKlMGwBsNMPVo8mAIUoAAF3FfAKYG3WbNm+Omnn+Dj44Nu3bphyZIlKFy4sFpq+LnnnkNERNL/oecyZ3cMvMaXlLIaePUIcbYEXv1rcxvf8LcGztKvYOClX5KFV/mLMfC+UesNjAwZiVaPCmHW6WNpBl7j/ilffkvr8dUrtBnLAWSmhl0n/0CDojdQteB17I/zwp9+OAff6vPRrGIV3D/WFDUTh6vyAmV46oxNgVePHKvFLI6dhle1Seq4VCUsxtkUkhzPbxqH9hcswVa22sf6w6tGK9x/+l8qkGYaePUcyfoEOvAaZ9aQUWqZWq1mJ0s49q2Ldk8VUS8MyiaB9nB0PoRs+A+m3LS8/Da7/VgEHVuiRoClnnzKnilYfGSxGo3X/Sf/TRaYc9m/I2wuBShAAQpkv4BTAu/o0aPx0ksvqbA7adIkSN3um2++iS1btuC7777D5s2W0bTctjHwpt1jLhl4L17GQL+nVYONo87GACsjhPJiVKNHBTH/tOVX+ilHeO0NvNpCRphT/co+6SWvxObvo+aO0ihS2fKC4LOnO+PVYoutgTc0JhbedzIf1da1wVIL/NXOYBSuOFedT9cfW3vLOOVZUjDdvLgTRt5PCtYyk8TZdnjg1Q2lq8+zBt4Ma2f1OUvXAS4dfrw4iEx1tmqYKmNonnBQzXahFj6Z1SSZr/xFln3+aFEhvHpvC77w+Fp9vXnV6rh5/461fljXXOt70TNrpOzX3PZvCdtLAQpQgALZK+CUwHvt2jV4eXnBw8MDly5dwqBBgxAZGYnixYvjiy++UGE4N24MvNkTeDMMlVkd4bUn8EoNa8xlhHl6qpBsHOm2J/DKy1b+S/wVUprlAPpeXgpE1bA4eJa2lPrUPvcSXiyyxhp45z16Go1P731cb5vON0t6gTfV6OeSPsCxpIU7kgLvlH83xGKPu9YzN79YG8Gx/aDLIuQL2iHuzj30nrsLcQn3ML5zLbSr7Zv+rBJJQTiu5Wj4n7OULKgAvv4zq6++aMOnWmDrb53xUZHVGPhgmfXr8kLhyq4rrW17dcWrqqxBziM/pIzYMsLUYiC2/tujS0+8PfPj4MR2th7G/ShAAQpQwAUEnBJ407rPmzdvomjRosiTJ48LMGStCbkt8G4+s9nyK/sMphtzdElDpm/2p0GfYajUU1/JymMN+qY6Wv/6XUKSdwFvVfMpn827eBnDfUsjPs+jZDWtellhCU/dq3RXSwhXv3sXK87HmA68Rss0A69evriiP567Wwz3PQ+r++l4rjoqFtnjsMAr50xWx6uvK19ICrwBX1fF3kKeaFTwaexNvIzn/iiD3y4PTxV4Z740V4XdyItxqq3WmSUMSzFDVogrXgEYeQhICtdhHSdj4JFv1DHqZcYz57HwUayqU9ZzJMvX7t1oCN+i4dh65iRmFy+mDFKOUMuLdFLSoMsadJlDejXGEtA3Rl5Ck2dKonyJQtZnRkaL4+/FQz8rmf0rsHzfOby/PFztlmzO5MwO5NcpQAEKUCDHBZwSeF944QWsXr0afn5+OX7DjmxAbgu8toxO2ht4pQRAjjGWCRhLGrISeI1z56aqk9W/Ok9nDld9bX1dXUMbGn0WIypUwd48iWhdobX6nwT/RZGLki0kYV1G99SZNAOv/pW6LTWjmQZePXtBRX/Uz3sVD3HHGngvlwxXAVS2oQXKY9ixUMvywmmEfP1MpzfCK1+31vEaX1iTL8iMCc/1Rd1fLS98yQwVMg1bretPY88fAShaZap1QQ655w4l/oHJ6yKt30Y9ni+Haa/XTz4/snEmjaRR7FXtx2H8sYXW42Y8KomwuFNYXMxbrWAnLwNGXY+yfn35+YtYVbSI9evpzeAgB+gf5CQ4Sx22hFjpW/mBR7aOM7ch8vIlVPG7h1/+2kd9JqPv7Ve2VyUWmc4+kdQq/VKg/NXuOY4d+Q8Pz0UBClCAAnYLOCXwvvzyy5g1axbq1TOssmR3U13vAAZeIGXAlF5yVOCVc6Wa5cHOwGsMsAGVqqrAqzcJxRJKjUsFZxZ4jfeX2QwUGU7pZZjV4GjFxuiV95K1XQGXC+CQV9zjwKunSctkoQYdeGUBi8ANP6BwuccB0zpKanxhTa5Y0R9hz/XEwPDp8HuUD582GK7+XO1OXhy4/LaqAzaOwLZ+NAvHoyJRs0ELtVhGsZqTVFCffOUPdLubD7t7h6Pp95UtofLdwxi49BWM/SMWYa+MRVDE4xXuuj4qjAsJ19Q96n74Zvc2JOIq8nnGYMalK1jk7WX9uh7NTetfAWPpiMxqISFW3+97y8Pxn4g91vpoqROWkfyUS06rumKfGqlOL/vJYiRv1HwDS38roO5ZNuOMGmm1SVa92xR5CWVLFHq8mIjr/RPGFlGAAhR4YgScEnjl5bQ5c+Zg6tSpqFSpktvgPkmBV6Yrk7pJmQu1bNGylkBjqFE1zgSQU4HXOKWaDjauEnhTzXhhCJ4LK9XD53lird8XXa554GKhm9bA26pQWcyK3GktP0jvG8i4RPGA/0xGwac2W8OqdUQ65ctlFf3RzjMOF+7eUCPJ3Z4bhPa7x6Pk/Tw4e/6dVIE38GRt9M3zM674NEKzWy+hUJnlqjldb8bjr/cro1nMu1jm8TFqehzDwJov4Njtixh6/QYOVH8dOy8Hq9FUvZCFvg8pt8CDQqg3aSMKlNqk2i3HLCrmhZt586rZG/Qzl96967pe/fXqXhUwvdUKtJy6BV5P7wRKrrYeKs+GTGUmq7ZJOYOMLEuZhYRqGRk2ruKmp9iTF/Z+j+iM3aeuWc8ji4bo7wMpm5E+1qPKesaMWn7eWD/CMF2b2/zrxxuhAAUokLsEnBJ4hw0bhiNHjuDcuXPw9fVFoUKP6+iEa+PGjblLLam17h54jQtH6NFKY/1vWr+yT/kWvQ6e9nSwcWQ01Siqnv6qekegz5Jkp02rPcbAO66UD9Z4FbUek9YIb48fWiLqXiyWPyyN81cOY2Tpp1LVPFvPOSCN1cMMLdIr28lHqQLvrtnABsvUW7pdjx54Ik++BLwVexvhBfNaA2+jIuXR7fQBeJd5Do16LrGGqpSmOvAuf7Mm+q6bZQmOhoCp6nh/GmNZ9CFp8YfZFesgKG8c/O7dx8Zn++N4ma74067e6tQJlzqrF+lktFSmApNt2Yk8qJU3Gg+LlUddLx/k9biuPpe5e2efKYbud8bhX4Un4tPyt1VYVfd+Jz92PyyPfEVOqdFcKUHQ5/PLVxgb39iN4IgYDF64D00rhyPCcwkaJD7EgYKW4w+9NNuyOIbM+BB7FmjQ5/GyxUkIer7loo/yqDpt2fr6foevQy6iQd3dOHH/v3iQ4KtGj/UmMzwE9wxGzzU91Q9zsqUsVTH+8Iboybh52wM1/bzU0tBz+jVUL+z1XNtThWc5Vu5PQm+LqVtw7rqlREUHY3u+B7gvBShAAQo4VsApgVdGeDPaWrdu7di7ctLZclvg1WE0oxXQjKFRhY2kUJdWXa1xX/0r5JTH21ofaewyY+BNtWiCcV7XgKSZBpIOzizwym6ykIG8yCajemkF3oClbdRLWzIzQljscfXSVMp7SBl45cU3qQlOOQqpX5hToa90IySrRzZMDdaufBlcyJ8f92/WQn6vSDW6uaVIIRwrUMASwoqWxc3YaLVPRj9A1JsYDO/Ei9hecASmFy+FeSUKq7aLi4xAqlH4zdOA6FDLjA8LOqN5xXIqmMpLfY2bjMTOioMwYUsLXPQwtKf+UBVSxUxqa2vcvYfNhQupHwYe3i2OGl55EZV4DV0ulsUPsX/DC2U/wxHvG6j2MC+i8j5EoYd5cPtRQRXm9Wjt8B/bI+TOeXQtUhmf9lwDPSL6XsPjmHP7W+vjoFZ9azoRqNHp8WIZaZR2yD3K/8rsCMIW3FYrxhW68RdcvlAPDZssQVRcOG6f64d2dYphW+xXlkBcoR0CK3cHfOuovpZ6dNn0M2f8DYZ8nnilDe5ebavqd2f9tgfdG5bA9O6dkpXwyHMwqPpkdJq1zXoPWX3BTfpMvmelnCKtTdqnR5Sd9E8eL0MBClAg1wo4JfDmWp1MGp7bAq/cTmajk1kNvDrQOTrwpnrpLYPAq2dckPuUkWiZskpmXaj2KD9Wnj5p6c2JNx7P3JBGDW/AIn/sfRCHeUXqIOxcqE2BV0yldlRerJLgr0OIHvlLM/AmzV4QlzcP/CuWV02TQKV/na8XnUj5CKb7A0TMQVSacRbT8gehR/5t1hkOZH/ZpIxA/VAS8VuywGudZ1gWt+i9GDsLNMPcjU3V6LLHg7K4l+88Xn/mrzh5a5d1tovGCQnWUWkZBR5V9bR60a3KjZI4HjsSBctPxN28D7Dh7Hn0LOOH+HyWkVrZ9A9QR7Z/j7JbhuOilz+qj/oJenR6c5vz6H7hn9b9W926jVk13wZKVLDM5ytbkyFAh6lpf3dOLIaF3l5q9odSNyri7u3RqNZgoWr77ehB6P9ca9SveRzjQ8djw+U4lL0Va53uTf+AIj8YHDxWHoeu7UdYwqfWl/ZkBP5pvIqyT1/DgT+2o2jCy5jVrb8KylLqI7XD8sJcx1IfY9k2yw8rssnUbW+1sNQ1Szvke+RRXAscOJWIL3rVx6OQz1BszzTcrP82vF6bpvYz/qYkrT7Xtefy/cGNAhSgAAUyF3Ba4D106BCioqKQmPj4pSHdvL/85S+ZtzSb91i5ciVmzJihVn9r27atdYGMjC7LwBtmHRXTo8Y5GXiNI8MSwNNaSCKzwDt8wQsIyXMHk5/piQv7vk0z8KZcLtj4a29jyYfx81SzOiTNXqDn+q1boh52H2hqqZm9k2AtZ0j5/KUZeJPKIyIfVlTlBrLpMgmZAUFexpJQptpw9bY18B794TX0Kuv3+AeCN9dh58Na+O/al/Bz8cfTBb5Xbwa2XlpkDbyNHhaAv5+3GhmO/30sFtbagqF3w+DxMD8qFm2B329vVfcgcxn/zdcXWwtZwp+UFEQO3qT+/O26rXhrbzfcylsERcZEYtOXA+GVcAF1SwJ/LfjH4xf2rt/AMBSzTHN2eruFo6I/kGJ0X32e9CLg+fz50L58WXg+zIvOpX7AimuWEo2bR6ZYXzaT57Tx169Yztf+M6DpMOjnp2fV3pi/pgHyFT5prWH+/foZxN69nKw7Ht4rgVGN38LMA19AanxlhF9+sCh4vxquHh+oriU1vwH+lTChS20Ya8xlNP/Ouf4oV6IQZtz+EI3yHEFkgbqo9aHlHvVUa/qCukZeXoa7cuciPtwToAK28QdCOf+IkBEY23isdco2a4PlB8WtUyyO3YMy/ddUXtaT0WqOIGdKxR0oQIFcIuCUwPuvf/0L33zzDerXr4/w8HDUqVMH0dHRiI+Ph4Td999/P0e5Tp06hf79+2Pp0qV4+umn8e6776JBgwYYONDyK870ticx8MpI5o4+OxSJcURV/i6jd9keeOVCxmmvDJ1jDAkZBV5d7ynlAbKsrXGWhtnz/VVN69CKHYEDSzINvHJ5PcKn60D1KGay+s+UM04k3cPsslURVCARfcu+jG92VEsVeB/cqqxqX/WWatU0CXkLOqsXCGXzfvgIKOiNgBKeyWY40G0JfVgG3tG71Khm2LqhGOiVB43uAfPPnQGGbMP0Q56otrMvdvhctdY7S+DdHvMzdl0OVrMx1KjUBr1uHUDxBx44GzUZ25/+B0YUvYiogo9HNVWJRP03Mc7DG2vOL1Vtk3v5tv18NHumJGSKr+a/9UOTfEctI7a7LSuryWastR52GRh6K2kFuILeQGLc4zl+U35jJo3+33xUGD3KF1dlGXPuP4XB+a+gcP4iuHRovAqY28e2BoyzVSSVSOhnt1TByjh1YDA8fLZba5gL3vgTvtqzCvWqnkXbajUx58ACPMxzB88UrYeT8QfV1GrdqnTDKz++ijsPbiHPmf4IrnYOb4VXg1fF57FsQE0sXNQWn3skWFutSyQOFnwb3nluq2nYwhq9h+41WmJq2FRVFyw/QMksEfJ9J+UgUzccxepL45GngGU5ZnnRTo/y6udafy7Pt7XMZkGnxz8wjDyYqgbaSLn80B58vP8t9HhmICa2HJX5v80HfgAa5PygReYN5R4UoMCTLOCUwNu8eXPMmzcPNWrUQJcuXbB27Vo8fPgQU6ZMQYkSJTB0qOXXrjm1zZ07F3FxcXjvvfdUE+QFuw8++ACrVq3KsElPYuAVkJR1vRpJ/g9ZAqSuhZTPM1rkIj1c48teadasphN4jTWzEhAkhMivrmUKrE9PH7Vc7s11mB17yBpy5VfHEij0CFpWA68EbL2QgdSASlhRyxSXbmRdmjfZC3hJ9zC8UnXLiHL1ftj5R1Wsv/pRshHelIE3VS3w1y2wOe53fO5XDt6XnsF7N6LRpO94BGwdlSzwWn9df7cw2pw/qsJt2IZRGJjnsnU0Vka/JYjW+W0I2ubbBxkpDSz1NDrWW4jjl+dh+Y3t6B97H0Xqd0VQ9Hp0vFUAy858jM0+U/FUwkEM8O2E3wseRJ57XuiQOAxT/98bmL0rGEHHLN9XideaY2zjQPXrfanZvbnre+sSwsZnQZckyGcSHA+WWmVZrjjpRTu178QbwM9jgWbDrOFt41cj8OrVBVj0qAPCfQ9iQ+F8kJIIqedtVLIOQrZbamHVS2T65Uf5wDBirH8wkNFg64wR9YfiRJS/mpJMlye89uPf8PudrdZm65FW/6/HIq7Q49ry5xLuIfqRL+bkTcSIfLGqDrtKoZfVsR55CqN5fCC+uvymOo+u5S5X5Fmcu3VClVLs/MtOawmOjCJvOhqNOx7hKHyvIB56AAlIxHv1ZqLOyfV4Mz5YnadQviIqdNf0aoX2pUdhYNlz6ocivZ1v8wFCSpWz1gfr6djOXr+Djv8MxsMyX6qXEfM+KoT1f/oZZb1LWo+VZ1xmuJDnUKZ3w6qhgATepFFy2VEW+vAu5KGOMf5Zf6/pMpt0/3GVuaI9i9v8fwdyXvl+z2wmD5tPyB0pQAG3FHBK4K1bty727duHAgUKoHPnzli3zrKE6o0bN9CuXTvs2rUrR3E//PBDNGrUCH/6058s/8ecmKj+LmUYGW0MvLOTTTGlR5qMgTdVQLOhp43BNc1f4dsQeOUyeoaCoQ+9MSzasopZysCrX+jSgcUYeI9GrlBhyTjlmpzCWNIg/2f7edjnqj5WQq5a1S2prjLdwGuoQ26X9wIu4AGWN/wQN0tVsYwW37uvRifzP/TBnbhK8Ci+36rWqFhVzO/+H0uY+D0Y4zcNw5bChS3P7bXmuHupK06PLI+AVT1U4J3q/zU6VvG3/rpe9usWH48x74Rjyw9dMD7PNRUKZ12+qkKkBN48Wz/DSA/LNWS7UqQalnnGYo63J5rdroJrfg9w7MYpfHE1HoOvfAU9Qjm7yWY0aeCJ178JQZGH1dTyu3K+eRd6WNp3pQ26VAhQC1VIze6R02cRWmAEvPLcVl+fXHQcxsd/ijBvHwwsaZlNQ4Jn6MiGKDu/MfBaEPBzIHDjrArs+Lol4FlM9eny8z64+d/RGJg/GJefH4VDTxXCyKhF1nvo6vEU9l+ZqGZXUC+RRc8Ffp1iaVfZZij4zgb15/YruuH8rZOq3tej2F5lLz84rdtWRZUn6BfQZu9diqCIT63n/+ZBB2zxbI11kafx6Jl/Jqtblp1kFgspAZFZKeoWmIufr79nmW+49iC0Wfd/6ocLKcMwbrXzVEDnin/Hv/YdRHzJz61fyvfAA0tjzqh+l1rvwonFUPuRLIVdUE0PNyz2hvVcr5+uj2FFo5Bw53eElKuNVfcuW1+G1CcMuPkA/69SJ0yIboBVDzbBo9g+67VqPWiJZa3/gtWXdmH16Q0IS3g8X3SzOG9MuHEEFz081LVDS7VH+ImO8MMVJFb8N4o9LIzEy9VR4J4XPEr9geOFwtR5SzwqhQHFh+FCoTK4ezcala7vVJ/fKlAKVa/+gtv3zuNgqefgWeH/t3ce4FFUbRt+Ewi9CUiTAEovARRCMRQFpCrwCaiISrEBFkD9EEQURWkfCjZAVMACqBRpIqCgIggK/EiRLr1KDy0kgfzXcyZnMrvZbGZ3UtjNc67LC9idc2bmPpN477vveU9TqZ+zrMTEnJLFZ3+T6nnLy+0VnpF1B2fIxtOr5FT8WdkXY0S680iYtEgoJ8Uv55O4awlSKHeYlCpkVAO6mBArhy7tkdBrV+VqvtKSkC2XxOa+Wa4mZJeTMSFSIOaY3BEWJjdly+nCH7U+kNhzOTZeLl29pt47nu26HMrhWmXIpZOI5Iy/KHkTLkqeHNnc35Jr1xPMsZK96ecL4ZJf8iQYHzBSapdD4uSQXPDzDOx2oxB4u0fS7+Ub5ZoC6ToyRHjbt28vI0eOlOrVq0v37t1l4MCB6u8nT55U+bJ//fVXpjJ74YUXpEWLFtK2bVvzOiCzyDnWWx8/8MADya5x48aNsnv37ky9dl9P7p5/6t4/tUVrOD6lCC/EALm82L5YtwwR3nNG3mqr5U+pCLNu+utg7OrVfP9G42W3CK+78M6b1lRJYPvi9eXo/l89bnxgZWjduAI5lAv+WaAECQ0ijKgcXrNy09HF6LINJCrUuN4t9UdK9G1NJGpmlHn9N2evKgcP1pAKt22XvFd2yK6QeLEK7/LFfaX/yaRqAIgGXz74tIpg6q2CkY7Q/fbm8snaDfL5to/lfDZDLnCNF/6YZKRvIE+R3NNsAAAgAElEQVQ2oYDIgK1mtQREMq9eOC0d1jwot4SeMhfBFZcWckJ+Mq5530GpefUT2ZzzSfXvWff9rTZZKDfoe/VvXAeE95O9zyi5g0RWLlhb1aXVi9T0Irs58Y3l2/Ah6qv/6NBQtQPe7PWHZO+eRoZk5jkiUqKmSGLus0saRK6CMr/Ec1Lin9lGikSPRRJdqpYLS9zjthzvyaKDOVQ5sWYb+0nYHkNyVUPE+K8Z8uCeTbLt0mKplquTbDn9f2YptfWTJsvt17dIeN95ckuJEi41qMtcTZDvjx6SN+MflcMJN8vksHdFiteQ6Md/kLkTH5Ld2bab6SHdEvLJ2UvPSI2rg9TCuva5bpG3t68xq14kXZCo9JFmFxJkyrW28kWxEIkr+IckxBSTr87ultox5wULHluEl5EroUYZNrTPjoVKvZj9MqpwIbVLXan4eCXbuuIHjsl37brEXK4oFRNOqWoa6nk4fVYdN/TmIpIvQaTvmbPq+vAa/kNkWvdtdvmyS3k/6zU3vSCSLdtl80OY9T3d37qI0f19f/6tPyD605d9SCCQCKS22VEg3UtmXGuGCO+CBQvUtsKRkZGyePFitSCsadOmKp+3atWqarFYZrYhQ4ao/GIttcgtbtCggWzdmhgVFJEzZ5IKzutrrV+/fpYUXh0N1Tmz+OoVq9OtFQH0V/npLry6vFflthIRa8yX3kxAzxNKjEXuX2/8MxXhXTetufE1f8GKIse3eBRefd+QRggvUiLc84FxKp0bjAVAyO/Fbl44FouvKu9aLkertJbRZzYYKQWVe4ncPdilxFWJHNVk96bHjG1sD/eXiNBD6hbMDxyz7peJl3dLt0IRMv3cFkEVgYu7hinRbPFZDTmRPUTGVh8nreq2UOL53vLdMrBEHzMvWXb/pPor4S1YQy0Es25esfaf0/Ljzz/Kd7lHyIZcYfJ0sfzmj2ndhJwydf9ueSruBSV4yJvd2n2rys+1jjH+x11mZLTrZOObHFyf2u73mJF3fE+14mpXMvz5yWN1zXNYx8G4qiGNwZLvi3xl5PWeCC0mp+NzG4v2EP0tUVM6LehkbleMndvK5qonLY4+rXg+sr2P3Hwm8ZkQkZXtlkuT75vLd4XLy2sF4wTsj5y9Yghv5KsS+e1TxvmRVvEfI9+43udt5IocVlHVt0+dkX9uaiLnC1WVO/Z9bG4S8tmqfbL9h0mytvxZ9WEDlSvWxtwpDXL9rqKw+a8nyO8HDsmo8rVl+vUzgm8jdpStI3nOnJbndvwgt8QbkcUVUkX6lSghLx+NlUdCfxdBHeqdi5X0zs+XT74sWEAiK7STt5v+TyTmnEQf/kNa/T5YLibEqf4h13JI7IUa8njcEfnvRSPSioa8YUiutUG0O168JD1LFDMXDxaOC5Hqp8vKnZfipY4clh/y55CpxWIlx/UwuXKltLS/tk9+zXvdjGxjwWDrK6XkYO5/JTQkROKvJ8gzUlAqXMsuvUL/lX3ZrynxrhIbK1ez55f4kBySPSFWroQVkrDQfFIz+phcSTgly/PmlesSIk0v5ZANuWPlZHaRYvHXpdOFvFI0LkRuuxgi/+atJAfyh8jqXIckNvS6ZM8WIldir0nctevqtnIlZJP810vI5ZC8clPscckdGieFrp2VvAmXJE/CJTmTq6yszZb0oUGzuBISJ7kTwiR7aIhkCzUWcd58PZuUi73kwsv9H1ez5ZdLofnk8tX4ZMdlyxbqMfLrdcBU3jwUEi1XJPm5rN1yS3YJx4datoAmMLKX9zTLgL65DLj4DBFe9/tYvny5SmMoXbq0PPTQQ5Izp+tXSRlw3y6nQH7xiRMnVN4u2ubNmwUSjFxjby0QUxqsC7ZUDp5bsxPh1cKrI516YwJEVJEPCNHT0dVk1QlsTK41pcFjDvC4GsbX2lh8s3GG+dW0LrFlzZvF6cyFWviHu/AeXSPrT/5lSE21B2Xdu7dJryJ5pe7NtUUOrvUovHo1v7XGrXsaA3IKtQjP3zNfpTpAkBH1dW/dzkfLoIje3oU3+xyJODhDddXC23NaXbVV8pRaA+TZvyfL5fhLku/ESFkz8F5TnL+pNEqqNWxnSqiL8O77TZUT8ya8kOTJETvlWMxWGZs9SZTG56kizf9eJj9eq6Pyff+4VkWqvrJK5W5qUUUkdcqqfabwvrnwbzOlQMuvlYUS+3sqmS+9+O0ml7xZ9YalfrH6N+oJf9fHeB50Q7RWxCWNQy2ii4mRtderyrC8r8iSK4+qY/aGlpPbru+XH0LvkjbXf1ECqcvE6eE+DOksTfe+mzT+XYNFzh2QLy6HyXv/JsikmG/V2KoCQsHwpLJv5RqrHNao0SvkQky8vFr+bXniyN/mOC1Ll1KpK5DxibfWVLvSTTl9SSJf2CsyqZH6wIVIdtyGryQs/qI8FPuqfJ3jLaM/nn2wwCYiaLW6SnS7MS5VFbCodPO/2+SHP4tKyOUa0ivqVuldfLvknvtY0r10nCAT5LyZmmTUJu6gNvrA74IpWz6XbBebyj8Hi0uvRrepfvgQ0+C2Iio1BW3N3tPSsFQ22bHnB+myYYRxDGo+l2nu/qirf5v1g7GRCJhhUxGbTVXXKBFp82geRgIkQAJJBDJFeG+0CcAOcKgWMXPmTLNKQ6VKleTZZ5/1eqmBKLxWWUPZLvfmj/DqXFmIJv5npCObegtZX7+G8bphAy5Yf60N2dm3SgnvjhxhRomtmyqp/+lDMHXbcuy8SIwhQVhcMyFXUvR13f6fZP353Wqjicgey2XdqOLSq2QxtShHRXgThTKydlLFDmzCgLQNHHP00lGVRoEFeygThbq/SOvQqRVYwNZvRT91PZpTyYRsUuXyBblQqpZEXz4pjx79RzrWeS6Z8JbNEyFbN3QzIp/hPyYTXrPyQtuvpeeqkWpzhXKxL8nCJ7ubwruwaHcp1+4lU0JnFeqVdH/nDhqbbCRuOoEIszWqClwQU5TXqhgeLfOOv6o2j1ALCS9eSqqLi/qyCVWl7htGBFdHkyGwU1fvk+iYePnt5Wby0rd/JYv2Wp8/d+G1jmOKsLW6AqK7gw/J/u/HSrl1w42hIJwDjEi/tZat2q1t5sMqGrzsWh1pmW2DikrnKF1Lch5Zo1IRSoeclG1hEdK/+GklorrNPBkuNS6ulkM5bpPw2MR6zsg5LVFfTka+KOUWJk93kkEHzIVX+j7GFl0snS8aecUnQ4vJZ8VzyvRcIYIUAZ2HjTQRvSmIil4PPiTyXW8lttEJeVQ1BzPKbF14lxjV9vQLC6XMwm/KbS4k83QMFori+XXZHMWPX9T4NgPcB9Ub5EdvdiEBEiCB9COQrsIbExOjcnex09q1a9fUgjWUIAsL855gn363m/LIWEg3evRowTUj3WLEiBFqkZ23FojCq0uJJStvlXijWub0feudsawS6h7hhQChGgJEr0P5DhkrvIhyHVgtup6tVbpxDyqlYq0l0b/pIJlwU0HzGt2F98hbhdVXzbiX/BdPyk6JUwvKqtToaj4Kup4qoriQBDRPpcgg33PazzEXuZmR8GvZ5f2De42v3lFbFlsMJ35V3nJabTkWYnyN3azU/TJ/eT2jdmylX6TT7mmq9BdSI9Ag12pL4Ce2S78fX5cVR+dK8fgH5KfHh5rCu/7kdcmZ7yaZeKyy/BpXRV4sMDZJeKOPyvorR5XwVqr5jBRs+5q5Je73zzeW6Jg4U3gR0UO095Em2eWttq3U1+YyqqzJZHGeDtJ24Bfq3/gaf/iibdLpjtIqQouGNAa9m5r1devPl96qV7/mUXgTa+2qYxK3l/7yl03y6C9NjG5uNXrxAQ5NRQVjzknc2OoqWqrmLFt1iWh0n/kNAV5rLR/Kv4UXSVzBbeqYonEJsvDIGcmXcEm+qv2VPHJslLFQDrvVlYgQuWuQyNfdXH9NWKRbvxE1aoWER28wI7Qrb+okxaoUlS7HfzD76jQRNT4+oOn0CeSoj6+ZdA580NNRUXwAQPMhSup6sca/zLJ2Ofi1tyc+fI0ESCDwCaSr8L7zzjsqZxd1bbH464MPPpB27drJM888E/jkRCQQhVdHcFPKrbVu3oBJcpdbvKYrJ1gXb+nKDGZlhFp9zK9J0zXCmyi8eqtbd+FVKRErP0963poOknnhVY1yZeXby9FT240IL6Kcg06oGr86NUJ3UtFBN6FoOKOhyltG0+Wj8Hdr3qj+UKE56VQLlUJw7ryxUMpt5zi92Axj3Vumu8xcWtUQ3lbx0nNJLzPFYseexTLmn9lGybUef8jw3z6Wb/d+KDfFN5OVj7+XtKMeIoYiKuVg3LXOMizfaBUJR6pJ6JVY2X5ln7r362Wfk/pdX3VZcIavqnWEV41hqVKgBk3cLQ5/XVa0h7R89j31MspbNR69Qgrkyq6iu/lzZZctiRUbIM16Qwb3XwLuW/Dq86N27synGqoopWq6SkdiKSykPty5eYjaYc6aY+vxl4wlJWLbze2kWp1GxgcOrMbPXVKqnX1HshfcILlLGR8q9AYaR64Xla0PrpZW1Uu4XgNq+CZWezDPZ8nz1a/N2nBY/jtrk+zPZdSrVfLcurHsOLFReq5+RT1L3YrWkUGblxu1htGsUVvNOqVNNzzeLF8kARIgARLQBNJVeJs3by7Dhg2Txo2NHK1t27bJE088Ib//bmxcEOgtkIU3pdxaX4S31ZxW5tf5ree0VtOZFsKrx8V41o0uzOfFmtKQKLwTChU0FmNhw4hCZU3ZVnI+zxAa1ZoOknVVW5g1cuXyaVl/wZA+X4Q3pbQL6+s6j9F91ywlvFcSjK+rvQjvw5WekI/nVzA2S3gwzEV45/35riw4u1UGZispjz6yTD7fuFzGbu4vea5VkrkPvC+YDxX9PWxUgcDX4VhghhxQLfQ3h90kJ+POqoVUM4uNkZeeesI34UUOZuJ2v2tKPykNnxhrYtapEXhBCfvTDVWupzV3FyKM3FbdkPZgSq2I4Kv4hyavUcdAnv/XpZYhnFi4dnyL7L7zf1K8TCV5aPJaiT7+j4zr3kQiqxh5pim2mHOS8G6EhGCjDsjqrY3MGrW/57tHHj7VU0oWuSwXi72phtAl26bEt5L6fT+V6qUSI6ATo4zawBBQRHsTF5GpTpaatNbrQJT3yLkr6iVrNBvRVTw3SDFSea/guu83c3Gc6oAo77mDRs5roaTIuveb5bskQAIkQAKaQLoKL0qPrVy5UooUMVYBJyQkSLVq1VRN3jyJtUMDeSoCUXjBW+d+eoq8+iK81nH0363Ci/SIXWd3qa/gdXF7O/PtdYcyDOBJeIsUk4kFckmf4lESWftxc/MLlW/6Vfek07oJ786Tm+TC9ThZfeCQFHjtnO0Ir/s2xjr3ccL6d2Xi31PV+VIq36bkungdY3tcL8ILlmO+NuQGtXWHzO6gykE9VrmfzN06US6GxcqsEm2kSqsxsnzXfum/5j4JldzyaauP1P1XuyLyzfHEXcpEzEVPySLY+w7K4/K6fDbsBRfh1ZFaCPcthXInj/Ba0hrW3fWFRN7VweSsI5p4ISXhdU9tUBtCuDVcAxa7uVdxgAx3nWyUWEMUWTHy0N/j84bcV6QNQB6ROoB6viIyVPrKlzGN1PWeLfK6qqzR6+xlGXDulFGN4u3Xk4azRLfViw9NT0ptSCGf1srEPZrNlAI7vxl4DAmQAAn4TyBdhRdCiBq7efPmNa8QpclQ/aBEicSvBv2/9kzvmVWFV39VbxXelrNbKkHQJcEgmro6gU6LsDth7sIL8cOiL5xXRcD019KI0EEYD6yWIeWqyIKQyzK8SAO5pe5TpvCqc09qkXTqWl1lXUNDiF12QcNX/1hoNKqstAy/RY5lTyoa7ymlwZrrbN0cY/m87jL61J9yS/a8MrWHsXAu2YcICG/l/xgRPJ2fCfl6aLq5YQT6uQjvqHYyYXwZFcWukLO17Llq1JDdUmuQSO1uKnr65C+t1aIyRJaxqA51eZ+sOFYGrDZWtb9ZZIy8dnqgtClVVg7nTCrDhIVSja6+J/06t1Bfu0NuVw9qpvromro6DcFd1BCN3H/kmBSJ6i75C93sMsURw5aq6Kx1MZoeDwfidaQ46JaSsKLSQc03lqnDNr/e0vDLyWvNsmb4d9WS+eWHfol5vHYftMTjoifcIwX+/VPVFI5OyKsWCeYu/YVs+nebyIFqcu3cHZJQsIzJRHVzrxYBydULI73k0yIvGZUssNscGwmQAAmQQMYRSHfhxS5roaGh5h2htm3lypVdFq7Nnj074+44Dc8UqMKr80w9iaidCK/O/7UKr/WrfCDG2Fggp0tzeSqBltJUuAuvXhyGhWSIFhdY/ZGRNwnh/WOiEo2elWrL+rgzMqV4C8lf72m1oAsNVRIKjAhPOlXZKFnX5g3PwovFQNPulZ7lKqrqDLphUwipkrQ1K17XC9fwd5fd4EYlRg0tuZbuTFU0ufHLqiqDajonFSXT5nVTUqsZ9p92QX0Njq/7F35e2Xjvym0iufeq/NIxjSbJzTWaK+F9fElPVTdWR9ndhffX215Q5bXuLV5RDuRJur81e09Jjaufmrm1OiKLa9CCqvNxIZx629jUfpQgd6i126vRrao+r3U8/B3Cu3bvaRU5tp7T07hPfrFeRXmR1vDH3tMye8NhJblju9RWpc8K5M4ur99XPbVL8vi+Vaj1daEqhPX1ZNdnrZCg5jCxCohfV8BOJEACJEAC6U0gXYV3zpw5tq6/Uydj69FAa4EqvN52W0tL4YUUYnGYr7V4tfC619M15fLs+SThTVww1LNKXaPEVvEWEtl6nIqqoqnSa1oo8YI34e04QeWkWoW30tVYmVOxR5KcWh5SvXDN/OBglSCL8OrKGLqrKj2Fc9VOXN3vRXjHzo83Uwn2LG0qY/IYBfAVi7Pn5fb2G5VMLv37uDy37HXJWfh3swayFt4uW56S0tEb5XCB29Wf9xSvLsfzGNUlcMyD4SNl6ur95riehFe/aTttIIUfZmtur7VOb2rCq9MBrAvhvn6qYVJOrcNfHtbIM3aZ0xFY/bp7yTSxVovQ5cMcXgO7kwAJkAAJpB+BdBXe9LvsG2PkQBVe605hj1YzCvDrZld4IZI6LQD5q54ivCgFlUwKbUydJ+HV8oto75JiraTAb+8aEV4tvDWiZP2lQzIlbw2J7JxYjF+fy67wJo5nFV7rLmjul46ao6i326FCB7kl3y1mvVR1nEV4rbWNUYN32f59Rq1V/dW3vj5sAvDLYJcIr1V4s698QO0Cp9vIE9FSpPP/KeFFNHXCxqmSq/gitdAP5dLizt0hT1cbIu02PC6VYjbLmaKRUvjUOnmsQAPZWMRYzAbhHdd0soz/aZfaFAIto4QX6RGz1x9Wpct6RpXzGqF1j8Ii0ottjNOqWUXcmrahF5p5PJ+eN1ZOSKtp4DgkQAIkkG4EKLwO0Aaq8HrbfMKO8CJi+3Lkyy7C616JQEc99XgoAfZ2o7dt0fYkvMhL/WrbVyqXV0Vx105xFd7azV02kHA5kY/Cq/OBMYY34XU5h1tdWlWjtfcqdYhVeOtejZepR48a+cK5ChlD6J3jKreVCSdWuwjv1ytzKCGEcJXb0t1FeN/fm1v+avSV2p0MwvvhmqWSp+xk87KunmwufWr1lVZ/9pJqcVskulg9lavqLrxrexrfxDw4eY2SXmuE0yqCOMZphFfX1sVYEEs0bGHcoHwRM+0hpYdE1/FNTY5tPWRuB+mUCX1dOgUDkeXDZy5L57rhLhUk3OdNurp9yPLnItiHBEiABEgg3QhQeB2gDVThRWRS16F1l1A7wgtkEFprhDelftZcV7v1eLXw6u2JcT7k4o7+c7Qs+GeBDC9xt3Rc87nadlX+mKRmsGdKwqu/esbXzqhvWqiMHHliiSrbZd0RTaUZJEZ4J5StIRNDjVqotoVXL2LSZarQOTGv0yq8usyVS86nrjpRNkqWn/w/6V/cWPyFfOUfNoSqhV34Sr3N+eHS5dJf6j2UHGu7r4Ek3DXYFN73ftks+Su9kUx4667pK42vr5PYotUkx6lt0jd3E/mthJHCcPXMnbJrwMfq74iiollzdK3Ca13M5u+Pjd6UAv2dyrO/1+Cpn1XEbV+Xnjc8NzofOy0vimORAAmQAAmkGQEKrwOUgSq83jafSGvhBV5dwcFOeTKUZ4qaGaU2c0C6BbYn1ovkzMh02bbS95dJxjay5w+pP3veWslzhNda9gv1UhNFNFnpMyfCi+gudsLCKv3EhW/6PPjTKryqBm/OcJE+ideCA7Q4FSoj62L+VTuhoeEDghYxRDV7xX0tbS/MU+9BnHMc6Sz5GzymUgH0cYWrvSlxCZcNmU2M8Ib8MlL6hyXtNvdc2H3yS+lN6picF1rL+mf/l+JPgad6ug5+ZFxq8doWSycntNnXWjLM9nXh2cKcI5rP2rg2SfMwEiABEsgcAhReB9wDVXix1z2qGCDXE/VxUUpsUL1BioS78OrNE9xzdPV2wjpVISVRxpjeFsm547fKOPKEEY1GLjCqPOhSYHULVpSpfy1P6lo2SiJCDxmSeOy8yKCk2rMudW5TE17skLVppkyoHCUTY43xbEV4rdFd1NbVKRSJEV6Xig4Q3oI1jBq8ullKXOktkrXwWnc7G3vzYlN4B54+K9+f6icJZRupTR208Fas9YUcjzW2xYXwdqv8pBRcO9ZVeIv3k1/yfKeOuTnuXlnxxMgME17Uz233vrEdrm2xdPAzarcrrgv1fkvflEfeeaCW3W48jgRIgARIIEAIUHgdTFSgCi9u2RrhtG4z7C6uuuSW3v0MkVdsgwrRRXqBft8axcT4qhxYDmNXqiGrhhipCNgEokJHr8S9RZ+1qJfKVViWbje+2lfNKryI1FpLRNmI8OrtY/Vw8+o+IENPr1X/VBFZ7N6GmrkpNV2KTC9EcxNeK2+16UStHiJtRieNhgjxuAiVcuEuvNbNH14ut0deiflA9cM4Xc5NMReYaeGtX3elbLtkyPSVo10k/nwd6Z9ttovwji83Wj4L+chAF9JVFj32Soq3hm17kUOMllolBQc/SuxKAiRAAiRAAulKgMLrAG8gCy8ip2juZcNSEl73hWS6akJKwmvN1/W2SM4dvzfhtYqjyrnVLY2Fd12DXtLrxE9JwusekXW/aHfBHRlu5AtbFqZpfkp46/dPnvOZGOXdkSNMutxSUp1BM9SlscZGRkvnLb3Ve/H5S0uFk2OMbYdfbmZGeFs02Cl/nDd2ert84Cm5dvk26ZxtpYwNSxL22RGT5I2LI9QxbYu+KaPb/SfFnwJrbis2ZPjksboOfmLYlQRIgARIgAQyhwCF1wH3QBZefdvu2wynh/DqOrR2KjWkJrx604xZR45JlVhjkZXtCO/xLaaIRnxjbCeL5h7hdSy81q2PE0uPac5q04nHFiaVJNMXgSjvzIeN190WQLV5b6WqntAs106ZIomL0spGSbmdz6jeSA3QYvpg41hZfOo1F+FtELpNvs7xlnm/21rNkAe2D1O7svkivMlq0Tr42WFXEiABEiABEshIAhReB7QpvOtTTGmwRnhTk1jrFKR2rM4HHn/ipDS/fMXoWqurREQbi8BU5BfbvJaoabxnTWnAv5HH22ORRPzaN22EV1eBKF4jaSGaB+FVJ5vUSATSba3Ba+P50wvHCoRcks05nzR6NB0k5ZYa9wjh1ceMf7iyDN1oRGx1hNddeE92nisNF66W0LAz8kbzHtL19topXoU1wkvhtTFZPIQESIAESOCGJEDhdTAtWVF4de6uxmbdntiaF2wVXp17a2fHtdSE10yPQG7tucTtXJsOkoiDM5KE1yqUfgjvkahnpfXRBWo8lcPrLaXBOr5eiJaS8HrI7bXz+LmUzMr1sNGl4wRp82u4ivyinu34H3eZO7K9sPZelWedkvAixzli2FK5EBOv+uqas56uhcJrZ4Z4DAmQAAmQwI1OgMLrYIaCQXh1ioD7RhEai87R1TKLqg39f+5vUrMjvDjYPXUiJeypCa+uIWzWs8VAfghvy/XD5dilY+oy3FMarOMNP3laOsZnF6nSzogaN+jjeul2hVdvTOHHNrQuJbO08PZYJA8uzW5KrlV4IbC6ugMutnTISVmVs1/SdQ87L6hKEB0TJ9VLFnCpu+s+L9iy+OkvN6iXGeF18MuCXUmABEiABDKVAIXXAf5gEF73kmGp5fAicmvdVc1X4bVWb/CEPjXhNd+/EiNTjxvb7OqIrMdte7WQVm5r1ExNTGnouWOK2rXNo/BaUh7UIrOYmKRLte6Qhlc9Ce/MriI7F4s8NF2kyr1GX0/H2Xz2rPJqrZSgdwf7+NE6MmXVPlN+3YVX9TnW2kV4bZ7aRZxTiwbbHZPHkQAJkAAJkEBGE6DwOiCeVYUXyLAQDTuVoUauLj/WcEZD9VU6mvuuanZr8dqp6KCjxUsOHZFb4q+JXmRWN2cxmbpjvbED24mtxsyWbSTy6yhjFzXk2yaKaM/9c/wTXvf82x2LRL7uJgKh1tvL6rq61h24/pouMq+v63E2nz3sgFbzjWXqaGulBJ1ugMjr2r2nUxRetRXvhjspvDZ58zASIAESIIHgI0DhdTCnwSC87jVytZi6lx2zk5Jg7Tu1tVEaS7e0FF59zdh84dHoC7KuyXPS69B8MYXXur1v4nbBSnjREuW359VdXoVXpzwki/C6byPrSW6tr93+sMj+1SL7VqpNLdR1+LENrS5NZk0r8Ca8un4vbnnovdXk8Z8sC9OsdYpTef6t0WVGeB38smBXEiABEiCBTCVA4XWAPxiE1z2iml7Cq8+DXd1alG0hd4ffrXZ5c292Irx6x7VS8fGy9NBRWddxnPTaNC5JeHMVNNIX0GwIr1qYphfAoU+PRTIv/rQcvXhUOix6VUWRUfpMpUPgT0+7pFlF1iq8SGXQO7xh7I4TRGp38/mp01UYlLw2ulX117m9ne4oLYfPXnaJ8OJ9LQcnw3gAACAASURBVMlKVJe2N6Le1moSNq7CujMahdcGMB5CAiRAAiRwQxKg8DqYFgqvKzxvEV733GDr7m7WUewIL45vOa22HAu5pnYck9YjXYXXOiDSG/6YZIhv7oIiSwarMmY9c181I7yehFfVw0VDxYVzB0W6zhCZlPiaNUKaWoT3j4lJ8p0o0+bYPjx7nhaZWbcdxlB/7DvjUnVBC+/m11tKga87eBZ2G9fgMk7uMBs9eAgJkAAJkAAJ3FgEKLwO5iMYhFdvCtGtajcZVG+QaGlFdYaJmyaKFlM7KQ061cCTzOqorMbtVHhHTWso00MuSvsLF6Vjo6GG8BasKFP/Wu46ozoyC+G9tZHItHtVlLZnyeJJwhubU/oe2Z3UL6U6uROjjCip9f3UhBcpFNbWf7NIobIOnrqkrlbh3X4MVRfi5beXm0n4TbnNg3CMKjumS6W5R6htXIkWXtT7ZSMBEiABEiCBQCRA4XUwa8EgvO5VEZwIr47OepJZfZ60Et5105pLr5B/VUmxvg0GOxPe6wWk74HERW64QOvGFdbn44eXk6LFOg83tYoMOp0BqQwlIpI2xHDw3Omu1sVs+rUUpdSB8EKa0bzV602D2+EQJEACJEACJJBuBCi8DtBmFeF9ud7L0mVhF0H+7Zz2c1Ik5k14o2OjBdK74uAKWfDPAjNy7D6Y3ZQGv4QXC8jG1xQpVEaG1G2vrgOtj7vwprSoS1dkKFRGpP8W49I9bTKhS5Dpm/Mxb9aXR1JHX1MVXh2J9iPC68v18FgSIAESIAESuBEJUHgdzEpWEd6+tftKr6W9UpRUjdCb8OpjUquza1t4Z3eVXpe2qghvZIMBKv2iT/n7pe9P411n1JrSgKhs4m5nEzqOVH18El4cPK6GyPlDSTV27QhvOkqmz8Jbq6vIfyY5eOrZlQRIgARIgAQCjwCF18GcBYPw4vat+bmeUhrsCi9kFv+hPm/HCh09kj1y8Yi0ntNaHbO009Jkxzy/4nn5+dDPgh3dmpdpnvLs/DzS3E5Y5xurXeHmDXbtUzDcEFRdRcGp8K6dYCx803V3M1l4dfUG2xFeP8uiOfgxYVcSIAESIAESyHQCFF4HU0Dh9Q+etwVwduv1il3h1ZfYeqRIg75mhHZC65dl4s6ZSRHe4wdFrkYbR3urU4stgsdFGMdiARoWwaGKgzXv1z2lIR0l07bw+jdV7EUCJEACJEACQUGAwutgGim8/sFzF15EhSsXrqx2bEsz4dWRXX2JurJCYkR2wl29ZeKBxUnCKwWT6uWmtjHDd72TNpHQVRjc+yRGktUJ0lF49fbCqUZ4/Zsq9iIBEiABEiCBoCBA4XUwjcEivJ0WdJJdZ3fJrPtmyeg/R6tyXdayZHZTGuyitAqvLmUG4X0r6i3z/FNaTVHbFqfYUorw/jDSiL5ad1vDIF6Ed0rxFhJ5bKd94bWWIrMjvH5uNmGHp95tjcJrhxaPIQESIAESyKoEKLwOZj5YhNcaVcWisYwUXn1uTEP+HPml8k2V1fntCG/DfV/JxWyhghrC07dPV5IOOVdNS6l7hDcxOjuh7v0y8fR69a6L8NqpqKCrNVil2luEN6W6vg6ePd3VKrz5c2WXLcNapcGoHIIESIAESIAEgosAhdfBfFJ4/YPnaZGc+0ipCu+ORdLzlwGyPncuVT1CS7opvFpK3YU3UYQn1GorE6ON2rsuwmunooLO0b0BhPezVftk+KJt6j7q31pYvnm6oX+Twl4kQAIkQAIkEMQEKLwOJjdYhFdXRhgeNVzm75mfoRHeO2feKRdiL6gav0ir0C1V4d3/m/Rc0ksJb8m8JeXYpWOC6zerQ7gvHNNR1kThnVf3ARl6eq1/wouFa6Msu6V5igpbc3gHHRDJVcjBk5ZyV73bGoU3XfByUBIgARIggSAhQOF1MJHBIrzW2rdYQKZTClB7V0VAW02xVYfXLkprCoU+h84Zti28MecM4T2ftCWwiySnJLyJkd91lZpKr7h9ScKbkMPYRc1OhBe9rELrqY8uV6aOPW8Xjc/HUXh9RsYOJEACJEACWZAAhdfBpFN4/YPnSXgRnR26eqg5IBbQVSlcxesJrPm/WszNhW4pCW/i6+vK1VVbE6t+WLSWs5gIFqDZFV69AQUGyEThPXT2ijQevULdB1Ma/Hse2YsESIAESCD4CVB4E+c4ISFBPvroI5k6daps2LDB1sxTeG1hSnaQJ+HVUWR98JbuiVv3ejmFTsXQh9iK8HoS3vAOEhmS1zfhtUZwvQmvXYH2D6XqpXdbo/A6gMiuJEACJEACQU2AwisicXFxMmDAAClWrJgsXLhQ1q1bZ2vSs4rwYtez/j/3l7vD75b3m71vi423gzwJ7+quqyVqZpTZzY7w6lQMj8KLF61pBzqHNzH/dl2uXNKrZDHVdUqtARJ59oRvwqtr8WIAT9v1aiGm8Dp+XjgACZAACZAACTglQOFNJLhy5Upp1KiR1KlTRzZu3GiLa7AIL/J2kUsLocUCMvccXpete3XZL1uEPB+khVeLdL6wfLLm4TXmFsfolebCi13RCiUuNBtWUKzCO6vOK1Ll5H5DeO1uEmEte+apjxZevQWxA16pdW3z3krZfuwCUxpSA8X3SYAESIAEsiwBCq9l6uPj4yUyMjLLCi/Kex29dFSOXjwqSzotkdZzWis66SW81s0tpraeau6yli7Ca1045ia8W5pOECnX2LdfAmsniCwZbPTxJLzWzSnuTjzOtzPYPlpvL8yUBtvIeCAJkAAJkEAWI5BlhBe5uXPnzk02vdOnT5cCBQqo170JL45zb8OGDZPdu5OqBATqs6MjvLqerRZOXS83rYVX766mN4zAeSG8+vV0F96pbWXdiQ1mSoNfwmtdFOdJePH+mgkiVe8Vqd0tXR8NLbz9mleUAfdUStdzcXASIAESIAESCEQCWUZ47UyON+GFMLu3ESNGUHjtgHU7RufeasHWwmvNybWT0jBvzzyXyg7J+owMN7YZRrNGeL/rLUf+/lZah9+i3vJLeI9vFpmUGBW2mwbhBys7XfRuaxReO7R4DAmQAAmQQFYkQOG1zDpTGowdy3SEtdOCTmozCOT2/nzoZ9etex38tKQkvMsPLleL4/T5UzuFjkzr45IJb0q1cP+aLjKvr0TcWsZ/4VUSXdA4dTpuHZwaA7wP4V227bj0anSbdKlT2k4XHkMCJEACJEACWYoAhZfCKymlNOjFZR637nXwY5KS8Orr0IvYUjuF38J77oDI+JpJwttqukiJmqmdLvn7OoKcycLr+4WzBwmQAAmQAAlkLQIUXgpvpgmvRo8c4b5+VH/wW3hVWLSGTAgx0h369j/o30/9Dy+LHN8i0maUf8Ls31nZiwRIgARIgARIwEcCFF4fgVkPD7ayZO6L1tI7wpupwmuto5uOW/86eLzYlQRIgARIgARIII0IUHgdgAwW4d1xZod0WdhFKheuLDvP7FREkA97owtvdGy0980qEIH9Y5Ixw+5Sm5jH6/E9B88Eu5IACZAACZAACdx4BCi8DuYkWIQXCHQJMo0jPYXXPRXB35QG9+tOtmjNujmEu/Baqywwwuvgp4BdSYAESIAESODGJ0DhdTBHwS687lv3OhFTK+b0EN6SeUvKss7LXGdTC2/xGiJ9VjuYaXYlARIgARIgARIIZAIUXgezR+H1D5678GKL4eZlmvs1mI5M61q+LoNo4S0bJdJzsV/jsxMJkAAJkAAJkEDgE6DwOpjDrCa8w6OGS8cKHR0QM7q6C++UVlMkskSkX+NSeP3Cxk4kQAIkQAIkkKUIUHgdTHdWE14nYmrFnJbCqzfH8Bjh1dv/MsLr4ClnVxIgARIgARIIfAIUXgdzSOH1D15aCq+1ksTU1m7bP1N4/Zsg9iIBEiABEiCBICNA4XUwocEuvF9u+1LGrBtjEkqrCK8ug6YHdjKuV+HFjmobZ4hUbceNIRw85+xKAiRAAiRAAoFOgMLrYAaDXXjTMhLrjtlaBm3WfbOkSuEqfs2EV+H1a0R2IgESIAESIAESCDYCFF4HMxpMwqtzYTUO1LTNKOFNVj/XhznRwnt3+N3yfrP3fejJQ0mABEiABEiABLIKAQqvg5kOJuHV4hhowqtrBadVjWAHjwO7kgAJkAAJkAAJ3KAEKLwOJobC6z88a0qDkwgvhdf/OWBPEiABEiABEsgqBCi8DmY6WIU3X1g+WfPwmoBIadDCOzByoDxa7VEHs8muJEACJEACJEACwUqAwutgZoNVeHVN2yMXj0jrOa1NQk6qKbhjTqsIr4PpY1cSIAESIAESIIEsQoDC62Cig114gcYqpmkpvF43jHAwJ+xKAiRAAiRAAiRAAu4EKLwOngkKr//wWE7Mf3bsSQIkQAIkQAIk4BsBCq9vvFyOpvD6D4/C6z879iQBEiABEiABEvCNAIXXN15ZWnhXd10tBXIUcEAsqSuFN00wchASIAESIAESIAEbBCi8NiCldEgwRXh1tQPcq160hr+n1+IyCq+DB49dSYAESIAESIAEfCJA4fUJl+vBWUF4rTuwOamX645ZC2+3qt1kUL1BDmaBXUmABEiABEiABEjAOwEKr4MnJCsIr3UHtrQU3udXPC8/H/pZuEOagweQXUmABEiABEiABGwRoPDawuT5IAqv//C4Q5r/7NiTBEiABEiABEjANwIUXt94uRxN4fUf3rw982T+nvnSoUIH6Viho/8DsScJkAAJkAAJkAAJpEKAwuvgEaHwOoDHriRAAiRAAiRAAiSQQQQovA5AZwXh1bm2wJSWObwOsLMrCZAACZAACZAACfhEgMLrEy7Xg7OC8FrLlVF4HTws7EoCJEACJEACJJBpBCi8DtAHk/Aip3bo6qGKhrUOL4XXwQPCriRAAiRAAiRAAjcEAQqvg2kIJuFdd3yd9Frai8Lr4HlgVxIgARIgARIggRuTAIXXwbxQeB3AY1cSIAESIAESIAESyCACFF4HoLOS8OYLyydrHl7jgBa7kgAJkAAJkAAJkEDmEKDwOuCeFYRX5/Za83odIGNXEiABEiABEiABEshwAhReB8izgvDq3F4Kr4MHhV1JgARIgARIgAQylQCF1wH+YBXePrX6SN/afRUZCq+DB4RdSYAESIAESIAEbggCFF4H00DhdQCPXUmABEiABEiABEgggwhQeB2AzgrCGx0bLTvP7JT8OfJLlcJVHNBiVxIgARIgARIgARLIHAIUXhE5deqUjB49Wn777TcJCwuTJk2ayLBhw9TfvbVgEl6IbdTMKHW71pSGzHkseVYSIAESIAESIAESSDsCFF4R2bhxo+zbt0/at28v169fl969e0vz5s2lW7duWUZ4caMRn0dQeNPuZ4sjkQAJkAAJkAAJ3CAEKLweJmLq1Kly+PBhGTrU2Go3pRZMEV4K7w3yE8nLIAESIAESIAESSHMCFF4PSJ9//nkV4e3QoYP5bkxMTLIjIyIiZPfu3Wk+KZk1ICO8mUWe5yUBEiABEiABEkhPAllGeBG1nTt3bjKW06dPlwIFCpivr1q1SsaNGyfffPONZM+e3Xz9vvvuS9Z3x44dFN70fDo5NgmQAAmQAAmQAAmkAYEsI7x2WG3evFkGDhwokOOSJUum2oUpDaki4gEkQAIkQAIkQAIkkOkEKLyJU4Bo7YABA+TDDz+U8uXL25oYCq8tTDyIBEiABEiABEiABDKVAIVXRP755x9B3u57770nFSpUsD0hFF7bqHggCZAACZAACZAACWQaAQqviIrsLlq0SEJDQ82JyJkzpyDFwVsLNuFtOKOhXIy7yDq8mfbjyBOTAAmQAAmQAAmkBwEKrwOqwSa8PZf0lPUn1lN4HTwT7EoCJEACJEACJHDjEaDwOpgTCq8DeOxKAiRAAiRAAiRAAhlEgMLrADSF1wE8diUBEiABEiABEiCBDCJA4XUAmsLrAB67kgAJkAAJkAAJkEAGEaDwOgBN4XUAj11JgARIgARIgARIIIMIUHgdgKbwOoDHriRAAiRAAiRAAiSQQQQovA5AU3gdwGNXEiABEiABEiABEsggAhReB6CDVXjH3z1empdp7oAMu5IACZAACZAACZDAjUOAwutgLoJNeB2gYFcSIAESIAESIAESuGEJUHgdTA2F1wE8diUBEiABEiABEiCBDCJA4XUAmsLrAB67kgAJkAAJkAAJkEAGEaDwOgBN4XUAj11JgARIgARIgARIIIMIUHgdgKbwOoDHriRAAiRAAiRAAiSQQQQovA5AU3gdwGNXEiABEiABEiABEsggAhReB6ApvA7gsSsJkAAJkAAJkAAJZBABCq8D0BReB/DYlQRIgARIgARIgAQyiACF1wFoCq8DeOxKAiRAAiRAAiRAAhlEgMLrADSF1wE8diUBEiABEiABEiCBDCJA4XUAmsLrAB67kgAJkAAJkAAJkEAGEaDwOgBN4XUAj11JgARIgARIgARIIIMIUHgdgKbwOoDHriRAAiRAAiRAAiSQQQQovA5AU3gdwGNXEiABEiABEiABEsggAhReB6ApvA7gsSsJkAAJkAAJkAAJZBABCq8D0BReB/DYlQRIgARIgARIgAQyiACF1wFoCC8bCZAACfhCoEGDBrJ27VpfuvBYEiABEpDdu3eTggMCFF4H8L788ktJSEiQxx57zMEo7JoagV27dsn48eNlwoQJqR3K9x0SeOCBB2TSpElSuHBhhyOxuzcC7777rlSpUkXatm1LUOlI4Pfff5elS5fKG2+8kY5n4dAgcM8998iPP/5IGCRwwxKg8DqYGgqvA3g+dKXw+gDL4aEUXocAbXan8NoE5fAwCq9DgD50p/D6AIuHZgoBCq8D7BReB/B86Erh9QGWw0MpvA4B2uxO4bUJyuFhFF6HAH3oTuH1ARYPzRQCFF4H2Cm8DuD50JXC6wMsh4dSeB0CtNmdwmsTlMPDKLwOAfrQncLrAywemikEKLwOsFN4HcDzoSuF1wdYDg+l8DoEaLM7hdcmKIeHUXgdAvShO4XXB1g8NFMIUHgzBTtPSgIkQAIkQAIkQAIkkFEEKLwZRZrnIQESIAESIAESIAESyBQCFN5Mwc6TkgAJkAAJkAAJkAAJZBQBCm9GkeZ5SIAESIAESIAESIAEMoUAhTdTsPOkJEACJEACJEACJEACGUWAwusH6evXr8vbb78tixYtkrCwMOnTp49069bNj5HYxZ3A+vXr5ZFHHpEcOXKYb61evVry588vZ86ckf/+97+yefNmtRPYiBEjpE6dOoToA4H9+/fL008/LQ899JD07NnT7OmNLXgPGjRITp48qXYHe+edd6RYsWI+nDXrHXrp0iV58cUX1Y1j5zrd+Hyn3bMQFxcnEydOlNmzZ8u1a9ekUqVK6ndCyZIl1UnmzJmjdmiMjY1Vu4Bht7Vs2bKl+l7aXWHwjIT/12Gny7Nnz0qRIkXktddek3r16qkbxE6jGzdulJCQEPVv/P4eOHCg+jt/dwTPMxAMd0Lh9WMWZ82aJQsXLpTJkyfL5cuXlTygzFCNGjX8GI1drASwDeiaNWtk2LBhycC89NJLcsstt0i/fv3UL1L8ieNz5cpFiDYIrF27Vv1Pv2LFinL77be7CG9KbPGBDrKA+WjSpIl8/vnnglJPH3/8sY0zZs1Djh07Jr1791aMjx8/7iK8fL7T7pk4d+6czJgxQwlXvnz55IMPPpDdu3fL+++/L/v27VOvf/311+rDGT581K5dW3r16uX1vbS7uuAa6aOPPpKOHTuq379//vmnPP/88+r3NCS3Xbt2ghKd7tuR40MIf3cE13MQ6HdD4fVjBh9//HHp0aOHNG7cWPWeNm2a4H9ygwcP9mM0drESwP/AEG189tlnXcAgql63bl1BtDd37tzqPUTWu3TpIs2aNSNEGwQgA4iUQwIKFixoCq83tojmvPXWW4IPeWg4tmHDhvLTTz+psdiSE7h48aLs3LlTRRbxAcEa4eXznX5PzLZt21RkEdFIBCOio6MFH+TQtm/frn4/z5s3z+t76Xd1wTUyPsz98ssv6vcI/j+4cuVKM8Kr73TTpk383RFc0x7wd0Ph9WMKmzdvLl988YX6tIuGH3b8+9NPP/VjNHaxEgDDqVOnSs6cOZXYdu3aVX1FhkgZIun4Javb//73PylUqJA8+eSThOgDAXwbcdNNN5nC640tomOI6I4ePdo8Q+fOndVXmjVr1vThrFnvUHw4Q+TLKrx8vtPvOZg+fbr8/fffKq3hlVdeUR+Q77//fnXCq1evqn9v2bLF63vpd3XBM/KePXtUWtTy5cvVTUF+S5Qoob7trF69uvpgER4eLvPnz+fvjuCZ9qC4EwqvH9MYFRUlCxYsULlMaPiKB7liiN6wOSOAr8HwP6c8efLIgQMHVBQXqQuVK1dWXxMvWbLEPAG+wkTEEe+z2SfgLrzI602JLf5HhsgZUiF0wwcQROAbNGhg/6RZ8EhPwsvnO30eBHxoe/TRR9W3bQhEvPDCC9KiRQtp27ateUKk8mDXRqQ3pPSezkNNn6sM/FHj4+PVt5vdu3dX6Qpo+EYjb968gvfwAW/u3Lkqyv7NN9/wd0fgT3lQ3QGF14/pxC/Lzz77TMqWLat645MuZBevsaUtAXz9rvN1O3XqJKtWrTJPgEhO0aJF5amnnkrbkwb5aO7Ce+LECUmJLYT3119/VQvVdOvQoYO8+eabUqtWrSAn5ez2PAmv+4h8vp0xRm8spIKAYUGrTjMbMmSIej6xVbaWMnxA27p1q3h7z/nVBO8ICC4gRQT/3/MWZLjzzjuV9CIQxN8dwfs8BOKdUXj9mDV8nfPggw+auaOffPKJQBpeffVVP0ZjF28E8DXl3r17FdvIyEhZsWKFFChQQHV54okn1DzoSANJ2iPgLrwJCQkpsi1VqpQSBOQ+oiGKg9XZmAekk7ClTMCO8PL5dvYEXbhwQaXmYF1FmzZtzMGmTJmififrdRX40IznGIuNvb3n7GqCtzd+R4AfIrn401urX7++LFu2TA4fPszfHcH7SATknVF4/Zg25Cah5I2u0oAowsiRI5U0sDkjgHxR5IZi1fWRI0fUqurhw4cryUJeHiK6/fv3V1FffA2PxVM4ls0+AXfhRc+U2CK1pHXr1jJ06FAVPcMiLDDHV5ds3gl4El4+32n31KD0Gz70IpXBmrqAM0C2Hn74YZk5c6ZZpQFly5CK4+29tLu64BoJv4MhvcjdtzZ8qPj3338lIiJCvY8cdUR1v/rqK5Vuxt8dwfUcBPrdUHj9nMExY8Yo6UXOF6ILXDjlJ0i3bih3hQWAaIjkIpqOcjhoWHWNVdgbNmxQ76FUlv4KM23OnjVG8SS83tju2LFDcT969KiUL19exo4dqxalsPkuvHy+0+6pQToIPoiFhoa6DIrcUZQgQx4pFlvGxMRI06ZN1WI2Xd/b23tpd4XBMRJKvLVs2TIZZ+RCoyQZ0hsOHTqkFhpjARsiwLpON393BMczECx3QeENlpnkfZAACZAACZAACZAACXgkQOHlg0ECJEACJEACJEACJBDUBCi8QT29vDkSIAESIAESIAESIAEKL58BEiABEiABEiABEiCBoCZA4Q3q6eXNkQAJkAAJkAAJkAAJUHj5DJAACZAACZAACZAACQQ1AQpvUE8vb44ESIAESIAESIAESIDCy2eABEiABEiABEiABEggqAlQeIN6enlzJEACJEACJEACJEACFF4+AyRAAiRAAiRAAiRAAkFNgMIb1NPLmyMBEiABEiABEiABEqDw8hkgARIgARIgARIgARIIagIU3qCeXt4cCZAACZAACZAACZAAhZfPAAmQAAmQAAmQAAmQQFAToPAG9fTy5kiABEiABEiABEiABCi8fAZIgARIgARIgARIgASCmgCFN6inlzdHAiRAAiRAAiRAAiRA4eUzQAIkQAIkQAIkQAIkENQEKLxBPb28ORIIDgKbN2+WIUOGyIEDB+S+++6Tt99+Ozhu7Aa6i5EjR8rly5dl+PDhN9BV8VJIgARIIG0IUHjThiNHIYGgI9C0aVMJDw+Xr776yuXe/vnnH+ncubNs3Lgxw+4Z52vRooX06tVLSVmhQoUcnfuDDz6QS5cuyaBBg9Q4+BNjV6pUKU3HdTRYBndOa+H97rvv5OLFi/Loo4+ad/LYY49J9+7dpXnz5hl8dzwdCZBAVidA4c3qTwDvnwRSIADhvXDhggwdOlT+85//mEdlhvDWrl1bZs6cKVWrVk2T+frzzz/l6tWr0rhxY4mNjVUC9tlnnzkWXuu4aXKhGThIWgtvv379pG7dui7CO3v2bKlXr56UKVMmA++MpyIBEiABEQovnwISIAGPBCC8Tz31lLz//vuydOlSM6rqSXhnzZolkyZNkmPHjqmoMGSnbdu2tshCOMeOHSsLFixQgl2zZk157bXXlNzu3r1bBg8eLJs2bZL8+fNLtmzZ5Mcff0wW4cUYY8aMkYULF6qoYvny5eXLL7+UDRs2yJw5c6RLly7y5ptvqqjuH3/8IVruXn/9dbn//vtl+/bt5vhIl2jZsqUcP35c8P7q1aulSJEi8tBDD0nv3r0lJCREVqxY4XVcnRaAMfD3VatWSWhoqNx1111qTB2hxnXkypVLjhw5Iv/3f/8n8fHx0qBBA3WteN1Twz3h/T179kjZsmXlxRdfVMK+ZMkSGTFihPz666/qGnXDOV9++WVp06aNvPvuu/LDDz+oeSpVqpR6XUdbrcJ7+PBhufvuuxWX7Nmzm2NVrFhRfvrpJ3XeM2fOqPOtXbtWoqOjpVq1aurft912m7z66quKT1hYmOTMmVMxxjx27NhRnnjiCbn33nvVmLhnnHfbtm1SsGBBeeCBB+T5559XrNBwPKLCc+fOFVwT7qtbt25qDDTwGjVqlHz//ffqGiDSL7zwgtxzzz22nj0eRAIkkHUIUHizzlzzTknAJwIQ3k8//VQmT56spAdi1fIuRgAACeZJREFUguYuvBCsgQMHyrhx46RWrVqybt06JWGImCIym1qDqEJC8efNN9+sRAnyvHz5csmXL5/qXr16dcFX5CmlHEB6fv/9d3nrrbeUyO3atUvuvPNOJaYQzqJFi6oc4OLFi0vJkiVN4dVi6ml8SHKTJk2kZ8+e8u+//0qfPn3U3yG+dsdFKgauGRJ27do1JWfnz5+XKVOmqPsC06lTp8rEiROVeF65ckUJHoQNHzbcGyQT4gqxxP1BGJ955hnBBw5IaP369RX3O+64Q3X966+/pEePHkpKIdD44IIPEmCwaNEiJc6YLz2/OofXjvDGxcXJ4sWLVZQ8T548iv2JEyfkk08+UedGigik2ZrSYBXe06dPqzQVPDvIy4b047nB359++mlTeE+dOqU+vNx6661KevH+tGnT1LOGqD9k+KOPPlLPCsQZzxBYsJEACZCAlQCFl88DCZCARwIQXohE6dKllWQh0hsZGZlMeCE0kB6roL333nuyc+dOmTBhgle6iMzefvvtMmPGDCUwuj388MPSqlUrle+ZmvDqMZBrjLGsDWIKeUJUuFy5cuZb7l/fuwsvoqgQMUi3bhgf0dHp06cr4U1tXIgkIsIQcUQ50RB9joqKkm+++UaqVKmihBcL8iBuuuEDxtatWxVv9waekD4Ir27PPfecIPKKyCiiqJBPpKGg4TgI9ujRo5ONlZCQoD5ILFu2TM2xrxFe9wHBDGKPD0BoqQnvhx9+qPLAIei6Qcwh8BgLDYKMCHX//v3NYx5//HFp1qyZivRiLubNmydffPGF5M6dmz/JJEACJJAiAQovHw4SIAGPBCC8kJKIiAj1dTkkFmkHBw8edFm0hkgjorONGjUyx4EoIpoJ0fTW9u3bp9IH/v77b8mRI4d5KEQN0UZEDdG8RXhTGgP9IKZIIfjtt99cLiM14YWQQhrxlbxuEEREj/GVvp1xv/76axV9/Pbbb13O3aFDB/WVPCKVuI5z5865CCmimT///LMZBbZ2hlAiqorUDt2uX7+ucqzBbM2aNSpKihQKfP2PCDXmAZKNiCwiy7h+RJLx/o4dO9TcIgXEV+FFNPfjjz9W0oqxY2JilNBDWu0I74ABA5Ro43p1Q398aEEaSbFixcyUBqRE6Pbss8+qZxIfOJCH/d///leQO/3ggw/KI488oiK8bCRAAiTgToDCy2eCBEggVeHFARANiCcir506dTKrNGBh0vjx412EF1KFqGJqwosoMPI53YUXebSQMjvCixSL1q1bJxtDCy+ED1FMa0tNeBFxxgIrCKunBuFNbVxEHZE24C687du3lyeffNIUXvdSYN6EF7nROvfW03VBfiG5yNVFmgKipZBfCDKEGNFkzFWJEiUEAl+5cmUVtbYjvJDLGjVqmDm8EHekTrz00kuSN29eJZ2IMtsVXlwb8n1TE15rzq9+DrXwagZ4jpAagpQNfEiD4LORAAmQgJUAhZfPAwmQgC3hRS4lvmJGNBeyosuSIaqGlAadd4nBEA3Ggifk4npriAoiTQKSZ833RUoD8liRM4vmLcILEdNVHNxzhu2IKcaHQEFMdRUIyBtEC5FhLKZyb3bGxRjI+/WU0oAUBizy8lQZwZvwopzaypUrVc5uSg1jYjGXjgK/8sor6lCINlJE8GEFbf/+/Yqxpwjv2bNnVTUFzLHOo8YCQixExIeZwoULK9lFJBpRWjRExZHHrYUX/BD1Rw6xbtYcXtwLxtf5zDgGfcEMucmIQLsvcktJePX4SI+A4EN+2UiABEiAwstngARIIFUC1pQGfTAWjn3++edqAwgtvEhfgFTpRWvr169XuZyQXcgsckix0AvR2jp16iQ7LwQNfSDS+BobkVXkqmLcAgUKpCq8OGDYsGGqkgOirohe4qt6VHvAV/ypRWLRHznKEELkIUMWkXOLigGQXdToheAhkgxBh8TZEV5EW7FoDbm6etEaot744IDoL5qvwotFa1jchrxpfChANQNEbbGgC1FaNCzcQjQewogPHojKokEksXAN5zx58qRiBsFEmop7hBfHI1KMPl27dlWpA4jkQo4hvKiGgLlFRBdziwg9ngGIshZejI+FaIi4ggVybK0CiwoWEGiMC/Z60RrmAh+o0FITXnyowFyBMXK5sQgRaSjcmCTVH28eQAJZjgAjvFluynnDJGCPgCfhRU8sRoLsWjeemD9/vpLUQ4cOqYgfhAsSg4ZcT+SYQohRRcC9QTAhZhBdlJZCtBVlrbSo4fjUqjQg/QFii/xWpAhgERcWmUGI7AgvIrk4JyoHQErbtWunpBDihEVYkCmUW8PiKaRP2BFeXDcE9Y033lBRWS2RyCmGQPsjvOgDscc14k+kLSAtAekKFSpUMNFCGsHVmlKCXGcsxIMQ40MBBBUfSsDHk/Bi0R0EEh9YIJVIw8AiRnzgQRUEMNCVGRCtxn3iGOTfokFgIcT48IH8WpSacxfYLVu2KMb4Ex9uEH1Gbq+OTqcmvLgGsMBCPizWQyoDRNvpxiT2fkJ4FAmQQCARoPAG0mzxWkmABEiABEiABEiABHwmQOH1GRk7kAAJkAAJkAAJkAAJBBIBCm8gzRavlQRIgARIgARIgARIwGcCFF6fkbEDCZAACZAACZAACZBAIBGg8AbSbPFaSYAESIAESIAESIAEfCZA4fUZGTuQAAmQAAmQAAmQAAkEEgEKbyDNFq+VBEiABEiABEiABEjAZwIUXp+RsQMJkAAJkAAJkAAJkEAgEaDwBtJs8VpJgARIgARIgARIgAR8JkDh9RkZO5AACZAACZAACZAACQQSAQpvIM0Wr5UESIAESIAESIAESMBnAhRen5GxAwmQAAmQAAmQAAmQQCARoPAG0mzxWkmABEiABEiABEiABHwmQOH1GRk7kAAJkAAJkAAJkAAJBBIBCm8gzRavlQRIgARIgARIgARIwGcCFF6fkbEDCZAACZAACZAACZBAIBGg8AbSbPFaSYAESIAESIAESIAEfCZA4fUZGTuQAAmQAAmQAAmQAAkEEgEKbyDNFq+VBEiABEiABEiABEjAZwIUXp+RsQMJkAAJkAAJkAAJkEAgEaDwBtJs8VpJgARIgARIgARIgAR8JkDh9RkZO5AACZAACZAACZAACQQSAQpvIM0Wr5UESIAESIAESIAESMBnAhRen5GxAwmQAAmQAAmQAAmQQCARoPAG0mzxWkmABEiABEiABEiABHwmQOH1GRk7kAAJkAAJkAAJkAAJBBIBCm8gzRavlQRIgARIgARIgARIwGcCFF6fkbEDCZAACZAACZAACZBAIBGg8AbSbPFaSYAESIAESIAESIAEfCZA4fUZGTuQAAmQAAmQAAmQAAkEEgEKbyDNFq+VBEiABEiABEiABEjAZwL/D5ZinD62GgUGAAAAAElFTkSuQmCC" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.params_plot(\n", - " res,\n", - " max_evaluations=300,\n", - " # optionally select a subset of parameters to plot\n", - " selector=lambda params: params[\"c\"],\n", - ")\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## There are many optimizers\n", - "\n", - "If you install some optional dependencies, you can choose from a large (and growing) set of optimization algorithms -- all with the same interface!\n", - "\n", - "For example, we wrap optimizers from `scipy.optimize`, `nlopt`, `cyipopt`, `pygmo`, `fides`, `tao` and others. \n", - "\n", - "We also have some optimizers that are not part of other packages. Examples are a `parallel Nelder-Mead` algorithm, The `BHHH` algorithm and a `parallel Pounders` algorithm.\n", - "\n", - "See the full list [here](../how_to_guides/optimization/how_to_specify_algorithm_and_algo_options" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## You can add bounds" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([0., 0., 0., 1., 2.])" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " lower_bounds=np.arange(5) - 2,\n", - " upper_bounds=np.array([10, 10, 10, np.inf, np.inf]),\n", - ")\n", - "\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## You can fix parameters " - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([0., 1., 0., 3., 0.])" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " constraints=[{\"loc\": [1, 3], \"type\": \"fixed\"}],\n", - ")\n", - "\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Or impose other constraints\n", - "\n", - "As an example, let's impose the constraint that the first three parameters are valid probabilities, i.e. they are between zero and one and sum to one:" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0.33334, 0.33333, 0.33333, -0. , 0. ])" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.array([0.1, 0.5, 0.4, 4, 5]),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " constraints=[{\"loc\": [0, 1, 2], \"type\": \"probability\"}],\n", - ")\n", - "\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "For a full overview of the constraints we support and the corresponding syntaxes, check out [the documentation](../how_to_guides/optimization/how_to_specify_constraints.md).\n", - "\n", - "Note that `\"scipy_lbfgsb\"` is not a constrained optimizer. If you want to know how we achieve this, check out [the explanations](../explanations/optimization/implementation_of_constraints.md)." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## There is also maximize\n", - "\n", - "If you ever forgot to switch back the sign of your criterion function after doing a maximization with `scipy.optimize.minimize`, there is good news:" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [], - "source": [ - "def upside_down_sphere(params):\n", - " return -params @ params" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0., -0., -0., 0., -0.])" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.maximize(\n", - " criterion=upside_down_sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_bfgs\",\n", - ")\n", - "\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "estimagic got your back." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## You can provide closed form derivatives" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere_gradient(params):\n", - " return 2 * params" - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0., -0., -0., -0., -0.])" - ] - }, - "execution_count": 15, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " derivative=sphere_gradient,\n", - ")\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Or use parallelized numerical derivatives" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0., -0., -0., -0., -0.])" - ] - }, - "execution_count": 16, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " numdiff_options={\"n_cores\": 6},\n", - ")\n", - "\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Turn local optimizers global with multistart" - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0., 0., -0., -0., 0., -0., 0., -0., -0., -0.])" - ] - }, - "execution_count": 17, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(10),\n", - " algorithm=\"scipy_neldermead\",\n", - " soft_lower_bounds=np.full(10, -5),\n", - " soft_upper_bounds=np.full(10, 15),\n", - " multistart=True,\n", - " multistart_options={\"convergence.max_discoveries\": 5},\n", - ")\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## And plot the criterion history of all local optimizations" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAArwAAAH0CAYAAADfWf7fAAAgAElEQVR4XuzdCXhU1f3/8W9WIGGHIAEBJcq+G9lkESX9C1pBtNhSii2ubalaQSvuuLX4c6HaaqVqq6hQFcsmIigIoqBgkX0JiOxL2IUQkpD8n+/BO06GLDNzZiaTm/d9Hh+E3HPuOa9zCZ85OffcmMLCwkLhQAABBBBAAAEEEEDApQIxBF6XjizdQgABBBBAAAEEEDACBF5uBAQQQAABBBBAAAFXCxB4XT28dA4BBBBAAAEEEECAwMs9gAACCCCAAAIIIOBqAQKvq4eXziGAAAIIIIAAAggQeLkHEEAAAQQQQAABBFwtQOB19fDSOQQQQAABBBBAAAECL/cAAggggAACCCCAgKsFCLyuHl46hwACCCCAAAIIIEDg5R5AAAEEEEAAAQQQcLUAgdfVw0vnEEAAAQQQQAABBAi83AMIIIAAAggggAACrhYg8Lp6eOkcAggggAACCCCAAIGXewABBBBAAAEEEEDA1QIEXlcPL51DAAEEEEAAAQQQIPByDyCAAAIIIIAAAgi4WoDA6+rhpXMIIIAAAggggAACBF7uAQQQQAABBBBAAAFXCxB4XT28dA4BBBBAAAEEEECAwMs9gAACCCCAAAIIIOBqAQKvq4eXziGAAAIIIIAAAggQeLkHEEAAAQQQQAABBFwtQOB19fDSOQQQQAABBBBAAAECL/cAAggggAACCCCAgKsFCLyuHl46hwACCCCAAAIIIEDg5R5AAAEEEEAAAQQQcLUAgdfVw0vnEEAAAQQQQAABBAi83AMIIIAAAggggAACrhYg8Lp6eOkcAggggAACCCCAAIGXewABBBBAAAEEEEDA1QIEXlcPL51DAAEEEEAAAQQQIPByDyCAAAIIIIAAAgi4WoDA6+rhpXMIIIAAAggggAACBF7uAQQQQAABBBBAAAFXCxB4XT28dA4BBBBAAAEEEECAwMs9gAACCCCAAAIIIOBqAQKvq4eXziGAAAIIIIAAAggQeLkHEEAAAQQQQAABBFwtQOB19fDSOQQQQAABBBBAAAECL/cAAggggAACCCCAgKsFCLyuHl46hwACCCCAAAIIIEDg5R5AAAEEEEAAAQQQcLUAgdfVw0vnEEAAAQQQQAABBAi83AMIIIAAAggggAACrhYg8Lp6eOkcAggggAACCCCAAIGXewABBBBAAAEEEEDA1QIEXlcPL51DAAEEEEAAAQQQIPByDyCAAAIIIIAAAgi4WoDA6+rhpXMIIIAAAggggAACBF7uAQQQQAABBBBAAAFXCxB4XT28dA4BBBBAAAEEEECAwMs9gAACCCCAAAIIIOBqAQKvq4eXziGAAAIIIIAAAggQeLkHEEAAAQQQQAABBFwtQOB19fDSOQQQQAABBBBAAAECL/cAAggggAACCCCAgKsFCLyuHl46hwACCCCAAAIIIEDg5R5AAAEEEEAAAQQQcLUAgdfVw0vnEEAAAQQQQAABBAi83AMIIIAAAggggAACrhYg8Lp6eOkcAggggAACCCCAAIGXewABBBBAAAEEEEDA1QIEXlcPL51DAAEEEEAAAQQQIPByDyCAAAIIIIAAAgi4WoDA6+rhpXMIIIAAAggggAACBF7uAQQQQAABBBBAAAFXCxB4XT28dA4BBBBAAAEEEECAwMs9gAACCCCAAAIIIOBqAQKvq4eXziGAAAIIIIAAAggQeLkHEEAAAQQQQAABBFwtQOB19fDSOQQQQAABBBBAAAECL/cAAggggAACCCCAgKsFCLyuHl46hwACCCCAAAIIIEDg5R5AAAEEEEAAAQQQcLUAgdfVw0vnEEAAAQQQQAABBAi83AMIIIAAAggggAACrhYg8Lp6eOkcAggggAACCCCAAIGXewABBBBAAAEEEEDA1QIEXlcPL51DAAEEEEAAAQQQIPByDyCAAAIIIIAAAgi4WoDA6+rhpXMIIIAAAggggAACBF7uAQQQQAABBBBAAAFXCxB4XT28dA4BBBBAAAEEEECAwMs9gAACCCCAAAIIIOBqAQKvq4eXziGAAAIIIIAAAggQeLkHEEAAAQQQQAABBFwtQOB19fDSOQQQQAABBBBAAAECL/cAAggggAACCCCAgKsFCLyuHl46hwACCCCAAAIIIEDg5R5AAAEEEEAAAQQQcLUAgdfVw0vnEEAAAQQQQAABBAi83AMIIIAAAggggAACrhYg8Lp6eOkcAggggAACCCCAAIGXewABBBBAAAEEEEDA1QIEXlcPL51DAAEEEEAAAQQQIPByDyCAAAIIIIAAAgi4WoDA6+rhpXMIIIAAAggggAACBF7uAQQQQAABBBBAAAFXCxB4XT28dA4BBBBAAAEEEECAwGtxD1x44YWSmZlpUQNFEUAAAQQQQAABBMIt4KrAm5eXJy+99JK89957cvr0aWnRooU8+eSTkpqaahxXrVol9957r2RlZUmrVq3kmWeekQYNGpivTZ06VSZMmCC5ubmSkZEh48aNk7i4uFL9Cbzhvj2pHwEEEEAAAQQQsBdwVeA9cuSIvP322zJixAipXr26vPDCC2YG9vnnnzcBWIPsI488In369JHXX39dvvjiC3n55Zdl69atpsyUKVNMAB49erR06tRJRo4cSeC1v8eoAQEEEEAAAQQQKFcBVwVeX8l169bJPffcI7NmzZKVK1fK448/Lu+++645raCgQHr06CEff/yxTJ48WY4dOyZjxowxX1u/fr2MHTtWpk2bRuAt19uTiyOAAAIIIIAAAvYCrg68b731lqxdu9Ysa5g+fbqZ0R0/frxH7brrrpOHHnrIzOymp6fLkCFDzNdOnTplfr969WoCr/09Rg0IIIAAAggggEC5Crg28O7du1d+9atfyb///W9p3Lix/Oc//xGd8dW1uc4xfPhwGTVqlLzzzjvSv39/GThwoOdruj5306ZNEhMTY/5szZo1Zw3UNddcw0Nr5Xr7cnEEEEAAAQQQQKBsAVcG3sOHD8sNN9wgd999t/Tu3dsozJgxQxYuXGgeVHOOQYMGyaOPPmoCb8eOHWXo0KHmS8ePH5fu3bsXCbl33nnnWZoffPABgbfse4wzEEAAAQQQQACBchVwXeD9/vvv5Te/+Y3ceOONMmDAAA+uLm24//77Pety8/PzpWvXrjJ//nx5//33Zd++fWbdrh66m4OeO3PmzFIHh10ayvXe5eIIIIAAAggggIBfAq4KvCdOnJCbbrrJLGXwXp6gEvqQ2hVXXCEPPvigmfXVXRr0gbVJkybJzp07ZdiwYebhNWeXBt3STJc7lHYQeP26xzgJAQQQQAABBBAoVwFXBV59+EwDbWxsbBFUXb+r24xt2LDB7Nqwe/duSUtLk6efflqaNGliztWdHPSBtpycHOnbt6950C0xMZHAW663JxdHAAEEEEAAAQTsBVwVeO05AquBGd7AvDgbAQQQQAABBBAoDwECr4U6gdcCj6IIIIAAAggggECEBAi8FtAEXgs8iiKAAAIIIIAAAhESIPBaQBN4LfAoigACCCCAAAIIREiAwGsBTeC1wKMoAggggAACCCAQIQECrwU0gdcCj6IIIIAAAggggECEBAi8FtAaeF98+i9So1Yt6X5pf4uaKIoAAggggAACCCAQLgECr4WsE3i1ioxB11rURFEEEEAAAQQQQACBcAkQeC1kvQNvv4FXS3xCgkVtFEUAAQQQQAABBBAIhwCB10LVO/CmX9JH6tRPsaiNoggggAACCCCAAALhECDwWqgSeC3wKIoAAggggAACCERIgMBrAU3gtcCjKAIIIIAAAgggECEBAq8FNIHXAo+iCCCAAAIIIIBAhAQIvBbQBF4LPIoigAACCCCAAAIREiDwWkBr4H1j4kty/NhR4aE1C0iKIoAAAggggAACYRQg8FrgauCd/K9X5PDBAwReC0eKIoAAAggggAAC4RQg8FroauCdM3O6fLtxvTRv2VrSWrWxqI2iCCCAAAIIIIAAAuEQIPBaqBJ4LfAoigACCCCAAAIIREiAwGsBTeC1wKMoAggggAACCCAQIQECrwW0d+BNSW0knbr2sKiNoggggAACCCCAAALhECDwWqh6B16tJmPQtRa1URQBBBBAAAEEEEAgHAIEXgtV38Db/dLLpUat2hY1UhQBBBBAAAEEEEAg1AIEXgtR38DLXrwWmBRFAAEEEEAAAQTCJEDgtYDVwPvVki9kw+qV5uUTHbv2kAapjSxqpCgCCCCAAAIIIIBAqAUIvBaiGngzMzNly4Z17MVr4UhRBBBAAAEEEEAgnAIEXgtdAq8FHkURQAABBBBAAIEICRB4LaAJvBZ4FEUAAQQQQAABBCIkQOC1gCbwWuBRFAEEEEAAAQQQiJAAgdcCmsBrgUdRBBBAAAEEEEAgQgIEXgtoJ/Du37NbVn61RFIapkqnbj0taqQoAggggAACCCCAQKgFCLwWok7gPXwgS5Z/vkjq1Ksv6b36WtRIUQQQQAABBBBAAIFQCxB4LUQJvBZ4FEUAAQQQQAABBCIkQOC1gPYNvDVq1ZL0S/pKfEKCRa0URQABBBBAAAEEEAilAIHXQtM38GpVvF7YApSiCCCAAAIIIIBAGAQIvBaoTuD9/ugRWfrpJ6amlu06SNO0Cy1qpSgCCCCAAAIIIIBAKAUIvBaaTuDVKuZNn2pqat6ytaS1amNRK0URQAABBBBAAAEEQilA4LXQJPBa4FEUAQQQQAABBBCIkACB1wKawGuBR1EEEEAAAQQQQCBCAgReC2jvwLtlwzr5duN6SW3STNp1SbeolaIIIIAAAggggAACoRQg8FpoegdeXj5hAUlRBBBAAAEEEEAgjAIEXgtcAq8FHkURQAABBBBAAIEICRB4LaAJvBZ4FEUAAQQQQAABBCIkQOC1gPYOvM5evPq2te6X9reolaIIIIAAAggggAACoRQg8FpoegdercbZizdj0LUWtVIUAQQQQAABBBBAIJQCBF4LTQKvBR5FEUAAAQQQQACBCAkQeC2gCbwWeBRFAAEEEEAAAQQiJEDgtYD2DbwLPpgu+fn50m/g1RKfkGBRM0URQAABBBBAAAEEQiVA4LWQ9A28yxcvlMMHD0j6JX2kTv0Ui5opigACCCCAAAIIIBAqAQKvhSSB1wKPoggggAACCCCAQIQECLwW0AReCzyKIoAAAggggAACERIg8FpAE3gt8CiKAAIIIIAAAghESIDAawFdUuDt2LWHNEhtZFEzRRFAAAEEEEAAAQRCJUDgtZAsKfA2b9la0lq1saiZoggggAACCCCAAAKhEiDwWkgSeC3wKIoAAggggAACCERIgMBrAV1S4E1t0kzadUm3qJmiCCCAAAIIIIAAAqESIPBaSJYUeOvUqy/pvfpa1ExRBBBAAAEEEEAAgVAJEHgtJAm8FngURQABBBBAAAEEIiRA4LWA9g28Wzask283rhdmeC1QKYoAAggggAACCIRYgMBrAeobeA8fyJLlny8i8FqYUhQBBBBAAAEEEAi1AIHXQtQ38Obn5cmC2TMkPiFB+g282qJmiiKAAAIIIIAAAgiESoDAayHpG3i1qnnTp5oaMwZda1EzRRFAAAEEEEAAAQRCJUDgtZAk8FrgURQBBBBAAAEEEIiQAIHXAprAa4FHUQQQQAABBBBAIEICBF4LaAKvBR5FEUAAAQQQQACBCAkQeC2gSwu83S+9XGrUqm1RO0URQAABBBBAAAEEQiFA4LVQLC3wpl/SR+rUT7GonaIIIIAAAggggAACoRBwZeBdsGCB3HXXXfLWW29JmzZtPE4jRoyQFStWSExMjPmz4cOHyz333GP+f+rUqTJhwgTJzc2VjIwMGTdunMTFxZVqTOANxS1IHQgggAACCCCAQHgFXBd4X331VZk/f75kZ2fLE088USTwXnnllTJp0iSpW7duEdWtW7eKhuEpU6ZIgwYNZPTo0dKpUycZOXIkgTe89x+1I4AAAggggAACYRdwXeBdunSpdOnSRW644QZ58MEHiwTe3r17y6JFizwzvI7uxIkT5dixYzJmzBjzR+vXr5exY8fKtGnTAg68yxcvlMMHDwhLGsJ+73IBBBBAAAEEEEDALwHXBV6n19dff708/PDDRQJv586dpWHDhmb2t23btibUNmnSRO677z5JT0+XIUOGmOKnTp0yv1+9ejWB16/biJMQQAABBBBAAIHoFahUgff48eOSnJws+fn5ZmnD+++/L7NmzTLrffv37y8DBw70jJSuz920aZNnNvj3v//9WaM4d+5cyczMLPLnzPBG781OyxBAAAEEEECgcgpUqsDrO8Q9e/Y0ofeFF16Qjh07ytChQ80pGoy7d+8ua9as8RTR8Ot76JpgAm/l/ItDrxFAAAEEEECg4ghU6sDbrVs30Vla3aFh3759ZomDHqtWrZL7779fZs6cWepIFrdLAzO8Fefmp6UIIIAAAgggUDkEKk3g1UC7f/9+ad++vRQWFsorr7wiCxculDfffFN27twpw4YNk8mTJ3t2aWjRooWMGjWKwFs5/h7QSwQQQAABBBBwsUClCby7du2SO+64Q3bs2CFVqlQRfYBNZ3F1GzI9dC3v+PHjJScnR/r27StPPvmkJCYmBh14m7dsLWmtftwD2MX3EF1DAAEEEEAAAQSiWsC1gTcS6qUtaSDwRmIEuAYCCCCAAAIIIFC2AIG3bKMSzygt8NapV1/Se/W1qJ2iCCCAAAIIIIAAAqEQIPBaKBJ4LfAoigACCCCAAAIIREiAwGsBTeC1wKMoAggggAACCCAQIQECrwV0cYH3my+/kKy9e4QlDRawFEUAAQQQQAABBEIoQOC1wCwu8G7fkikb16wi8Fq4UhQBBBBAAAEEEAilAIHXQrO4wKvVzZs+1dSaMehai9opigACCCCAAAIIIBAKAQKvhSKB1wKPoggggAACCCCAQIQECLwW0AReCzyKIoAAAggggAACERIg8FpAE3gt8CiKAAIIIIAAAghESIDAawFN4LXAoygCCCCAAAIIIBAhAQKvBXRZgTf9kj5Sp36KxRUoigACCCCAAAIIIGArQOC1ECTwWuBRFAEEEEAAAQQQiJAAgdcCmsBrgUdRBBBAAAEEEEAgQgIEXgtoAq8FHkURQAABBBBAAIEICRB4LaAJvBZ4FEUAAQQQQAABBCIkQOC1gC4r8DZv2VrSWrWxuAJFEUAAAQQQQAABBGwFCLwWggReCzyKIoAAAggggAACERIg8FpAlxR4ly9eKIcPHhBmeC1wKYoAAggggAACCIRIgMBrAVlS4N2yYZ18u3E9gdfClqIIIIAAAggggECoBAi8FpIEXgs8iiKAAAIIIIAAAhESIPBaQBN4LfAoigACCCCAAAIIREiAwGsBTeC1wKMoAggggAACCCAQIQECrwV0SYF3+5ZM2bhmlafm1CbNpF2XdIsrURQBBBBAAAEEEEAgWAECb7ByIlJS4D18IEuWf77IU3OdevUlvVdfiytRFAEEEEAAAQQQQCBYAQJvsHIEXgs5iiKAAAIIIIAAApETIPBaWDPDa4FHUQQQQAABBBBAIEICIQ+8eXl5cuDAAUlNTY1QF8rvMv4GXm1hxqBry6+hXBkBBBBAAAEEEKjEAiELvEePHpWHH35Y5syZI4WFhbJx40bDOn36dNm2bZvcfvvtrmMuKfDm5+XJgtkzivS3V8YAqZaU5DoDOoQAAggggAACCES7QMgC75gxY+TUqVMm2A4ePFjWrl1r+q7B95ZbbpGFCxdGu0XA7Ssp8GpF86ZPLVJfSsNU6dStZ8DXoAACCCCAAAIIIICAnUDIAm96errMnTtX6tatK23btvUEXp357dGjh6xbt86upVFYOpDAy04NUTiANAkBBBBAAAEEKoVAyALvRRddJLNnz5ZzzjmnSOD96quv5K677pLFixe7DrS0wPvZ3A8l52S2p88EXtcNPx1CAAEEEEAAgQoiELLAO27cONm9e7c88sgj0r9/f1m2bJl8/fXX5vcDBw6U0aNHVxAS/5tZWuBdvnihHD54gMDrPydnIoAAAggggAACYREIWeDNzc2VCRMmyKRJkyQnJ8c0NjExUX7zm9/InXfeKfHx8WHpQHlWSuAtT32ujQACCCCAAAII+CcQssDrXE63Jdu1a5ecPn1amjRpYkKvWw8Cr1tHln4hgAACCCCAgJsEQh543YRTVl8CCbxaF3vxliXK1xFAAAEEEEAAgdALhCzwlrVG95lnngl968u5RgJvOQ8Al0cAAQQQQAABBPwQCFngff7554tcTvfk3b59u8yfP9/szXvrrbf60ZyKdQqBt2KNF61FAAEEEEAAgcopELLAWxKf7tTwyiuvyEsvveQ6YX8Cb/OWreXbjetN39Mv6SN16qe4zoEOIYAAAggggAAC0SwQ9sCrne/Xr58sWLAgmh2CaluggVfDb1qrNkFdi0IIIIAAAggggAACwQmEPfDqm9Z++tOfyqJFi4JrYRSX8jfwbt+SKfn5+ULgjeLBpGkIIIAAAggg4FqBkAXeZ5999iwk3Y/3008/lZ49e5oXULjt8Dfwar91WQOB1213AP1BAAEEEEAAgYogELLAe88995zV3+TkZGnXrp0MHjxY4uLiKoJHQG0k8AbExckIIIAAAggggEC5CIQs8JZL68v5oqUF3t3bt8nJ7BPSILWR7N+zmxnech4rLo8AAggggAAClVfAKvBmZWX5LZeS4r7dCUoLvN4wWzasI/D6fadwIgIIIIAAAgggEFoBq8Crgc/fIzMz099TK8x5/gZeneFd+dUSSWmYKp269aww/aOhCCCAAAIIIICAGwSsAu+JEyf8NtD1vG47/A28hw9kyfLPF0mdevUlvVdftzHQHwQQQAABBBBAIKoFrAJvVPcsAo0j8EYAmUsggAACCCCAAAKWAiELvCdPnpS33npLNm3aJPpaYd/jr3/9q2VTo6+4v4E3Py9PFsyeIfEJCdJv4NXR1xFahAACCCCAAAIIuFggZIH3jjvukO3bt0tGRoa8+eab8otf/EK2bt1qXjjx+OOPyxVXXOE6Rn8Dr3Z83vSppv8Zg651nQMdQgABBBBAAAEEolkgZIG3S5cuMm/ePKlXr555s9rMmTNNv6dPn25C7zPPPBPNDkG1jcAbFBuFEEAAAQQQQACBiAqENPAuXrxYkpKS5Oqrr5Zp06ZJbGys6NvWunXrJitXroxoxyJxsUAC75IFH8vxY0d521okBoZrIIAAAggggAACXgIhC7wjRoyQm2++WXr37i2333679O/f3wRfDbq33HKLfPnll66DDyTwLl+8UA4fPCCpTZpJuy7prrOgQwgggAACCCCAQLQKhCzwrlmzRmrWrClNmzaVVatWyQ033GB+ry+n0AB82223RatB0O0KJvCyNVnQ3BREAAEEEEAAAQSCEghZ4PW9+t69e0VDcOPGjaV169ZBNS7aCwUSeJ23rRF4o31UaR8CCCCAAAIIuE0gZIF3wIABZgmDPrB27rnnus2p2P4EEnidl09UTUqSdp3TpU59971quVIMOp1EAAEEEEAAgQonELLAO3XqVPnggw9kyZIl0qFDBxN+NQTXrVu3wqH42+BgAq/W3bxla0lr1cbfy3AeAggggAACCCCAgIVAyAKv04YjR47I3LlzZfbs2bJ8+XLp2bOnCb9XXXWVRTOjsyiBNzrHhVYhgAACCCCAAALeAiEPvN6Vb9myRR577DH5/PPPJTMz03XyBF7XDSkdQgABBBBAAAEXCoQ88B46dEjmzJljZni/+eYb6dWrl5nhHThwoOv4CLyuG1I6hAACCCCAAAIuFAhZ4H333XfNGl7db7dTp06eNby1a9d2IduZLhF4XTu0dAwBBBBAAAEEXCQQssCrM7iDBg0yuzQ0atTIRUQldyWQwJuflycLZs8wlfHyiUpxe9BJBBBAAAEEEIgSgZAF3ijpT0SbEUjg1YbNmz7VtI+9eCM6TFwMAQQQQAABBCq5AIHX4gbQwPvi03/xO8ASeC2wKYoAAggggAACCAQpQOANEk6LBRp4t2/JlI1rVvkdkC2aRlEEEEAAAQQQQACBHwRcGXgXLFggd911l7z11lvSps2PL3hYtWqV3HvvvZKVlSWtWrWSZ555Rho0aGAo9MUZEyZMkNzcXMnIyJBx48ZJXFxcqTeKE3jjExKk38Cry7ypnLetsaShTCpOQAABBBBAAAEEQiYQ0sB76tQp2bFjhxw/fvysBurODZE4Xn31VZk/f75kZ2fLE0884Qm8p0+fNkH2kUcekT59+sjrr78uX3zxhbz88suydetWGTFihEyZMsUE4NGjR5udJkaOHOlX4NWTMgZdW2b3CLxlEnECAggggAACCCAQcoGQBd5PP/3UBEWdIa1atepZDV22bFnIG19chUuXLpUuXbrIDTfcIA8++KAn8K5cuVIef/xx0e3T9CgoKJAePXrIxx9/LJMnT5Zjx47JmDFjzNfWr18vY8eOlWnTphF4IzJqXAQBBBBAAAEEEAifQMgC74ABA+SPf/yj/OQnPwlfawOo+frrr5eHH37YE3inT59uZnTHjx/vqeW6666Thx56yMzspqeny5AhQ8zXdKZaf7969WoCbwDmnIoAAggggAACCESjQMgC76WXXio6yxsth2/g/c9//iPr1q0za3OdY/jw4TJq1Ch55513pH///kXeBqfrczdt2iQxMTHm9Llz557Vtd///vdmlwY9WNIQLSNPOxBAAAEEEEAAgaICIQu8V155pWiorF69elQY+wbeGTNmyMKFC82Das6hL8p49NFHTeDt2LGjDB061HxJ1yB3795d1qxZ4zn3qaeeOqtf//znPwm8UTHaNAIBBBBAAAEEEChZIGSBV2dA33zzTfntb38rTZs2lcTExCJXTUlJieg4+AbetWvXyv333+9Zl5ufny9du3Y1D7i9//77sm/fPrNuVw/dzUHPnTlzZqltdnZp0JMCmeGtmpQk7TqnS536kUaxpdUAACAASURBVDWJ6ABwMQQQQAABBBBAIEoEQhZ4O3ToICdPniyxW5mZmRHtsm/g1YfUrrjiCvMgW+/evc0uDfrA2qRJk2Tnzp0ybNgw8/Cas0tDixYtzHKH0g7vwJt+SZ8yA6yzS4PWqWE3rdWZLdN0mzIOBBBAAAEEEEAAgfAIhCzwnjhxotQWJicnh6cHJdTqG3j1tA0bNsg999wju3fvlrS0NHn66aelSZMmpoZZs2aZB9pycnKkb9++8uSTT541S+17KQ28r/39eck5mS3+BF4t/9ncD8353oc/s8MRxeNiCCCAAAIIIICAiwRCFnhdZOJ3VzTwTv7XK3L44AG/A29+Xp4smD2DwOu3MicigAACCCCAAAJ2AiENvN98841MnDhRdPlCYWGhXHDBBXLjjTfKxRdfbNfKKC0dTODVrsybPpXAG6VjSrMQQAABBBBAwH0CIQu8s2fPNutj9Y1lbdu2Ndt56S4Hb7zxhtkP9+qry371bkXjJfBWtBGjvQgggAACCCBQGQVCFnj1hRO6s4Guf/U+dG9eXQ9b3D62FR1cA++cmdPl243rpXnL1p6H0MrqFzO8ZQnxdQQQQAABBBBAIHQCIQu8rVu3luXLl4vvw2m6p61u/6UvfXDb4R14daeF9F5Fw35J/fXerUHPadr8AmnZvqPbeOgPAggggAACCCAQFQIhC7yXX365PPHEE+aFDd7H4sWL5bHHHpOPPvooKjocykZ4B974hATpN9C/ZRu+gTeQsBzK9lMXAggggAACCCBQGQRCFninTJkizz33nHlIrU2bNuahNZ3VffXVV81SB32rmdsO78CrfdPAq8G3rIPAW5YQX0cAAQQQQAABBEInELLAq01asGCBCbhbtmwRfZNZy5YtTQDu169f6FocRTX5Bl5/9+L1Dbw1atWS7pf2j6Ke0RQEEEAAAQQQQMA9AiENvO5h8a8noQq8erVeGQOkWlKSfxfmLAQQQAABBBBAAAG/BawDb1ZWltSqVUuOHj1a6kVTUlL8blRFOTGUgdff2eGKYkM7EUAAAQQQQACBaBGwDrw9e/aU4cOHm/W7pR36Mgq3Hb6Bt23ndGnUtFmZ3fRd0qAFCLxlsnECAggggAACCCAQlIB14NVtx5KSkuTkyZOlNsB3u7KgWhtlhXwDr7978RJ4o2wgaQ4CCCCAAAIIuFrAOvA6OvpGtWuuuUZq1KjhajDvzgUbePPz8uT7o0dk1/ZtsmfHNlMlM7yV5rahowgggAACCCAQYYGQBV59nbC+Ta1x48YR7kL5XS7YwOu0eMuGdeYtbQTe8htDrowAAggggAAC7hcIWeC98847pX379mYbsspyhDLwduzaQxqkNqosdPQTAQQQQAABBBCImEDIAu+KFSvkgQceEH3FcLdu3aRatWpFOnHVVVdFrFORupBv4A30jWneM7z+rv+NVN+4DgIIIIAAAggg4BaBkAXewYMHl2oybdo0t5h5+hHKwKu7O7Rs19GvN7W5DpIOIYAAAggggAACYRQIWeANYxujtmoNvKtWrpSsPbtk45pVEugMr3aMWd6oHV4ahgACCCCAAAIuEQhp4D116pR88803snfvXhk0aJAhys3NNb8mJia6hOzHbmjg1f2FnW3GCLyuG2I6hAACCCCAAAIuEAhZ4N28ebPcdNNNkp2dLceOHZMNGzYYnilTpshnn30mf//7313AVbQLTuA9mZ0ti+d9KFWTkqR3xoCA+skMb0BcnIwAAggggAACCAQsELLAq29b69u3r9x8882iW5StXbvWNGb79u3ys5/9TL788suAGxftBZzAq+2cN32qaW6g++lu35JplkPowYNr0T7itA8BBBBAAAEEKqJAyAJvhw4dZOnSpeata96B99ChQ9KrVy9Zt25dRfQptc2hCLzeb11LaZgqnbr1dJ0THUIAAQQQQAABBMpTIGSBt0+fPvKPf/xD2rRpUyTw6u4M+udz5swpz36G5dqhCLzaMJs1wGHpGJUigAACCCCAAAIuEghZ4H377bfltddekz/84Q8yduxYefHFF2X58uXy+uuvy+OPP+55iM1FdhLqwBufkCD9Bl7tJiL6ggACCCCAAAIIlLtAyAKv9mThwoUm9OoDbKdPn5YLLrhAbr31Vundu3e5dzQcDSgu8LZs10Gapl0Y0OW8lzVkDLo2oLKcjAACCCCAAAIIIFC6QEgDb2XDLi7wBvPgmXfg7ZUxQKolJVU2SvqLAAIIIIAAAgiETSBkgVd3Ynj33XfPaujJkyfl+uuvlxkzZoStE+VVcagCr7bf2eUhmBni8uo/10UAAQQQQAABBCqCQMgC78UXXyzLli07q89ZWVly+eWXy6pVZ7bectMRjsAbzAyxm0zpCwIIIIAAAgggEGoB68CrD6kVFhbK/Pnz5bLLLivSPl3Hu3r1aunSpYs8//zzoW57uddH4C33IaABCCCAAAIIIIBAmQLWgXf37t3y6aefyvjx4+V3v/tdkQvGxsbKueeeKxkZGRIfH19mYyraCd6B13ZrMWdJAzO8Fe0uoL0IIIAAAgggEO0C1oHX6eDUqVPl2msr1w4DBN5ov71pHwIIIIAAAgggIGIdeHWNbq1ateTo0aOleqakpLjOOxyBl7etue42oUMIIIAAAgggUM4C1oG3Z8+eMnz4cHnuuedK7UpmZmY5dzX0lw9H4K1Tr76k9+ob+sZSIwIIIIAAAgggUEkFrAPv8ePHJSkpSXT7sdKO5ORk1xETeF03pHQIAQQQQAABBFwoYB14HZM33nhDrrnmGqlRo4YLmYrvUnGBt2pSkvTOGBCwwWdzP5Sck9lSo1Yt6X5p/4DLUwABBBBAAAEEEECgeIGQBd62bdvK3LlzpXHjxpXGurjAq50P5vXAyxcvlMMHDxi7YMpXGnQ6igACCCCAAAIIBCgQssB75513Svv27eXGG28MsAkV93QCb8UdO1qOAAIIIIAAApVHIGSBd8WKFfLAAw9I69atpVu3blKtWrUiildddZXrVEsKvP0GXi3xCQkB9dd7hjf9kj5Sp777drUICISTEUAAAQQQQACBEAmELPAOHjy41CZNmzYtRE2OnmpKCrzBBNaNq1fK7u3fSX5+vgRTPnpUaAkCCCCAAAIIIBBdAiELvNHVrci0JpSBV1vszPISeCMzflwFAQQQQAABBCqHgHXg/eSTTyQ1NVXatGlTrNiePXvk2LFj0rJlS9eJegfeUARWAq/rbhE6hAACCCCAAAJRIGAdeIcMGSLDhg2T6667rtjuLF68WJ555hn573//GwXdDW0TQh14dVnD9m83S8t2HeRkdrb5/+YtW0taq+I/TIS2N9SGAAIIIIAAAgi4U8A68Hbu3Fnee+89SUtLK1Zox44dcvXVV4s+1Oa2I9SBd8uGdfLtxvUm5B4+kGW2KSPwuu2uoT8IIIAAAgggEGkB68DboUMHmT17tpx77rnFtn3v3r1y2WWXybp16yLdt7Bfj8AbdmIugAACCCCAAAIIWAtYB95BgwaZvXd1Fre446OPPpKnnnpKdK2v2w4NvC8+/RfPLKyzJKFt53Rp1LRZwN1lhjdgMgoggAACCCCAAAJlClgHXn2l8GuvvSZvvvnmWbO8+/fvl+HDh0tGRobcfffdZTamop3gG3i9A2sw6263b8mUjWtWSWqTZnL4YJbkZGezpKGi3RS0FwEEEEAAAQSiTsA68BYUFMgdd9whCxYsEH2AzdmNYfPmzfL++++btb2TJk2S5OTkqOu8bYOcwKsBtV2XdLENvLpud/nni85qVp169SW9V1/b5lIeAQQQQAABBBColALWgddR++CDD2TmzJmydetW8/IEXdPbv39/uf766yUxMdGVuE7gdQIpgdeVw0ynEEAAAQQQQKCCC4Qs8FZwh6Ca7wRefY2wvixi/57dZpeFYGdkmeENahgohAACCCCAAAIIlCpA4LW4QTTwTpzwtOd1wIcOZBF4LTwpigACCCCAAAIIhEOAwGuhqoF38r9eMfvl6gyvbeDVpsybPvWsFgU7Y2zRNYoigAACCCCAAAKuESDwWgylBt7//mey7NmxTXQrsvy8XLPLgk1AJfBaDAhFEUAAAQQQQACBYgQIvBa3hQbeOTOne96OVrd+itllgcBrgUpRBBBAAAEEEEAgxAIEXgtQ78Bbp36KtOucLp/N+1D0IbZ+A4t/EUdZl2OGtywhvo4AAggggAACCAQmQOANzKvI2d6BV7+g63idfXQzBl0bVM1LFnwsx48dLVLWZsY4qEZQCAEEEEAAAQQQcJEAgddiMH0Dr67jXbtiuakx2MC7fPFC8xCc90HgtRgkiiKAAAIIIIBApRcg8FrcAr6Bt3nL1mY9bygCb/WatYrM9OqSCQ3U1ZKSLFpMUQQQQAABBBBAoPIJEHgtxtw38DZtfoFs/3azqVHX8Opa3kCP3du3ycnsE3IyO9vs/uB96JIJDb4cCCCAAAIIIIAAAv4LEHj9tzrrTA28Cz/5WLZtyTSzsbr0wFmOYBtOndcUe19UZ3gbNW1m0WKKIoAAAggggAAClU+AwGsx5hp4MzMzxXklcLgDry6ZSGvVxqLFFEUAAQQQQAABBCqfAIHXYsx9A2/VpCTJyT4pIoVmxwab5QfFzfCmNmkm7bqkW7SYoggggAACCCCAQOUTIPBajLlv4NWqYkzcPbNFmU3g1TW83x89Iiu/WlJkqYSuE27ZvqNFqymKAAIIIIAAAghULgECr8V4O4FXg+nSTz8xNYUq8Gpd+Xl5pk6t39nfVx+E0zBdo1Zti5ZTFAEEEEAAAQQQqDwCBF6LsXYCr1bhLEEoLCyUmJgY6xle32at+d9yz64NOsOrM70cCCCAAAIIIIAAAmULEHjLNirxjOICb1x8vJzOz5eOXXtIg9RGFrUXLapLHPSlFDkns80Xul96ObO8IdOlIgQQQAABBBBwswCB12J0iwu8zgsjwrGjgvdb2GzXCFt0m6IIIIAAAggggECFEqhUgXfEiBGyYsUKs+RAj+HDh8s999xj/n/q1KkyYcIEyc3NlYyMDBk3bpzExcWVOpjFBd6q1apJzsmTEo7Au3H1Ss+LLQi8FervGY1FAAEEEEAAgXIUqFSB98orr5RJkyZJ3bp1i5Bv3bpVNAxPmTJFGjRoIKNHj5ZOnTrJyJEjAw68iVWqSO6pU2EJvNoYZ5aXwFuOf2u4NAIIIIAAAghUKIFKFXh79+4tixYt8szwOiM1ceJEOXbsmIwZM8b80fr162Xs2LEybdo0vwOvrrFdPO9Dz/nhmOHVyr/58gvJ2rtHeOtahfp7RmMRQAABBBBAoBwFKlXg7dy5szRs2FCys7Olbdu2JtQ2adJE7rvvPklPT5chQ4aYoTh16pT5/erVq/0OvHrivOlTPeenNEyVTt16hnxond0g2I835LRUiAACCCCAAAIuFahUgff48eOSnJws+fn5ZmnD+++/L7NmzZK77rpL+vfvLwMHDvQMs67P3bRpk2c2ePDgwWfdAmvXrjWvFnYO78CrrxlO79U35LeN92uMw1F/yBtMhQgggAACCCCAQDkLVKrA62vds2dPE3pfeOEF6dixowwdOtScosG4e/fusmbNGk8R/TPfQ2eMiwu8+khc7TAFXn0ZxYLZM0xTMgZdW863D5dHAAEEEEAAAQSiX6BSB95u3brJ3LlzzQ4N+/btM0sc9Fi1apXcf//9MnPmzFJH0HuXBj3xxxneGKlTr15YZnj1Op/N/dDsx9srY4BUS0qK/ruMFiKAAAIIIIAAAuUoUGkCrwba/fv3S/v27UXfhvbKK6/IwoUL5c0335SdO3fKsGHDZPLkyZ5dGlq0aCGjRo0KKvBq/XXrp4Qt8Do7NTRq2sw8vMaBAAIIIIAAAgggULJApQm8u3btkjvuuEN27NghVapUEV2OoLO4ug2ZHrqWd/z48ZKTkyN9+/aVJ598UhITEwMKvM7rf8MdeJ0H17RxvHGNv94IIIAAAggggEDpApUm8IbjRvBd0uAEUQ28NWvXlu6X9g/HZWX/nt2y8qslpm724w0LMZUigAACCCCAgIsECLwWg+kbeJ0dFKSwUCQmJmwPlXmuIyIt23WQpmkXWvSCoggggAACCCCAgLsFCLwW41ti4JVCEYlM4GU/XosBpCgCCCCAAAIIVAoBAq/FMGvg/WjWDNGXTNSoVVu8Z1612nBuG7Zkwcdy/NhR0/pwvdXNgoaiCCCAAAIIIIBA1AgQeC2GQgPvi0//xdSg4TaSgdf7WqlNmkm7LuzWYDGUFEUAAQQQQAABFwsQeC0G1zvw6sNj8QkJsvTTTzw1hnOG1zvwhuutbhY0FEUAAQQQQAABBKJGgMBrMRQaeGe9/55s/3azOHvier9emMBrgUtRBBBAAAEEEEAgRAIEXgtIDbxzZk6XbzeuN7XonrgbV6+UwwcPiL5euH8YX/37/dEjRWaT9fqs5bUYTIoigAACCCCAgGsFCLwWQ+vs0qAhV2d5NXDqUgMn8F4S5lf/es8mE3gtBpKiCCCAAAIIIOBqAQKvxfA6gXf39m2ydsVy0YfHcrJPeAJvh649pEFqI4srlF7UN/DqsopGTc8TXdPLgQACCCCAAAIIIHBGgMBrcSc4gdd5gKxqUpIkxCfI98eOir5trVpyslRLSjYBNK1VG4srFV9Ur7th9UrP9mTOWeFcOxzyTlAhAggggAACCCAQZgECrwWw94snnNnWKlWryqmcHBN4Y2J0Ja+YwJveq6/FlUouunzxQjOj7Huwnjcs3FSKAAIIIIAAAhVQgMBrMWjegdeZ5Y2Pj5f8/PwigbdGrVrS/dL+Flcquej+Pbtl+5bMs0KvLm9o2a6j2SqNAwEEEEAAAQQQqMwCBF6L0fd9tXCRNbWFhSI/zPDqJfoNvDqs4bO4mV7dG7hO/RSLHlIUAQQQQAABBBCo+AIEXosx9A283q/7FZ/A2zHMD7AReC0GkqIIIIAAAggg4GoBAq/F8PoG3m++/EKy9u7RZwFFCguKzPDqTGvd+ilm67JwHGv+t1z27Nh2VtXhDtrh6At1IoAAAggggAACoRQg8Fpo+gbeLRvWnXkJRaFWWnRJg3OZcO2g4Fy7arUkc6mck9menoXzoTkLPooigAACCCCAAAIRESDwWjD7Bl7nwTXf5Qzel9DtycIxy3syO9vsAVw1KVmy9uySjWtWeS4bzofmLPgoigACCCCAAAIIRESAwGvB7Bt48/PyZMHsGWXWGK5ZXt8Lez9EF6lrltl5TkAAAQQQQAABBCIsQOC1ANfA+8vX/ixd6zeTga0vNjV9NvdDz3ICfRFF9Ro1JSGxSpH1tZHaI1fX9epsr26Txo4NFgNNUQQQQAABBBCo0AIEXovh08B72WvjJFUS5ZHe15maijy4JoWiobdx0/Nk53db5VTOSc/V2nZOF90rN9yHs3sD63jDLU39CCCAAAIIIBCtAgRei5HRwHvVK49JdmyB3NIsXS5q2kKch8e837Sml6jX4Bw5uH+f52oahNMv6SvVks48ZBauwwngrOMNlzD1IoAAAggggEC0CxB4LUZIA+/If/+ffFeQLefHJsm9lwz2BF7fB9eanp8mdVIamAfLnAfKIrHMQB9mWzzvQ9NLZnktBpuiCCCAAAIIIFBhBQi8FkOngfeBKS/LF9l7TS3DUtvJufnxZmsy3ZksxqtuXb6gyxj0cB4m01lXPcL12mHn8gs+mG7W8eqscqeuPaRGrdoWvaYoAggggAACCCBQsQQIvBbj5Rt4W8XXkNs6Xu6ZUfWt2nlY7cd1vmfOiORrh5nltRhwiiKAAAIIIIBAhRQg8FoMm7Mt2cZ92+XZTYsluSBWnu37c88Mrm/Vzrrd3du/O/OCih+OcC9t2Lh6pWz/drO5mrahd8YAi15TFAEEEEAAAQQQqFgCBF6L8fLeh3fUorclL0bk/9IHyZdz55haNcjqoetoN67+xiwr0OPC1m0lc/1az5UjsWPDkgUfy/FjR8012ZPXYtApigACCCCAAAIVToDAazFk3oH34c/ek72Sa9bxJu89LIcPHjBvVNM3q+nx/dEjsvTTTzxXO6dRY9m3e5f5fST25XW2J9Pr9coYEPbdISxYKYoAAggggAACCIRUgMBrwekdeF//er55eK1zYl3pLjUla++es4KsvnpYty3TMOx96DKDRk2aecKxRZNKLOq9brhp8wukZfuO4bgMdSKAAAIIIIAAAlEnQOC1GBLvwPv19k0ycdtyqVMYL39q00+Wf76o2G3AvLcJK+7S4VpuoNdd+79lJmzz4JrFoFMUAQQQQAABBCqcAIHXYsi8A69Wc+tnb5vaHkjrLRuWfVVisPTdpUGkUAolxmxjFs7lBjrDrEE8PiHB7AzBgQACCCCAAAIIVAYBAq/FKPsGXmcd77W10yTm252m5uJmbEta2qDn6968zVu2kQapjSxaVnJRZw/gOvVTzBKK+Ph49uUNizSVIoAAAggggEC0CBB4LUbCN/A663jbx9aUlgdOmZq7X3p5sYEyPy9P9u/ZLWtXLPdpQYzUqFVTmqZdKHXqpYT84TLv3Rr0wixvsLgBKIoAAggggAACFUKAwGsxTL6B17OOtyBOLj8Sb2oua49dZ8b1x2b8+I62cIRR790anBll3RaNt69Z3AgURQABBBBAAIGoFiDwWgyPb+DVqpx1vKPqtpW9mzf7teWYzvbqzGvOyeyzWhPqh9h0lwjvl154X7CscG5BRVEEEEAAAQQQQKDcBAi8FvTFBV5nHe/AKqmStOeQX4FXm7Dmf8tlz45tP7RGH1/Tmd7wvCTCd5bXIWjUtJnobC8HAggggAACCCDgJgECr8VoFhd4nXW8bQqSpM2R06IPh9WtnyK6963ujlDSoQ+ybVi90rwNLTY2VkRipOD0aalRu5Y0bX6hHD6YZYrqA23VkpLM/+vMcGl1lnQtfQnG90ePFrN++Myrh9t1Tjft5kAAAQQQQAABBNwgQOC1GMXiAq+zjrd2QZz0/2Edr17Cn+UCutxg+5ZMzyuIi2taSmojqVmrtvnSoQNZJvDWrVdfGjU9L+Dwqw/NafjV9bsrv1pS5HIaeLXuTl17WAhRFAEEEEAAAQQQKH8BAq/FGBQXeLU6Zx3vdYeqeGpv2a6D2XmhrOPsPXpFYmPjJLFKopw6efKHhQ5n16LbmaVf0jfg0OvUVHRJxY/16xvZqlZLMrPUwcwml9Vfvo4AAggggAACCIRbgMBrIVxW4O37fYLsjyuQ9UmnpbPUkNt6/7TMq+kM78Y1q4o9LyExUZqcn2a+pm9Oy8k+cebXHx520+UIGkx1drZaUrJnj11/lj7okgoNtNu2bDb16++9H6LTJRka2J3lFGV2hBMQQAABBBBAAIEoESDwWgxESYH3jwunSHZsQZGaG+fHy0P9hpZ5NQ2neuTl5UnWnl2iyxzy8/OLlNNlDXroubFxcXLs8CEpKCiQ0z7n+V5MA6339mM6K5yQkGhOc9bsOi+i0LrX6KuID2R5rm+WOHTrafbu5UAAAQQQQAABBCqKAIHXYqRKCryz1y+T6Qcyi9RcPz9WxnToH3RY3Lh6pXlRRXFblzkXSqpeQ/JyT0l+bq7ExcdL1aRk8xBcKI6YmBgpLDyzc0SVqlWlfoOGktq02Q9Vx0iNmjVZ8hAKaOpAAAEEEEAAgZALEHgtSEsKvBv3bZcXNi6WPN1d7IcjoUBk0JEqxb5q2J8mOMsSdK2tzvzqa4GPHT3qtZXZ2bXoDK4eurZXZ4wTEhLMQ2rOoQ+9OYfO5Oqh54UqJJfUL9+ZZuc8/XPngTz9M++dImrUrGUCtT/LM/zx5BwEEEAAAQQQqDwCBF6LsS4p8GqVzy2ZKRvyvy9Su67pHTbwZxZXPFPUO/RpAG7ctJlZqqAzwNu2ZJ4VWJ3gqwGyRs3aovvt+nM4yys0JGsQ1mPvjm2yd/cuiZEf9wo2X4jxSvf+VB7Cc3Ttsq5Ztjl0bXJZdZQU1H2vy5IPm5GgLAIIIIAAAqEXIPBamJYWeHWW9/3N/5Ocgnw5WJArebEizU7Fyq9b9PA7cAbbNH2QTdf+mvW3eblnrQE+81BbkqQ0bCQNflgPHMi1tG59OE5niPUahw8e8BR3tjNr2a5jiQ+4aZD2nml2Cmuo9v5zZ9ZZv65/7ruWOZA2l/e5GpbVXD+YOHsp6wcU58/Ku31cHwEEEEAAATcLEHgtRre0wOtd7atL58hXeYekVn6MDE1sLI2aNAt76NVQeTL7hMQnJMru7d+ZwJi1d0+R3urMaO+MARYCZ4rqzhK+yytst0nzt1Ea7k2o/2EG2t9yvudpPepV2lFSUPct4/0BoKT61P7MEpOjZumGvuFOwy9LNoIdQcohgAACCCBQsgCB1+Lu8Dfw6iWcvXn1/4fn1JF2XS4WZ12qRRP8LqpBSpc76KyiLoHYtX2bWfqgM4/6UgydedTQZ7PtmD5Yp7O0P74iWaT7pZcX2RnC7wa76EQnKKuvzop7+3h3Uz8k6DnO2/n0gxF7H7voRqArCCCAAALlJkDgtaAPJPA+sGCKZMWf2apM1/Km5MVKx649glpSYNFkzwyizvjq+l/nAbWmaRfI7u3bTPjVtawb16w0s46BHhrYli6Y51l+4LyqWHeMsAnTgbYjms9Xe7XWMFvczLvTdifs6rIT/U9ng5u3bB3NXaNtCCCAAAIIRKUAgddiWAIJvP9d8rEsycmSo/GFkn4iQc47FWuWNTjrOS2aEXRRDacbV39TZKmDsxOCVuo83KbrcQOZadSZXj3/243rPW1LbdJM2nUJPEAH3bkKVFBn3XV5w5kAfNSzBKW4Ncvea4Gdh+yK282iAnWfpiKAAAIIIBB2AQKvBXEggVcv87f578vqhBxpnR0nbXPizZVTGqaalzmU57FkwcelbkWmIatZ2oXmR+2BLMPQH+UvW7zQU3evjAHM8vo50I6dzuxqCoFQewAAIABJREFUIA7FVnHewdjPZoT0NH3QMRyHv7tnBHNtfa02P5kIRo4yCCCAQHQJEHgtxiPQwPvfhbNlTuwR0T15+x5PlNr5Z7byKo+lDd7d1plefbBNf9VD9/nV2UV965o+9Ob9sgtdZ9qxa0+/Q4D+yH7pp5+YepnlDf5mc8ZIZ4L1cNYDa4h0draIxB7KwffAfSW9g7aOg/6eddfuG2d6hAAC7hAg8FqMY6CBd+2WDfL87v+ZK7bPqyoXxdT0PDimM3ot23eMin8wnW3NdAmCtkvDsM4yem8Npq83btCwkV+7TXiHXmZ5LW44i6L+7jBhcYkyi3q/6KTMkwM4IZx9078Lpb3d0LeZuma9WfMLzvw0pFbtAHrBqQgggAAC4RQg8FroBhp49VLeuzVcXTdNEjfvLNICfVDM3xdDWDQ9qKIaLHQP3u3fbvaUP/MPey0T1Ev7B14fkNPdCZjlDYqeQlEo4ARtnVl3PhA6S0/070T3S/tHYatpEgIIIFA5BQi8FuMeTOCdvX6ZTD+Qaa7aM6mh3HDRZSZEej/g1bZLugmQ0XroCyE0wPrOfOmsr/NqYP0HX5dD7N+zS5o2v9B0ZfG8Dz3boOnXWBsZrSNMu4IV0D2pN65ZZYoHuvwn2GtSDgEEEECgbAECb9lGJZ4RTOD9evsmmbhtuamzc2JdubhRmlzU5Ewg9H54rCL86N83qJdGqT/qzc09JQX5pyUmJkZi4mKlWrUk6dq7X0A7QFgMF0URiIiAbjm3dsWZv+MaenUnlmDeaBiRxnIRBBBAoJIIEHgtBjqYwLvryAF5dPXcIle9pVm6XNS0hdmbVUOkzpzqUoGW7TpE/TpAXZ+rP8513nimb3OrU6++6Z8/rwOuVbee1G9wjnkhg+4BzIGAGwSK+zBYET7EusGePiCAAALFCRB4Le6LYAKvXs57lte5fK/qqXLZ+e0l4WSurPxqiWd2qEFqY6les5Y4T4FbNDciRTX8+s5m6Z/p8gUNxZlrV8mJ48dNW3Sm1/uI1OuIIwLBRSq9gIZeved936xH8K30twYACCBQDgIEXgv0UAReXdawIvdQkVak5MXIkbhCaZMTb349ElcgrU9Xkfr5cdKxRVtJadiowq5/1VlsfcVxSfvK6qx207QzSzw4EKjoAs4rvb3X6OvynpzsbPPWvLRWbSp6F2k/AgggUCEECLwWwxRs4D128oRkZu2SfSeOysDWF8vrX8+XZSf2mpYkFMZKduyZVxAXdySdjpGasfHSqGoNSUqoIvWrVpeNR/ZJ73NbFjm9emIVaXlOU4veha+oLnXQt7EdPnjgrIvExsVJ42bnS6v2HcPXAGpGIMICCz6Y7nndtnNp3bdX32IYrbuyRJiIyyGAAAJhFSDwWvAGG3iLu6SG4D3HDkpqzXry33VfmlO+zT4kp0+flsLCQpHCQjkaVyh5sRYN9ipapzBeqsacqSytej3za5v658qJ3JOSVq+RNK59Zh1uuI6ztzjT5Q2FnstpGGjVobOkntvE7AUcyKuNw9Vm6kUgWAHn5SDbtmwussSBbfqCFaUcAgggEJgAgTcwryJnhzLwltYMXQeoW4FtXP2NHJA8yYsplB1JMZJSrabsy8+WnIJ8OVV4WqrExHmq0d8fjjkddO/0bXDVY+Ilt7DAzChXjY2Xxkm1PMG4pIovrN9IalZL9vu62re1/1tmZns18hYU6tpep3ihJNeoJadP55s1zDobRvD1m5YTo1hg3vSpntbpw5rl/drnKKaiaQgggEBIBAi8FoyRCrxOE3Wm87O5sz0/GtXw1yztQjl29IgJhDVq1pKqScl+re/duG+7HD+VY6pek7VTTubnyp7c4yY42wRlfzi9Z5c90baw0MxkO//VyhepIkWns5NOiyQVxEpCYqL5Ly831/RZZ8Hj4uKkdvUa0rRGPfNn+hIM/ZCgvxKS/RkVzom0wPLFC80HPQ27nbr24D6N9ABwPQQQqFQCBF6L4Y504NWm6sb2u7ZvK/GhLyfc6a4IGvZ0xwR9yC3QY+HmVfLd0QPSLuVcTyjW/9FlFqUdBwtzJa/o5guBXrrczk8uiDWz2c5RO76q1Kv642y1rpduUN2/18U6eyuXW2e4cNQLeO/XG81vWIx6SBqIAAII+CFA4PUDqaRTyiPwOm3R2d4z+9+eMGtcvV/369teDcE6i+S8BS0vL9eE4WpJyaa8/qqHzoxGYjbUe3a5JNtvD++T3fv2nFm//MORHVcoJ2J/+L2+vKKYwlnxJT/wZzHUESvqG7r9vbD3khN/y+h5GuI7pJ4f9jXbgbSpspyry3l06zLdtkz/3umODfrhNP+Hv5+VxYF+IoAAApEQIPBaKJdn4PVttvPj+7y8PMnJPmFmgbP27DKn5efnB9VL33WF+o+yE5q1Qufr8fHxYXtBhgYCDfQ6Y13azHZQHfQplB0ncsJrh4wTsSInYn4M0EUCdxkXPJDwY1APRdsiUUeqJIrOap+bXEfOr9NAAl2PHYk2uvEaxe3g4PSzY9cevKXNjYNOnxBAIOICBN4fyKdOnSoTJkyQ3NxcycjIkHHjxpl1oaUd0RR4S2unPiH+/dGjntlgZ1bYt4w/b0Yr6w7VUKyzx3p4B2TvPw92JlmD74bVKwOaATuVk2M+AOSeOiUnjn8vBaeLPsgXE3tmTXBScvWzXoRRVl+9v66zdfqGPNvDN3T7W58uIzlcwnZ2ap+QkGDWd/seukTlWEF+iVvh6cOL9WMTzU4e+mIUZ/cOfWNgjSrVAnpA0d++VLbz9O+d7+4NjoF+qNSH2vQc/UmMfqDVD38cCCCAAAKBCRB4RWTr1q0yYsQImTJlijRo0EBGjx4tnTp1kpEjR7oi8AZ2S/x4ts4a+4Y6Dct6aPh0tlrSf4RLepFEcdfWN6rpoW+Rc4KxhmStW4NZfEKihGPWWEOproHWazmvcHbap6FQHxzSgBHpbdB8nf0dL+2PMx7eZXRc9GvFjYna69fUQB90bNr8AvPBJOvwQdlyaI/sOnFEsk4eNw8w7pXcs5pyfuyZsLU/P8esd06tUl1a1W0kDWvUjtp9n/31LO/zzAfOvDxzb3r/ndIXVXgf+qBqoybNIrL8qLxNuD4CCCAQKgECr4hMnDhRjh07JmPGjDGu69evl7Fjx8q0adMqdeAN5ibzDcJOKDYzoNknin3ZRCDX0cBmArHP8goNBc5aZK1Pd3DwfcWx73X05Re+a5+1fp0Jbdc53QR6Z5cH7Zd3OA6kzeV5roZpZ62oPzPQGvjVICEhUVIapsqxwnzZfGC3fLh7fZm7d+jrsXUv52h+6Ul5jkUg19Z7z2xFuGaV+fDnuyxJx8j5wKj3/skTJ8z9rn83znxoTAjkcpyLAAIIuF6AwCsi9913n6Snp8uQIUPMgJ86dcr8fvXq1QTeEP8V0OB46ECWeeBOD/1H3fnHWf+hdo5AZ42tm1n0vRee6mJiYiQu/szODQUFBZKQmCDJ1WsW+2PlpORkiY2P3qBx7PBh0w8NvrqVW35uruTknDT98uf4PDlXkk/HSJXYOFlb5ezZX+869LwTcYWiSyLqFMZJrhRKosRI49hqcl7Vkne6SEpMlPNqpfjTHNeeo0updImNHt9u2iANzmloljzoh6/9P6zLL6vz9c45R+Li4s0e1lWrVjOn632sf5ZYtWqJxZOSkj33e1nXCNXXg13iFKrrUw8CCFQOAQKviNx1113Sv39/GThwoGfUdX3upk2bPOs6J02adNYd8eijj0pmZmbluFOipJfOj/+9f5zvPatcboE5Snwi1YzvqhRIcoHI/rgCORJfaF6Gkh0rog/2cSAQrQLXHaoSrU2jXQiUKZAx6Noyz+GEkgUIvCJy//33S8eOHWXo0KFG6vjx49K9e3dZs2aNR+6NN944S/Gxxx4j8Lrkb5ez5EK7o/uj1j+noSRWqSLHjx6Vvbt3mhm37BPHJT9flzbEmAfnfI/T+flFtlFzCc1Z3fDeKs73izqrG3+6UHYnFEheTIHkFBZK1R9enbcj/rQkFMaYcFzSoQ/fHY0nNLv13invfhF4y3sEuL6NAIHXRk+EwCsir732muzbt8+s29Vj1apVJgTPnDmzVN2KskuD3S1CaQQQQAABBBBAoGILEHhFZOfOnTJs2DCZPHmyZ5eGFi1ayKhRowi8Ffv+pvUIIIAAAggggAAzvM49MGvWLBk/frzk5ORI37595cknn5TExEQCL39JEEAAAQQQQACBCi7ADK/FALKkwQKPoggggAACCCCAQIQECLwW0AReCzyKIoAAAggggAACERIg8FpAE3gt8CiKAAIIIIAAAghESIDAawFN4LXAoygCCCCAAAIIIBAhAQKvBTSB1wKPoggggAACCCCAQIQECLwW0AReCzyKIoAAAggggAACERIg8FpAE3gt8CiKAAIIIIAAAghESIDAawFN4LXAoygCCCCAAAIIIBAhAQKvBTSB1wKPoggggAACCCCAQIQECLwW0AReCzyKIoAAAggggAACERIg8FpAE3gt8CiKAAIIIIAAAghESIDAawFN4LXAoygCCCCAAAIIIBAhAQKvBbQGXg4EEEAgEIHu3bvL0qVLAynCuQgggIBkZmaiYCFA4LXAmzRpkhQWFsqIESMsaqGoWwR++tOfyjvvvCPVqlVzS5foR5AC06dPl+3bt8sf/vCHIGugmJsEhg8fLk8//bQ0bNjQTd2iL0EIfPHFF/LRRx/JuHHjgihNERsBAq+FHoHXAs+FRQm8LhzUILtE4A0SzqXFCLwuHdggukXgDQItREUIvBaQBF4LPBcWJfC6cFCD7BKBN0g4lxYj8Lp0YIPoFoE3CLQQFSHwWkASeC3wXFiUwOvCQQ2ySwTeIOFcWozA69KBDaJbBN4g0EJUhMBrAUngtcBzYVECrwsHNcguEXiDhHNpMQKvSwc2iG4ReINAC1ERAm+IIKkGAQQQQAABBBBAIDoFCLzROS60CgEEEEAAAQQQQCBEAgTeEEFSDQIIIIAAAggggEB0ChB4o3NcaBUCCCCAAAIIIIBAiAQIvCGCpBoEEEAAAQQQQACB6BQg8AYxLgUFBfLEE0/IrFmzJCEhQX7729/KL3/5yyBqokg0C+hb9P7+97/Lv/71L/n666+LNHXq1KkyYcIEyc3NlYyMDPPWnLi4OCnt3uC+iebRLr1t+nf9xRdflMOHD0u9evXkoYcekq5du5pChw4dkrvvvltWrVoldevWlSeffFIuuugi8zX9s3vvvVeysrKkVatW8swzz0iDBg3K/FrFlXJ/y48dOyZ/+9vfZPbs2aaz5513njz++OPmVz1K+t5Q2tf43uCO+0bfpjd37lzzX1nfG4L9vuEOqfLpBYE3CPd3331XZs6cKRMnTpTs7Gz5+c9/Ls8++6y0a9cuiNooEo0CeXl58sc//tGEEx3rZcuWeZq5detW8zrpKVOmmK+PHj1aOnXqJCNHjpTS7g3um2gcaf/apB98Bg8eLI0bN5avvvpKbr/9dlmyZInExMTImDFjzJ/fcccdJuDqr/rqUP0wrB+GHnnkEenTp4+8/vrrolsSvfzyy3L69OkSv+ZfizirvAT0w8snn3xi7oeqVavKv//9b1m0aJG89tprUtr3hmC/b5RXP7luYAL6d18nQXbu3OkJvCV9b9D7JpjvG4G1iLN9BQi8QdwTN954o/z617+W3r17m9L6DW/Pnj0yduzYIGqjSLQK6D9ivXr1MrN1K1as8DRTP+joLI9+w9Jj/fr1ZuynTZsmpd0b3DfROtKBt6tz587y6aefSo0aNSQ9PV0+//xzqVatmqlIf+Lzs5/9zMwE68yfftDRQ2fxevToIR9//LF8++23JX5N6+SoOAKZmZkyatQo8yGntO8NwX7fqDgSlbel+pM+nfjSn/TpBIjO8Orf95K+N1x66aVBfd/ge4PdPUbgDcLv8ssvlzfeeMPM6uihwUh//8orrwRRG0WiWSA/P18uvvjiIoH3vvvuM9+shgwZYpp+6tQp8/vVq1dLafcG9000j7T/bdu8ebPceuutZpZv79695h86Db/O8X//939Su3ZtM/uvM7rjx4/3fO26664zyyF0tq+kr3Xo0MH/xnBmuQroj6V1Bl+Xq/zud7+T0r43BPt9o1w7yMX9EnjqqackNTVVrrzySvP9QANvad8b9CVFwXzf4HuDX8NR4kkE3iD8LrnkEpkxY4aZwdFDf8SpP8p4++23g6iNItEsUFzgveuuu6R///4ycOBAT9MvvPBC2bRpk5kRLune4L6J5pH2r216P+hPd2644QazJOG7776T2267TebMmeOp4IUXXjCzOw0bNpR169aZWR/n0Ddu6Wzgtm3bSvxa9+7d/WsMZ5WbgP7Y+tprrzXrt/Unfbp2U9dvl/a9QWf+gvm+UW6d5MJ+CXzzzTfy3HPPmZ/06hp/J/CW9r1h0KBBQX3f4HuDX0NC4LVjKlpav2m9+uqr0qxZM/MFnenRsKt/xuEugeIC7/333y8dO3aUoUOHms4eP35c9BvRmjVrzD9oJd0b3DcV+97QEKvLWPTvva7T1WPfvn0m+CxevNjTOX1orX79+ibwLly40Dyo5hz6D92jjz5qAm9JX9N7i6NiCOhPd/SBxpdeesl86Hn44YdL/N4Q7PeNiiFROVup4/+LX/xCnn/+eTn33HPNByAn8Jb2vUG/DwTzfYPvDXb3GTO8QfjpjzOvv/56ueyyy0zpf/7zn+YfvgceeCCI2igSzQLFBV59OEXH21mzrQ8r6D9m+nBbafcG9000j3TpbdMdO3SMk5OTza/OoX+uS17mz58vNWvWNH980003me8PjRo1Mufq2m499F7SnR303F27dpX4NV0OwVGxBPSnN7o7g+7cUNL3hmC/b1QsicrVWn2YWR9Wjo+P93T8xIkT5vuEfhDSYFvc9wad/Ajm+wbfG+zuLwJvEH7Tp08339ycXRp0pu/Pf/6zuYE53CVQXODVH2cOGzZMJk+e7NmloUWLFuZH1aXdG9w3FffeeOyxx0TDra6/9T10babO6N55551mlwZd4qAPpiUlJckVV1whDz74oPmxt+7SoH8+adIks+ShpK9VXKXK0XJ94FADzTnnnGM6rA+r6TaVOmOvH2RK+t4Q7PeNyqHqjl56z/Bqj0r63lC9evUSv1ba9w13KJVfLwi8QdrrInUNvbotkT59f/PNNwdZE8WiWaC4wKvt1U/v+jBSTk6O9O3b1+y9mpiYaLpS2r3BfRPNo1182/QBs5/85CcSGxtb5ARdk3nLLbeYHTvuueces1ezzvLqQ0zODi4bNmwwX9u9e7ekpaWZtZ5NmjQx9ZT2tYqnVHlarA8basDV9Zo6s3fBBRfIn/70J2nZsqVBKO17Q7DfNyqPbsXuqW/gLe17Q7DfNyq2UPm2nsBbvv5cHQEEEEAAAQQQQCDMAgTeMANTPQIIIIAAAggggED5ChB4y9efqyOAAAIIIIAAAgiEWYDAG2ZgqkcAAQQQQAABBBAoXwECb/n6c3UEEEAAAQQQQACBMAsQeMMMTPUIIIAAAggggAAC5StA4C1ff66OAAIIIIAAAgggEGYBAm+YgakeAQQQQAABBBBAoHwFCLzl68/VEUAAAQQQQAABBMIsQOANMzDVI4AAAggggAACCJSvAIG3fP25OgIIIIAAAggggECYBQi8YQamegQQQAABBBBAAIHyFSDwlq8/V0cAAQQQQAABBBAIswCBN8zAVI8AAggggAACCCBQvgIE3vL15+oIIIAAAggggAACYRYg8IYZmOoRQAABBBBAAAEEyleAwFu+/lwdAQQQQAABBBBAIMwCBN4wA1M9AggggAACCCCAQPkKEHjL15+rI4CAHwKrVq2S+++/X7Zt2yY//elP5YknnvCjFKcEIvDnP/9ZsrOz5bHHHgukGOcigAACFUKAwFshholGIhB5gb59+0qTJk3kzTffLHLxLVu2yHXXXScrVqyIWKP0ev3795eRI0eaUFa7dm2ra7/wwgty4sQJuffee009+qvW3aJFi5DWa1VZhAuHOvD+97//lePHj8uvfvUrT09GjBghN9xwg1x++eUR7h2XQwCByi5A4K3sdwD9R6AEAQ2833//vTz44INyzTXXeM4qj8DbqVMnmTx5srRu3Tok4/XVV1/JqVOnpHfv3pKbm2sC2KuvvmodeL3rDUlDI1hJqAPvHXfcIenp6UUC73vvvSddu3aVpk2bRrBnXAoBBBAQIfByFyCAQLECGnhvueUWef755+Wjjz7yzKoWF3jfffdd+cc//iF79uwxs8IadgYOHOiXrAbOp59+WmbMmGECdocOHeShhx4y4TYzM1PGjh0rK1eulBo1akhcXJzMmzfvrBlereOpp56SmTNnmlnFtLQ0mTRpknz99dcydepU+dnPfiaPPvqomdX98ssvxQl3Dz/8sAwZMkTWr1/vqV+XS/zkJz+RvXv3in79888/l3r16snPf/5zue222yQmJkbmz59far3OsgCtQ/9/8eLFEhsbK5deeqmp05mh1nZUrVpVdu3aJf/73/8kPz9funfvbtqqf17coX3Sr2/evFmaNWsmo0ePNoF9zpw58uSTT8rChQtNG51Dr/mnP/1JBgwYIM8++6x8+OGHZpwaNWpk/tyZbfUOvDt37pR+/foZl/j4eE9dF154oXz88cfmuocOHTLXW7p0qRw7dkzatGljft+8eXN54IEHjE9CQoJUqVLFGOs4Dh48WG666Sa56qqrTJ3aZ73uunXrpFatWjJ06FC5/fbbjZUeer7OCr///vuibdJ+/fKXvzR16KFef/nLX+SDDz4wbdAgfdddd0lGRoZf9x4nIYBA5REg8FaesaanCAQkoIH3lVdekYkTJ5rQo8FED9/AqwHrnnvukeeee046duwoy5YtMyFMZ0x1ZrasQ4OqhlD9NSUlxQQlDc+ffPKJVK9e3RRv27at6I/IS1pyoKHniy++kMcff9wEuU2bNknPnj1NMNXAWb9+fbMG+JxzzpHU1FRP4HWCaXH1a0ju06eP/OY3v5H9+/fLb3/7W/P/Gnz9rVeXYmibNYSdPn3ahLOjR4/Ka6+9Zvqlpv/617/kpZdeMsHz5MmTJuBpYNMPG76HhkwNrhostX8aGH//+9+LfuDQENqtWzfj3qVLF1P0m2++kV//+tcmlGqA1g8u+kFCDWbNmmWCs46XM77OGl5/Am9eXp7Mnj3bzJInJSUZ+3379sk///lPc21dIqKh2XtJg3fgPXjwoFmmoveOrsvW0K/3jf7/rbfe6gm8Bw4cMB9ezj//fBN69ev//ve/zb2ms/4ahv/+97+be0WDs95DasGBAAIIeAsQeLkfEECgWAENvBokzj33XBOydKb34osvPivwaqDR0OMd0P7617/Kxo0b5cUXXyxVV2dmO3fuLG+//bYJMM4xbNgw+X//7/+Z9Z5lBV6nDl1rrHV5HxpMNTzprPB5553n+ZLvj+99A6/OomoQ09DtHFq/zo6+9dZbJvCWVa8GSZ0R1iCus5x66OzzJZdcIv/5z3+kVatWJvDqA3ka3JxDP2CsWbPGePse6qmhTwOvc/zhD38QnXnVmVGdRdXwqctQ9NDzNGCPHz/+rLoKCwvNB4m5c+eaMQ50hte3QjXTYK8fgPQoK/D+7W9/M+vANaA7hwZzDfBalx4akHWG+s477/Scc+ONN8pll11mZnp1LKZNmyZvvPGGVKtWjb/JCCCAQIkCBF5uDgQQKFZAA6+Gkvbt25sfl2uI1WUH27dvL/LQms406uxsr169PPVoUNTZTA2apR1bt241ywfWrl0riYmJnlM1qOlso84a6lHaDG9JdWg5Daa6hOCzzz4r0oyyAq8GUg2N+iN559CAqLPH+iN9f+qdMmWKmX185513ilx70KBB5kfyOlOp7Thy5EiRQKqzmQsWLPDMAnsX1kCps6q6tMM5CgoKzBprNVuyZImZJdUlFPrjf52h1nHQkK0zsjqzrO3XmWT9+oYNG8zY6hKQQAOvzua+/PLLJrRq3Tk5OSbQa2j1J/D+8Y9/NEFb2+scWl4/tOgykgYNGniWNOiSCOcYNWqUuSf1A4euw7777rtF105ff/31Mnz4cDPDy4EAAgj4ChB4uScQQKDMwKsnaNDQ4Kkzr9dee61nlwZ9MGnChAlFAq+GKp1VLCvw6iywruf0Dby6jlZDmT+BV5dYXHHFFWfV4QReDXw6i+l9lBV4dcZZH7DSwFrcoYG3rHp11lGXDfgG3quvvlpuvvlmT+D13QqstMCra6OdtbfFtUvDr4ZcXauryxR0tlTDrwZkDcQ6m6xj1bBhQ9EA37JlSzNr7U/g1XDZrl07zxpeDe66dGLMmDGSnJxsQqfOMvsbeLVtut63rMDrvebXuQ+dwOsY6H2kS0N0yYZ+SNOAz4EAAgh4CxB4uR8QQMCvwKtrKfVHzDqbq2HF2ZZMZ9V0SYOz7lIr09lgfeBJ1+KWduisoC6T0JDnvd5XlzToOlZdM6tHaTO8GsScXRx81wz7E0y1fg1QGkydXSA0vGnQ0plhfZjK9/CnXq1D1/0Wt6RBlzDoQ17F7YxQWuDV7dQWLVpk1uyWdGid+jCXMwt83333mVM1aOsSEf2wosd3331njIub4T18+LDZTUHH2FlHrQ8Q6oOI+mGmbt26JuzqTLTO0uqhs+K6jtsJvOqns/66htg5vNfwal+0fmc9s56jZdVM1ybrDLTvQ24lBV6nfl0eoQFfwy8HAgggQODlHkAAgTIFvJc0OCfrg2Ovv/66eQGEE3h1+YKGKuehteXLl5u1nBp2NczqGlJ90Etnay+66KKzrqsBTctokNYfY+vMqq5V1Xpr1qxZZuDVEx555BGzk4POuurspf6oXnd70B/xlzUTq+V1jbIGQl2HrGFR19zqjgEadnWPXg14OpOsAV1DnD+BV2db9aER1ZE+AAAD3UlEQVQ1XavrPLSms976wUFnf/UINPDqQ2v6cJuum9YPBbqbgc7a6gNdOkurhz64pbPxGhj1g4fOyuqhQVIfXNNrZmVlGTMNmLpMxXeGV8/XmWIt84tf/MIsHdCZXA3HGnh1NwQdW53R1bHVGXq9BzQoO4FX69cH0XTGVS10ja13gNUdLDRAa71q7zy0pmOhH6j0KCvw6ocKHSs11rXc+hCiLkPhxSRl/vXmBAQqnQAzvJVuyOkwAv4JFBd4taQ+jKRh1/vFE9OnTzchdceOHWbGTwOXhhg9dK2nrjHVQKy7CPgeGjA1mGnQ1a2ldLZVt7VygpqeX9YuDbr8QYOtrm/VJQL6EJc+ZKaByJ/AqzO5ek3dOUBD6ZVXXmlCoQYnfQhLw5Rut6YPT+nyCX8Cr7ZbA+q4cePMrKwTInVNsQboYAKvltFgr23UX3XZgi5L0OUKF1xwgYdWQ6O6ei8p0bXO+iCeBmL9UKABVT+UqE9xgVcfutMAqR9YNFTqMgx9iFE/8OguCGrg7Mygs9XaTz1H19/qoQFWA7F++ND1tbrVnG+AXb16tTHWX/XDjc4+69peZ3a6rMCrbVALfZBPH9bTpQwatG1fTOLf3xDOQgCBiiRA4K1Io0VbEUAAAQQQQAABBAIWIPAGTEYBBBBAAAEEEEAAgYokQOCtSKNFWxFAAAEEEEAAAQQCFiDwBkxGAQQQQAABBBBAAIGKJEDgrUijRVsRQAABBBBAAAEEAhYg8AZMRgEEEEDg/7dbxyQAAAAIBPu3NoPjwwUQ5FwkQIAAAQIlAYe3tJauBAgQIECAAAECt4DDe5MJECBAgAABAgQIlAQc3tJauhIgQIAAAQIECNwCDu9NJkCAAAECBAgQIFAScHhLa+lKgAABAgQIECBwCzi8N5kAAQIECBAgQIBAScDhLa2lKwECBAgQIECAwC3g8N5kAgQIECBAgAABAiUBh7e0lq4ECBAgQIAAAQK3gMN7kwkQIECAAAECBAiUBBze0lq6EiBAgAABAgQI3AIO700mQIAAAQIECBAgUBJweEtr6UqAAAECBAgQIHALOLw3mQABAgQIECBAgEBJwOEtraUrAQIECBAgQIDALeDw3mQCBAgQIECAAAECJQGHt7SWrgQIECBAgAABAreAw3uTCRAgQIAAAQIECJQEHN7SWroSIECAAAECBAjcAg7vTSZAgAABAgQIECBQEnB4S2vpSoAAAQIECBAgcAs4vDeZAAECBAgQIECAQEnA4S2tpSsBAgQIECBAgMAt4PDeZAIECBAgQIAAAQIlAYe3tJauBAgQIECAAAECt8AAJsUdyMvz690AAAAASUVORK5CYII=" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.criterion_plot(res)\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Exploit the structure of your optimization problem\n", - "\n", - "Many estimation problems have a least-squares structure. If so, specialized optimizers that exploit this structure can be much faster than standard optimizers. Likewise, other problems might have, if not a least-squares structure, at least a sum-structure (e.g. likelihood functions) that can also be exploited by suitable optimizers.\n", - "\n", - "If you define your criterion function a bit differently, you can seamlessly switch between least-squares, sum-structure and standard optimizers." - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "metadata": {}, - "outputs": [], - "source": [ - "def general_sphere(params):\n", - " contribs = params**2\n", - " out = {\n", - " # root_contributions are the least squares residuals.\n", - " # if you square and sum them, you get the criterion value\n", - " \"root_contributions\": params,\n", - " # if you sum up contributions, you get the criterion value\n", - " \"contributions\": contribs,\n", - " # this is the standard output\n", - " \"value\": contribs.sum(),\n", - " }\n", - " return out" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0., 0., -0., 0., -0.])" - ] - }, - "execution_count": 20, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=general_sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"pounders\",\n", - ")\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Using and reading persistent logging\n", - "\n", - "For long-running and difficult optimizations, it can be worthwhile to store the progress in a persistent log file. You can do this by providing a path to the `logging` argument:" - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "metadata": {}, - "outputs": [], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " logging=\"my_log.db\",\n", - " log_options={\"if_database_exists\": \"replace\"},\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You can read the entries in the log file (while the optimization is still running or after it has finished) as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "dict_keys(['params', 'criterion', 'runtime'])" - ] - }, - "execution_count": 22, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "reader = em.OptimizeLogReader(\"my_log.db\")\n", - "reader.read_history().keys()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "For more information on what you can do with the log file and LogReader object, check out [the logging tutorial](../how_to_guides/optimization/how_to_use_logging.ipynb)\n", - "\n", - "The persistent log file is always instantly synchronized when the optimizer tries a new parameter vector. This is very handy if an optimization has to be aborted and you want to extract the current status. It is also used by the [estimagic dashboard](../how_to_guides/optimization/how_to_use_the_dashboard.md). " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Customize your optimizer\n", - "\n", - "Most algorithms have a few optional arguments. Examples are convergence criteria or tuning parameters. You can find an overview of supported arguments [here](../how_to_guides/optimization/how_to_specify_algorithm_and_algo_options.md)." - ] - }, - { - "cell_type": "code", - "execution_count": 23, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0., -0., -0., -0., -0.])" - ] - }, - "execution_count": 23, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "algo_options = {\n", - " \"convergence.relative_criterion_tolerance\": 1e-9,\n", - " \"stopping.max_iterations\": 100_000,\n", - "}\n", - "\n", - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " algo_options=algo_options,\n", - ")\n", - "res.params.round(5)" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - }, - "vscode": { - "interpreter": { - "hash": "40d3a090f54c6569ab1632332b64b2c03c39dcf918b08424e98f38b5ae0af88f" - } - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/source/getting_started/index.md b/docs/source/getting_started/index.md deleted file mode 100644 index db85d0714..000000000 --- a/docs/source/getting_started/index.md +++ /dev/null @@ -1,117 +0,0 @@ -# Getting Started - -This section contains quickstart guides for new estimagic users. It can also serve as a -reference for more experienced users. - -`````{grid} 1 2 2 2 ---- -gutter: 3 ---- -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/optimization.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} first_optimization_with_estimagic.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Optimization -``` - -Learn numerical optimization with estimagic. - -```` - -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/differentiation.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} first_derivative_with_estimagic.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Differentiation -``` - -Learn numerical differentiation with estimagic. - -```` - -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/bullseye.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} estimation/index.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Estimation -``` - -Learn maximum likelihood and methods of simulated moments estimation with estimagic. - -```` - -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/installation.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} installation.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Installation -``` - -Installation instructions for estimagic and optional dependencies. - -```` - -````{grid-item-card} -:text-align: center -:columns: 12 -:img-top: ../_static/images/video.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} ../videos.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Videos -``` - -Collection of tutorials, talks, and screencasts on estimagic. - -```` - -````` - -```{toctree} ---- -hidden: true -maxdepth: 1 ---- -installation -first_optimization_with_estimagic -estimation/index -first_derivative_with_estimagic -``` diff --git a/docs/source/getting_started/installation.md b/docs/source/getting_started/installation.md deleted file mode 100644 index 52927d979..000000000 --- a/docs/source/getting_started/installation.md +++ /dev/null @@ -1,61 +0,0 @@ -# Installation - -## Basic installation - -The package can be installed via conda. To do so, type the following commands in a -terminal or shell: - -``` -conda config --add channels conda-forge -``` - -``` -conda install estimagic -``` - -The first line adds conda-forge to your conda channels. This is necessary for conda to -find all dependencies of estimagic. The second line installs estimagic and its mandatory -dependencies. - -## Installing optional dependencies - -Only `scipy` is a mandatory dependency of estimagic. Other algorithms become available -if you install more packages. We make this optional because most of the time you will -use at least one additional package, but only very rarely will you need all of them. - -For an overview of all optimizers and the packages you need to install to enable them, -see {ref}`list_of_algorithms`. - -To enable all algorithms at once, do the following: - -``` -conda install nlopt -``` - -``` -pip install Py-BOBYQA -``` - -``` -pip install DFO-LS -``` - -``` -conda install petsc4py -``` - -*Note*: `` `petsc4py` `` is not available on Windows. - -``` -conda install cyipopt -``` - -``` -conda install pygmo -``` - -``` -pip install fides>=0.7.4 -``` - -*Note*: Make sure you have at least 0.7.1. diff --git a/docs/source/how_to_guides/optimization/how_to_pick_an_optimizer.ipynb b/docs/source/how_to/how_to_algorithm_selection.ipynb similarity index 73% rename from docs/source/how_to_guides/optimization/how_to_pick_an_optimizer.ipynb rename to docs/source/how_to/how_to_algorithm_selection.ipynb index e141a6781..b91a7e8f3 100644 --- a/docs/source/how_to_guides/optimization/how_to_pick_an_optimizer.ipynb +++ b/docs/source/how_to/how_to_algorithm_selection.ipynb @@ -4,6 +4,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "(how-to-select-algorithms)=\n", + "\n", "# Which optimizer to use\n", "\n", "This is a very very very short and oversimplifying guide on selecting an optimization algorithm based on a minimum of information. \n", @@ -27,26 +29,23 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "import estimagic as em\n", - "import numpy as np" + "import numpy as np\n", + "import optimagic as om" ] }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ + "@om.mark.least_squares\n", "def sphere(params):\n", - " out = {\n", - " \"value\": params @ params,\n", - " \"root_contributions\": params,\n", - " }\n", - " return out\n", + " return params\n", "\n", "\n", "def sphere_gradient(params):\n", @@ -62,33 +61,22 @@ "source": [ "## Differentiable criterion function\n", "\n", - "Use `scipy_lbfsgsb` as optimizer and provide the closed form derivative if you can. If you do not provide a derivative, estimagic will calculate it numerically. However, this is less precise and slower. " + "Use `scipy_lbfsgsb` as optimizer and provide the closed form derivative if you can. If you do not provide a derivative, optimagic will calculate it numerically. However, this is less precise and slower. " ] }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "3" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", + "res = om.minimize(\n", + " fun=sphere,\n", " params=start_params,\n", " algorithm=\"scipy_lbfgsb\",\n", - " derivative=sphere_gradient,\n", + " jac=sphere_gradient,\n", ")\n", - "res.n_criterion_evaluations" + "res.n_fun_evals" ] }, { @@ -120,27 +108,16 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "33" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", + "res = om.minimize(\n", + " fun=sphere,\n", " params=start_params,\n", " algorithm=\"nag_pybobyqa\",\n", ")\n", - "res.n_criterion_evaluations" + "res.n_fun_evals" ] }, { @@ -159,27 +136,16 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "9" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", + "res = om.minimize(\n", + " fun=sphere,\n", " params=start_params,\n", " algorithm=\"nag_dfols\",\n", ")\n", - "res.n_criterion_evaluations" + "res.n_fun_evals" ] } ], @@ -199,7 +165,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.8" + "version": "3.10.14" } }, "nbformat": 4, diff --git a/docs/source/how_to/how_to_benchmarking.ipynb b/docs/source/how_to/how_to_benchmarking.ipynb new file mode 100644 index 000000000..f0b3ddb1c --- /dev/null +++ b/docs/source/how_to/how_to_benchmarking.ipynb @@ -0,0 +1,346 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": {}, + "source": [ + "# How to Benchmark Optimization Algorithms\n", + "\n", + "Benchmarking optimization algorithms is an important step when developing a new algorithm or when searching for an algorithm that is good at solving a particular problem. \n", + "\n", + "In general, benchmarking constists of the following steps:\n", + "\n", + "1. Define the test problems (or get pre-implemented ones)\n", + "2. Define the optimization algorithms and the tuning parameters you want to try\n", + "3. Run the benchmark\n", + "4. Plot the results\n", + "\n", + "optimagic helps you with all of these steps!" + ] + }, + { + "cell_type": "markdown", + "id": "1", + "metadata": {}, + "source": [ + "## 1. Get Test Problems\n", + "\n", + "optimagic includes the problems of [Moré and Wild (2009)](https://doi.org/10.1137/080724083) as well as [Cartis and Roberts](https://arxiv.org/abs/1710.11005).\n", + "\n", + "Each problem consist of the `inputs` (the criterion function and the start parameters) and the `solution` (the optimal parameters and criterion value) and optionally provides more information.\n", + "\n", + "Below we load a subset of the Moré and Wild problems and look at one particular Rosenbrock problem that has difficult start parameters." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2", + "metadata": {}, + "outputs": [], + "source": [ + "import optimagic as om" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3", + "metadata": {}, + "outputs": [], + "source": [ + "problems = om.get_benchmark_problems(\"example\")" + ] + }, + { + "cell_type": "markdown", + "id": "4", + "metadata": {}, + "source": [ + "## 2. Specify the Optimizers\n", + "\n", + "To select optimizers you want to benchmark on the set of problems, you can simply specify them as a list. Advanced examples - that do not only compare algorithms but also vary the `algo_options` - can be found below. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "5", + "metadata": {}, + "outputs": [], + "source": [ + "optimizers = [\n", + " \"nag_dfols\",\n", + " \"scipy_neldermead\",\n", + " \"scipy_truncated_newton\",\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "6", + "metadata": {}, + "source": [ + "## 3. Run the Benchmark\n", + "\n", + "Once you have your problems and your optimizers set up, you can simply use `run_benchmark`. The results are a dictionary with one entry for each (problem, algorithm) combination. Each entry not only saves the solution but also the history of the algorithm's criterion and parameter history. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7", + "metadata": {}, + "outputs": [], + "source": [ + "results = om.run_benchmark(\n", + " problems,\n", + " optimizers,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "8", + "metadata": {}, + "source": [ + "## 4a. Profile plots\n", + "\n", + "**Profile Plots** compare optimizers over a whole problem set. \n", + "\n", + "The literature distinguishes **data profiles** and **performance profiles**. Data profiles use a normalized runtime measure whereas performance profiles use an absolute one. The profile plot does not normalize runtime by default. To do this, simply set `normalize_runtime` to True. For background information, check [Moré and Wild (2009)](https://doi.org/10.1137/080724083). " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.profile_plot(\n", + " problems=problems,\n", + " results=results,\n", + ")\n", + "\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "10", + "metadata": {}, + "source": [ + "The x axis shows runtime per problem. The y axis shows the share of problems each algorithm solved within that runtime. Thus, higher and further to the left values are desirable. Higher means more problems were solved and further to the left means, the algorithm found the solutions earlier. \n", + "\n", + "You can choose:\n", + "\n", + "- whether to use `n_evaluations` or `walltime` as **`runtime_measure`**\n", + "- whether to normalize runtime such that the runtime of each problem is shown as a multiple of the fastest algorithm on that problem\n", + "- how to determine when an evaluation is close enough to the optimum to be counted as converged. Convergence is always based on some measure of distance between the true solution and the solution found by an optimizer. Whether distiance is measured in parameter space, function space, or a combination of both can be specified. \n", + "\n", + "Below, we consider a problem to be solved if the distance between the parameters found by the optimizer and the true solution parameters are at most 0.1% of the distance between the start parameters and true solution parameters. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "11", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.profile_plot(\n", + " problems=problems,\n", + " results=results,\n", + " runtime_measure=\"n_evaluations\",\n", + " stopping_criterion=\"x\",\n", + " x_precision=0.001,\n", + ")\n", + "\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "12", + "metadata": {}, + "source": [ + "## 4b. Convergence plots\n", + "\n", + "**Convergence Plots** look at particular problems and show the convergence of each optimizer on each problem. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "13", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.convergence_plot(\n", + " problems=problems,\n", + " results=results,\n", + " n_cols=2,\n", + " problem_subset=[\"rosenbrock_good_start\", \"box_3d\"],\n", + ")\n", + "\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "14", + "metadata": {}, + "source": [ + "The further to the left and the lower the curve of an algorithm, the better that algorithm performed.\n", + "\n", + "Often we are more interested in how close each algorithm got to the true solution in parameter space, not in criterion space as above. For this. we simply set the **`distance_measure`** to `parameter_space`. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "15", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.convergence_plot(\n", + " problems=problems,\n", + " results=results,\n", + " n_cols=2,\n", + " problem_subset=[\"rosenbrock_good_start\", \"box_3d\"],\n", + " distance_measure=\"parameter_distance\",\n", + " stopping_criterion=\"x\",\n", + ")\n", + "\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "16", + "metadata": {}, + "source": [ + "## 5a. Convergence report\n", + "\n", + "The **Convergence Report** shows for each problem and optimizer which problems the optimizer solved successfully, failed to do so, or where it stopped with an error. The respective strings are \"success\", \"failed\", or \"error\".\n", + "Moreover, the last column of the ```pd.DataFrame``` displays the number of dimensions of the benchmark problem." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "17", + "metadata": {}, + "outputs": [], + "source": [ + "df = om.convergence_report(\n", + " problems=problems,\n", + " results=results,\n", + " stopping_criterion=\"y\",\n", + " x_precision=1e-4,\n", + " y_precision=1e-4,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "18", + "metadata": {}, + "outputs": [], + "source": [ + "df" + ] + }, + { + "cell_type": "markdown", + "id": "19", + "metadata": {}, + "source": [ + "## 5b. Rank report¶\n", + "\n", + "The **Rank Report** shows the ranks of the algorithms for each problem; where 0 means the algorithm was the fastest on a given benchmark problem, 1 means it was the second fastest and so on. If an algorithm did not converge on a problem, the value is \"failed\". If an algorithm did encounter an error during optimization, the value is \"error\"." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "20", + "metadata": {}, + "outputs": [], + "source": [ + "df = om.rank_report(\n", + " problems=problems,\n", + " results=results,\n", + " runtime_measure=\"n_evaluations\",\n", + " stopping_criterion=\"y\",\n", + " x_precision=1e-4,\n", + " y_precision=1e-4,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "21", + "metadata": {}, + "outputs": [], + "source": [ + "df" + ] + }, + { + "cell_type": "markdown", + "id": "22", + "metadata": {}, + "source": [ + "## 5b. Traceback report¶\n", + "\n", + "The **Traceback Report** shows the tracebacks returned by the optimizers if they encountered an error during optimization. The resulting ```pd.DataFrame``` is empty if none of the optimizers terminated with an error, as in the example below." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "23", + "metadata": {}, + "outputs": [], + "source": [ + "df = om.traceback_report(problems=problems, results=results)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "24", + "metadata": {}, + "outputs": [], + "source": [ + "df" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/how_to/how_to_bounds.ipynb b/docs/source/how_to/how_to_bounds.ipynb new file mode 100644 index 000000000..f5dcae403 --- /dev/null +++ b/docs/source/how_to/how_to_bounds.ipynb @@ -0,0 +1,261 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": {}, + "source": [ + "(how-to-bounds)=\n", + "\n", + "# How to specify bounds\n", + "\n", + "## Constraints vs bounds \n", + "\n", + "optimagic distinguishes between bounds and constraints. Bounds are lower and upper bounds for parameters. In the literature, they are sometimes called box constraints. Examples for general constraints are linear constraints, probability constraints, or nonlinear constraints. You can find out more about general constraints in the next section on [How to specify constraints](how_to_constraints.md)." + ] + }, + { + "cell_type": "markdown", + "id": "1", + "metadata": {}, + "source": [ + "## Example objective function\n", + "\n", + "Let’s again look at the sphere function:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2", + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3", + "metadata": {}, + "outputs": [], + "source": [ + "def fun(x):\n", + " return x @ x" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(fun=fun, params=np.arange(3), algorithm=\"scipy_lbfgsb\")\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "id": "5", + "metadata": {}, + "source": [ + "## Array params\n", + "\n", + "For params that are a `numpy.ndarray`, one can specify the lower and/or upper-bounds as an array of the same length.\n", + "\n", + "**Lower bounds**" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=fun,\n", + " params=np.arange(3),\n", + " bounds=om.Bounds(lower=np.ones(3)),\n", + " algorithm=\"scipy_lbfgsb\",\n", + ")\n", + "res.params" + ] + }, + { + "cell_type": "markdown", + "id": "7", + "metadata": {}, + "source": [ + "**Lower & upper-bounds**" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=fun,\n", + " params=np.arange(3),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " bounds=om.Bounds(\n", + " lower=np.array([-2, -np.inf, 1]),\n", + " upper=np.array([-1, np.inf, np.inf]),\n", + " ),\n", + ")\n", + "res.params" + ] + }, + { + "cell_type": "markdown", + "id": "9", + "metadata": {}, + "source": [ + "## Pytree params\n", + "\n", + "Now let's look at a case where params is a more general pytree. We also update the sphere function by adding an intercept. Since the criterion always decreases when decreasing the intercept, there is no unrestricted solution. Lets fix a lower bound only for the intercept." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "10", + "metadata": {}, + "outputs": [], + "source": [ + "params = {\"x\": np.arange(3), \"intercept\": 3}\n", + "\n", + "\n", + "def fun(params):\n", + " return params[\"x\"] @ params[\"x\"] + params[\"intercept\"]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "11", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=fun,\n", + " params=params,\n", + " algorithm=\"scipy_lbfgsb\",\n", + " bounds=om.Bounds(lower={\"intercept\": -2}),\n", + ")\n", + "res.params" + ] + }, + { + "cell_type": "markdown", + "id": "12", + "metadata": {}, + "source": [ + "optimagic tries to match the user provided bounds with the structure of params. This allows you to specify bounds for subtrees of params. In case your subtree specification results in an unidentified matching, optimagic will tell you so with a `InvalidBoundsError`. " + ] + }, + { + "cell_type": "markdown", + "id": "13", + "metadata": {}, + "source": [ + "## params data frame\n", + "\n", + "It often makes sense to specify your parameters in a `pandas.DataFrame`, where you can utilize the multiindex for parameter naming. In this case, you can specify bounds as extra columns `lower_bound` and `upper_bound`.\n", + "\n", + "> **Note**\n", + "> The columns are called `*_bound` instead of `*_bounds` like the argument passed to `minimize` or `maximize`. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "14", + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "\n", + "params = pd.DataFrame(\n", + " {\"value\": [0, 1, 2, 3], \"lower_bound\": [0, 1, 1, -2]},\n", + " index=pd.MultiIndex.from_tuples([(\"x\", k) for k in range(3)] + [(\"intercept\", 0)]),\n", + ")\n", + "params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "15", + "metadata": {}, + "outputs": [], + "source": [ + "def fun(params):\n", + " x = params.loc[\"x\"][\"value\"].to_numpy()\n", + " intercept = params.loc[\"intercept\"][\"value\"].iloc[0]\n", + " value = x @ x + intercept\n", + " return float(value)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "16", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun,\n", + " params=params,\n", + " algorithm=\"scipy_lbfgsb\",\n", + ")\n", + "res.params" + ] + }, + { + "cell_type": "markdown", + "id": "17", + "metadata": {}, + "source": [ + "## Coming from scipy" + ] + }, + { + "cell_type": "markdown", + "id": "18", + "metadata": {}, + "source": [ + "If `params` is a flat numpy array, you can also provide bounds in any format that \n", + "is supported by [`scipy.optimize.minimize`](\n", + "https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html). " + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/how_to_guides/optimization/how_to_specify_constraints.md b/docs/source/how_to/how_to_constraints.md similarity index 55% rename from docs/source/how_to_guides/optimization/how_to_specify_constraints.md rename to docs/source/how_to/how_to_constraints.md index 82b73ae08..20ab1b745 100644 --- a/docs/source/how_to_guides/optimization/how_to_specify_constraints.md +++ b/docs/source/how_to/how_to_constraints.md @@ -4,7 +4,7 @@ ## Constraints vs bounds -Estimagic distinguishes between bounds and constraints. Bounds are lower and upper +optimagic distinguishes between bounds and constraints. Bounds are lower and upper bounds for parameters. In the literature, they are sometimes called box constraints. Bounds are specified as `lower_bounds` and `upper_bounds` argument to `maximize` and `minimize`. @@ -26,15 +26,15 @@ parameters) can even be used with optimizers that do not support bounds. ## Example criterion function Let's look at a variation of the sphere function to illustrate what kinds of constraints -you can impose and how you specify them in estimagic: +you can impose and how you specify them in optimagic: ```{eval-rst} .. code-block:: python >>> import numpy as np - >>> import estimagic as em - >>> def criterion(params): + >>> import optimagic as om + >>> def fun(params): ... offset = np.linspace(1, 0, len(params)) ... x = params - offset ... return x @ x @@ -47,11 +47,11 @@ The unconstrained optimum of a six-dimensional version of this problem is: .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.array([2.5, 1, 1, 1, 1, -2.5]), ... algorithm="scipy_lbfgsb", - ... ) + ... ) >>> res.params.round(3) array([1. , 0.8, 0.6, 0.4, 0.2, 0. ]) @@ -63,9 +63,9 @@ criterion function in a additively separable way. ## Types of constraints Below, we show a very simple example of each type of constraint implemented in -estimagic. For each constraint, we will select a subset of the parameters on which the -constraint is imposed via the "loc" key. Generalizations for selecting subsets of -`params` that are not a flat numpy array are explained in the next section. +optimagic. For each constraint, we will select a subset of the parameters on which the +constraint is imposed via the `selector` argument, which is a function that takes in the +full parameter vector and returns the subset of parameters that should be constrained. ```{eval-rst} .. dropdown:: fixed @@ -77,12 +77,14 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.array([2.5, 1, 1, 1, 1, -2.5]), ... algorithm="scipy_lbfgsb", - ... constraints={"loc": [0, 5], "type": "fixed"}, - ... ) + ... constraints=om.FixedConstraint( + ... selector=lambda params: params[[0, 5]] + ... ), + ... ) Looking at the optimization result, we get: @@ -94,7 +96,7 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o ``` -````{eval-rst} +```{eval-rst} .. dropdown:: increasing In our unconstrained example, the optimal parameters are decreasing from left to @@ -104,19 +106,21 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.array([1, 1, 1, 1, 1, 1]), ... algorithm="scipy_lbfgsb", - ... constraints={"loc": [1, 2, 3], "type": "increasing"}, - ... ) + ... constraints=om.IncreasingConstraint( + ... selector=lambda params: params[[1, 2, 3]] + ... ), + ... ) - Imposing the constraint on positions ``"loc": [1, 2, 3]``` means that the parameter value + Imposing the constraint on positions ``params[[1, 2, 3]]`` means that the parameter value at index position ``2`` has to be (weakly) greater than the value at position ``1``. Likewise, the parameter value at index position ``3`` has to be (weakly) greater than the value at position ``2``. Hence, imposing an increasing constraint with - only one entry in "loc" has no effect. We need to specify at least two parameters to make + only one selected parameter has no effect. We need to specify at least two parameters to make a meaningful *relative* comparison. Note that the increasing constraint affect all three parameters, i.e. ``params[1]``, ``params[2]``, and ``params[3]`` because the optimal parameters in the unconstrained case @@ -130,9 +134,9 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o Which is indeed the correct constrained optimum. Increasing constraints are only compatible with optimizers that support bounds. -```` +``` -````{eval-rst} +```{eval-rst} .. dropdown:: decreasing In our unconstrained example, the optimal parameters are decreasing from left to @@ -143,18 +147,20 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.array([1, 1, 1, 1, 1, 1]), ... algorithm="scipy_lbfgsb", - ... constraints={"loc": [3, 0, 4], "type": "decreasing"}, - ... ) + ... constraints=om.DecreasingConstraint( + ... selector=lambda params: params[[3, 0, 4]] + ... ), + ... ) - Imposing the constraint on positions ``"loc": [3, 0, 4]``` means that the parameter value + Imposing the constraint on positions ``params[[3, 0, 4]]`` means that the parameter value at index position ``0`` has to be (weakly) smaller than the value at position ``3``. Likewise, the parameter value at index position ``4`` has to be (weakly) smaller than the value at position ``0``. Hence, imposing a decreasing constraint with - only one entry in "loc" has no effect. We need to specify at least two parameters to make + only one selected parameter has no effect. We need to specify at least two parameters to make a meaningful *relative* comparison. Note that the decreasing constraint should have no effect on ``params[4]`` because it is smaller than the other two anyways in the unconstrained optimum, but it will change @@ -165,7 +171,7 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o Which is the correct optimum. Decreasing constraints are only compatible with optimizers that support bounds. -```` +``` ```{eval-rst} .. dropdown:: equality @@ -175,12 +181,14 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.array([1, 1, 1, 1, 1, 1]), ... algorithm="scipy_lbfgsb", - ... constraints={"loc": [0, 5], "type": "equality"}, - ... ) + ... constraints=om.EqualityConstraint( + ... selector=lambda params: params[[0, 5]] + ... ), + ... ) This yields: @@ -200,12 +208,17 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.array([1, 1, 1, 1, 1, 1]), ... algorithm="scipy_lbfgsb", - ... constraints={"locs": [[0, 1], [2, 3]], "type": "pairwise_equality"}, - ... ) + ... constraints=om.PairwiseEqualityConstraint( + ... selectors=[ + ... lambda params: params[[0, 1]], + ... lambda params: params[[2, 3]] + ... ], + ... ), + ... ) @@ -225,12 +238,14 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.array([0.3, 0.2, 0.25, 0.25, 1, 1]), ... algorithm="scipy_lbfgsb", - ... constraints={"loc": [0, 1, 2, 3], "type": "probability"}, - ... ) + ... constraints=om.ProbabilityConstraint( + ... selector=lambda params: params[:4] + ... ), + ... ) This yields again the correct result: @@ -256,12 +271,14 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.ones(6), ... algorithm="scipy_lbfgsb", - ... constraints={"loc": [0, 1, 2], "type": "covariance"}, - ... ) + ... constraints=om.FlatCovConstraint( + ... selector=lambda params: params[:3] + ... ), + ... ) This yields the same solution as an unconstrained estimation because the constraint is not binding: @@ -269,12 +286,12 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o >>> res.params.round(3) array([ 1.006, 0.784, 0.61 , 0.4 , 0.2 , -0. ]) - We can now use one of estimagic's utility functions to actually build the covariance + We can now use one of optimagic's utility functions to actually build the covariance matrix out of the first three parameters: .. code-block:: python - >>> from estimagic.utilities import cov_params_to_matrix + >>> from optimagic.utilities import cov_params_to_matrix >>> cov_params_to_matrix(res.params[:3]).round(2) # doctest: +NORMALIZE_WHITESPACE array([[1.01, 0.78], [0.78, 0.61]]) @@ -294,12 +311,14 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.ones(6), ... algorithm="scipy_lbfgsb", - ... constraints={"loc": [0, 1, 2], "type": "sdcorr"}, - ... ) + ... constraints=om.FlatSDCorrConstraint( + ... selector=lambda params: params[:3] + ... ), + ... ) This yields the same solution as an unconstrained estimation because the constraint @@ -308,12 +327,12 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o >>> res.params.round(3) array([ 1. , 0.8, 0.6, 0.4, 0.2, -0. ]) - We can now use one of estimagic's utility functions to actually build the standard + We can now use one of optimagic's utility functions to actually build the standard deviations and the correlation matrix: .. code-block:: python - >>> from estimagic.utilities import sdcorr_params_to_sds_and_corr + >>> from optimagic.utilities import sdcorr_params_to_sds_and_corr >>> sd, corr = sdcorr_params_to_sds_and_corr(res.params[:3]) >>> sd.round(2) array([1. , 0.8]) @@ -341,17 +360,16 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.ones(6), ... algorithm="scipy_lbfgsb", - ... constraints={ - ... "loc": [0, 1, 2, 3], - ... "type": "linear", - ... "lower_bound": 0.95, - ... "weights": 0.25, - ... }, - ... ) + ... constraints=om.LinearConstraint( + ... selector=lambda params: params[:4], + ... lower_bound=0.95, + ... weights=0.25, + ... ), + ... ) This yields: @@ -387,17 +405,16 @@ constraint is imposed via the "loc" key. Generalizations for selecting subsets o .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.ones(6), ... algorithm="scipy_slsqp", - ... constraints={ - ... "type": "nonlinear", - ... "selector": lambda x: x[:-1], - ... "func": lambda x: np.prod(x), - ... "value": 1.0, - ... }, - ... ) + ... constraints=om.NonlinearConstraint( + ... selector=lambda params: params[:-1], + ... func=lambda x: np.prod(x), + ... value=1.0, + ... ), + ... ) This yields: @@ -421,15 +438,19 @@ constraints simultaneously, simple pass in a list of constraints. For example: .. code-block:: python - >>> res = em.minimize( - ... criterion=criterion, + >>> res = om.minimize( + ... fun=fun, ... params=np.ones(6), ... algorithm="scipy_lbfgsb", ... constraints=[ - ... {"loc": [0, 1], "type": "equality"}, - ... {"loc": [2, 3, 4], "type": "linear", "weights": 1, "value": 3}, + ... om.EqualityConstraint(selector=lambda params: params[:2]), + ... om.LinearConstraint( + ... selector=lambda params: params[2:5], + ... weights=1, + ... value=3, + ... ), ... ], - ... ) + ... ) This yields: @@ -443,156 +464,49 @@ get a descriptive error message if your constraints are not compatible. ## How to select the parameters? -All the above examples use a `"loc"` entry in the constraint dictionary to select the -subset of `params` on which the constraint is imposed. This is just one out of several -ways to do it. Which methods are available also depends on whether your parameters are a -numpy array, DataFrame, or general pytree. +The parameters can be selected via a `selector` function. This function takes in the +full parameter vector and returns the subset of parameters that should be constrained. -```{eval-rst} -+---------------+---------------+----------------+---------------+ -| | loc | query | selector | -+---------------+---------------+----------------+---------------+ -| 1d-array | ✅ (positions)| ❌ | ✅ | -+---------------+---------------+----------------+---------------+ -| DataFrame | ✅ (labels) | ✅ | ✅ | -+---------------+---------------+----------------+---------------+ -| Pytree | ❌ | ❌ | ✅ | -+---------------+---------------+----------------+---------------+ -``` - -Below we show how to use each of these selection methods in simple examples - -```{eval-rst} -.. dropdown:: loc - - In all the examples above, we imposed constraints where our params are - a numpy array and the ``loc`` method is used to select the constraint parameters. - So now, we turn to DataFrame params. - - Let's assume our ``params`` are a DataFrame with a two level index. The names of - the index levels are ``category`` and ``name``. Something like this could, for - example, be the params of an Ordered Logit model. - - +----------------+---------------+----------------+ - | | | **value** | - +----------------+---------------+----------------+ - | **category** | **name** | | - +----------------+---------------+----------------+ - | **betas** | **a** | 0.95 | - +----------------+---------------+----------------+ - | **betas** | **b** | 0.9 | - +----------------+---------------+----------------+ - | **cutoffs** | **a** | 0 | - +----------------+---------------+----------------+ - | **cutoffs** | **b** | 0.4 | - +----------------+---------------+----------------+ - - Now, let;s impose the constraint that the cutoffs (i.e. the last two parameters) - are increasing. - - .. code-block:: python - - res = em.minimize( - criterion=some_criterion, - params=params, - algorithm="scipy_lbfgsb", - constraints={"loc": "cutoffs", "type": "increasing"}, - ) - - The value corresponding to ``"loc"`` can be anything you would pass to pandas' - ``DataFrame.loc`` method, too. So, if you know pandas, imposing constraints in estimagic - via ``"loc"`` should feel already familiar. - Imposing constraints this way can be extremely powerful - if you have a well designed MultiIndex, as you can easily select groups of parameters - or single paramaters. +Let's assume we have defined parameters in a nested dictionary: +```python +params = {"a": np.ones(2), "b": {"c": 3, "d": pd.Series([4, 5])}} ``` -```{eval-rst} -.. dropdown:: query - - Let's assume our ``params`` are a DataFrame with a two level index. The names of - the index levels are ``category`` and ``name``. Something like this could for - example be the params of an Ordered Logit model. - - +----------------+---------------+----------------+ - | | | **value** | - +----------------+---------------+----------------+ - | **category** | **name** | | - +----------------+---------------+----------------+ - | **betas** | **a** | 0.95 | - +----------------+---------------+----------------+ - | **betas** | **b** | 0.9 | - +----------------+---------------+----------------+ - | **cutoffs** | **a** | 0 | - +----------------+---------------+----------------+ - | **cutoffs** | **b** | 0.4 | - +----------------+---------------+----------------+ - - This time, we want to fix all betas as well as all parameters where the second index - level is equal to ``"a"``. If we wanted to do that using ``loc``, we would have to - type out three index tuples. So let's do that with a query instead: - - .. code-block:: python - - res = em.minimize( - criterion=some_criterion, - params=params, - algorithm="scipy_lbfgsb", - constraints={"query": "category == 'betas' | name == 'a'", "type": "fixed"}, - ) +It is probably not a good idea to use a nested dictionary for so few parameters, but +let's ignore that. - The value corresponding to ``"query"`` can be anything you would pass to pandas' - ``DataFrame.query`` method, too. So, if you know pandas, imposing constraints in estimagic - via ``"query"`` should feel just the same. +Now assume we want to fix the parameters in the pandas Series at their start values. We +can do so as follows: +```python +res = om.minimize( + fun=some_fun, + params=params, + algorithm="scipy_lbfgsb", + constraints=om.FixedConstraint(selector=lambda params: params["b"]["d"]), +) ``` -```{eval-rst} -.. dropdown:: selector - - Using ``selector`` to select the parameters is the most general way and works for - all params. Let's assume we have defined parameters in a nested dictionary: - - .. code-block:: python - - params = {"a": np.ones(2), "b": {"c": 3, "d": pd.Series([4, 5])}} - - It is probably not a good idea to use a nested dictionary for so few parameters, but - let's ignore that. +I.e. the value corresponding to `selector` is a python function that takes the full +`params` and returns a subset. The selected subset does not have to be a numpy array, it +can be an arbitrary pytree. - Now assume we want to fix the parameters in the pandas Series at their start - values. We can do so as follows: - - .. code-block:: python - - res = em.minimize( - criterion=some_criterion, - params=params, - algorithm="scipy_lbfgsb", - constraints={"selector": lambda params: params["b"]["d"], "type": "fixed"}, - ) - - I.e. the value corresponding to ``selector`` is a python function that takes the - full ``params`` and returns a subset. The selected subset does not have to be a - numpy array, it can be an arbitrary pytree. - - Using lambda functions if often convenient, but we could have just as well defined - the selector function using def. - - .. code-block:: python +Using lambda functions if often convenient, but we could have just as well defined the +selector function using def. - def my_selector(params): - return params["b"]["d"] +```python +def my_selector(params): + return params["b"]["d"] - res = em.minimize( - criterion=some_criterion, - params=params, - algorithm="scipy_lbfgsb", - constraints={"selector": my_selector, "type": "fixed"}, - ) +res = om.minimize( + fun=some_fun, + params=params, + algorithm="scipy_lbfgsb", + constraints=om.FixedConstraint(selector=my_selector), +) ``` -[here]: ../../explanations/optimization/implementation_of_constraints.md -[this tutorial]: ../../getting_started/first_optimization_with_estimagic.ipynb +[here]: ../../explanation/implementation_of_constraints.md +[this tutorial]: ../tutorials/optimization_overview.ipynb diff --git a/docs/source/how_to/how_to_criterion_function.ipynb b/docs/source/how_to/how_to_criterion_function.ipynb new file mode 100644 index 000000000..98afbf877 --- /dev/null +++ b/docs/source/how_to/how_to_criterion_function.ipynb @@ -0,0 +1,228 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "(how-to-fun)=\n", + "\n", + "# How to write objective functions\n", + "\n", + "optimagic is very flexible when it comes to the objective function and its derivatives. \n", + "In this how-to guide we start with simple examples, that would also work with \n", + "scipy.optimize before we show advanced options and their advantages. \n", + "\n", + "## The simplest case\n", + "\n", + "In the simplest case, `fun` maps a numpy array into a scalar objective value. The name\n", + "of first argument of `fun` is arbitrary. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om\n", + "\n", + "\n", + "def sphere(x):\n", + " return x @ x\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(3),\n", + " algorithm=\"scipy_lbfgsb\",\n", + ")\n", + "res.params.round(6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## More flexible `params`\n", + "\n", + "In all but the most simple problems, a flat numpy array is not ideal to keep track of \n", + "all the different parameters one wants to optimize over. Therefore, optimagic accepts \n", + "objective functions that work with other parameter formats. Below we show a simple \n", + "example. More examples can be found [here](how_to_start_parameters.md).\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def dict_fun(x):\n", + " return x[\"a\"] ** 2 + x[\"b\"] ** 4\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=dict_fun,\n", + " params={\"a\": 1, \"b\": 2},\n", + " algorithm=\"scipy_lbfgsb\",\n", + ")\n", + "\n", + "res.params" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The important thing is that the `params` provided to `minimize` need to have the format \n", + "that is expected by the objective function.\n", + "\n", + "## Functions with additional arguments\n", + "\n", + "In many applications, the objective function takes more than `params` as argument. \n", + "This can be achieved via `fun_kwargs`. Take the following simplified example:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def shifted_sphere(x, offset):\n", + " return (x - offset) @ (x - offset)\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=shifted_sphere,\n", + " params=np.arange(3),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " fun_kwargs={\"offset\": np.ones(3)},\n", + ")\n", + "res.params" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "`fun_kwargs` is a dictionary with keyword arguments for `fun`. There is no constraint\n", + "on the number or names of those arguments." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Least-Squares problems\n", + "\n", + "Many estimation problems have a least-squares structure. If so, specialized optimizers that exploit this structure can be much faster than standard optimizers. The `sphere` function from above is the simplest possible least-squarse problem you could imagine: the least-squares residuals are just the params. \n", + "\n", + "To use least-squares optimizers in optimagic, you need to mark your function with \n", + "a decorator and return the least-squares residuals instead of the aggregated function value. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "@om.mark.least_squares\n", + "def ls_sphere(params):\n", + " return params\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=ls_sphere,\n", + " params=np.arange(3),\n", + " algorithm=\"pounders\",\n", + ")\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Any least-squares optimization problem is also a standard optimization problem. You \n", + "can therefore optimize least-squares functions with scalar optimizers as well:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=ls_sphere,\n", + " params=np.arange(3),\n", + " algorithm=\"scipy_lbfgsb\",\n", + ")\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Returning additional information\n", + "\n", + "You can return additional information such as intermediate results, debugging information, etc. in your objective function. This information will be stored in a database if you use [logging](how_to_logging.ipynb).\n", + "\n", + "To do so, you need to return a `FunctionValue` object." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere_with_info(x):\n", + " return om.FunctionValue(value=x @ x, info={\"avg\": x.mean()})\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=sphere_with_info,\n", + " params=np.arange(3),\n", + " algorithm=\"scipy_lbfgsb\",\n", + ")\n", + "\n", + "res.params.round(6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The `info` can be an arbitrary dictionary. In the oversimplified example we returned the \n", + "mean of the parameters, which could have been recovered from the params history that \n", + "is collected anyways but in real applications this feature can be helpful. " + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "optimagic", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/source/how_to/how_to_derivatives.ipynb b/docs/source/how_to/how_to_derivatives.ipynb new file mode 100644 index 000000000..6e079f508 --- /dev/null +++ b/docs/source/how_to/how_to_derivatives.ipynb @@ -0,0 +1,279 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "(how-to-jac)=\n", + "\n", + "# How to speed up your optimization using derivatives\n", + "\n", + "Many optimization algorithms use derivatives to find good search directions. If you \n", + "use a derivative based optimizer but do not provide derivatives of your objective \n", + "function, optimagic calculates a numerical derivative for you. \n", + "\n", + "While this numerical derivative is usually precise enough to find good search directions \n", + "it requires `n + 1` evaluations of the objective function (where `n` is the number of \n", + "free parameters). For large `n` this becomes very slow.\n", + "\n", + "This how-to guide shows how you can speed up your optimization by parallelizing \n", + "numerical derivatives or by providing closed form derivatives. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Parallel numerical derivatives\n", + "\n", + "If you have a computer with a few idle cores, the easiest way to speed up your\n", + "optimization with a gradient based optimizer is to calculate numerical derivatives \n", + "in parallel:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om\n", + "\n", + "\n", + "def sphere(x):\n", + " return x @ x\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " numdiff_options=om.NumdiffOptions(n_cores=6),\n", + ")\n", + "res.params.round(6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Of course, for this super fast objective function, parallelizing will not yield an actual \n", + "speedup. But if your objective function takes 100 milliseconds or longer to evaluate, \n", + "you can parallelize efficiently to up to `n + 1` cores. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Custom derivatives\n", + "\n", + "If you don't want to solve your speed problem by throwing more compute at it, you can \n", + "provide a derivative to optimagic that is faster than doing `n + 1` evaluations of `fun`. \n", + "Here we show you how to hand-code it, but in practice you would usually use JAX or another \n", + "autodiff framework to create the derivative." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere_gradient(x):\n", + " return 2 * x\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " jac=sphere_gradient,\n", + ")\n", + "res.params.round(6)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In this example, the evaluation of `sphere_gradient` is even faster than evaluating `sphere`. \n", + "\n", + "In non-trivial functions, there are synergies between calculating the objective value and \n", + "its derivative. Therefore, you can also provide a function that evaluates both at the same time. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere_fun_and_gradient(x):\n", + " return x @ x, 2 * x\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " fun_and_jac=sphere_fun_and_gradient,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "`fun_and_jac` can be provided in addition to or instead of `jac`. Providing them \n", + "together gives optimagic more opportunities to save \n", + "time by evaluating just the function that is needed for a given optimizer. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Derivatives with flexible params\n", + "\n", + "Derivatives are compatible with any format of params. In general, the gradients have \n", + "just the same structure as your params. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def dict_fun(x):\n", + " return x[\"a\"] ** 2 + x[\"b\"] ** 4\n", + "\n", + "\n", + "def dict_gradient(x):\n", + " return {\"a\": 2 * x[\"a\"], \"b\": 4 * x[\"b\"] ** 3}\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=dict_fun,\n", + " params={\"a\": 1, \"b\": 2},\n", + " algorithm=\"scipy_lbfgsb\",\n", + " jac=dict_gradient,\n", + ")\n", + "res.params" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is also the convention that JAX uses, so any derivative you get via JAX will be \n", + "compatible with optimagic. \n", + "\n", + "## Derivatives for least-squares functions\n", + "\n", + "When minimizing least-squares functions, you don't need the gradient of the objective \n", + "value but the jacobian of the least-squares residuals. Moreover, this jacobian function \n", + "needs to be decorated with the `mark.least_squares` decorator. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "@om.mark.least_squares\n", + "def ls_sphere(params):\n", + " return params\n", + "\n", + "\n", + "@om.mark.least_squares\n", + "def ls_sphere_jac(params):\n", + " return np.eye(len(params))\n", + "\n", + "\n", + "res = om.minimize(\n", + " fun=ls_sphere,\n", + " params=np.arange(3),\n", + " algorithm=\"scipy_ls_lm\",\n", + " jac=ls_sphere_jac,\n", + ")\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The `fun_and_jac` argument works just analogous to the scalar case. \n", + "\n", + "Derivatives of least-squares functions again work with all valid formats of params. \n", + "However, the structure of the jacobian can be a bit complicated. Again, JAX will do \n", + "the right thing here, so we strongly suggest you calculate all your jacobians via JAX,\n", + "especially if your params are not a flat numpy array. \n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Derivatives that work for scalar and least-squares optimizers\n", + "\n", + "If you want to seamlessly switch between scalar and least-squares optimizers, you can \n", + "do so by providing even more versions of derivatives to `minimize`. You probably won't \n", + "ever need this, but here is how you would do it. To pretend that this can be useful, \n", + "we compare a scalar and a least squares optimizer in a criterion_plot:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "results = {}\n", + "for algorithm in [\"scipy_lbfgsb\", \"scipy_ls_lm\"]:\n", + " results[algorithm] = om.minimize(\n", + " fun=ls_sphere,\n", + " params=np.arange(5),\n", + " algorithm=algorithm,\n", + " jac=[sphere_gradient, ls_sphere_jac],\n", + " )\n", + "\n", + "fig = om.criterion_plot(results)\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We see that both optimizers were super fast in solving this problem (mainly because the problem is so simple) and in this case the scalar optimizer was even faster. However, in non-trivial problems it almost always pays of to exploit the least-squares structure if you can." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "optimagic", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/source/how_to/how_to_errors_during_optimization.ipynb b/docs/source/how_to/how_to_errors_during_optimization.ipynb new file mode 100644 index 000000000..647000a95 --- /dev/null +++ b/docs/source/how_to/how_to_errors_during_optimization.ipynb @@ -0,0 +1,252 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": {}, + "source": [ + "(how-to-errors)=\n", + "\n", + "# How to handle errors during optimization\n", + "\n", + "## Try to avoid errors\n", + "\n", + "Often, optimizers try quite extreme parameter vectors, which then can raise errors in your criterion function or derivative. Often, there are simple tricks to make your code more robust. Avoiding errors is always better than dealing with errors after they occur. \n", + "\n", + "- Avoid to take ``np.exp`` without further safeguards. With 64 bit floating point numbers, the exponential function is only well defined roughly between -700 and 700. Below it is 0, above it is inf. Sometimes you can use ``scipy.special.logsumexp`` to avoid unsafe evaluations of the exponential. Read [this](https://en.wikipedia.org/wiki/LogSumExp) for background information on the logsumexp trick.\n", + "- Set bounds for your parameters that prevent extreme parameter constellations.\n", + "- Use the ``bounds_distance`` option with a not too small value for ``covariance`` and ``sdcorr`` constraints.\n", + "- Use `optimagic.utilities.robust_cholesky` instead of normal\n", + " cholesky decompositions or try to avoid cholesky decompositions.\n", + "- Use a less aggressive optimizer. Trust region optimizers like `fides` usually choose less extreme steps in the beginnig than line search optimizers like `scipy_bfgs` and `scip_lbfgsb`. \n", + "\n", + "## Do not use clipping\n", + "\n", + "A commonly chosen solution to numerical problems is clipping of extreme values. Naive clipping leads to flat areas in your criterion function and can cause spurious convergence. Only use clipping if you know that your optimizer can deal with flat parts. " + ] + }, + { + "cell_type": "markdown", + "id": "1", + "metadata": {}, + "source": [ + "## Let optimagic do its magic\n", + "\n", + "Instead of avoiding errors in your criterion function, you can raise them and let optimagic deal with them. If you are using numerical derivatives, errors will automatically be raised if any entry in the derivative is not finite. \n", + "\n", + "### An example\n", + "\n", + "Let's look at a simple example from the Moré-Wild benchmark set that has a numerical instability. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2", + "metadata": {}, + "outputs": [], + "source": [ + "import warnings\n", + "\n", + "import numpy as np\n", + "import optimagic as om\n", + "from scipy.optimize import minimize as scipy_minimize\n", + "\n", + "warnings.simplefilter(\"ignore\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3", + "metadata": {}, + "outputs": [], + "source": [ + "def jennrich_sampson(x):\n", + " dim_out = 10\n", + " fvec = (\n", + " 2 * (1.0 + np.arange(1, dim_out + 1))\n", + " - np.exp(np.arange(1, dim_out + 1) * x[0])\n", + " - np.exp(np.arange(1, dim_out + 1) * x[1])\n", + " )\n", + " return fvec @ fvec\n", + "\n", + "\n", + "correct_params = np.array([0.2578252135686162, 0.2578252135686162])\n", + "correct_criterion = 124.3621823556148\n", + "\n", + "start_x = np.array([0.3, 0.4])" + ] + }, + { + "cell_type": "markdown", + "id": "4", + "metadata": {}, + "source": [ + "### What would scipy do?" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "5", + "metadata": {}, + "outputs": [], + "source": [ + "scipy_res = scipy_minimize(jennrich_sampson, x0=start_x, method=\"L-BFGS-B\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6", + "metadata": {}, + "outputs": [], + "source": [ + "scipy_res.success" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7", + "metadata": {}, + "outputs": [], + "source": [ + "correct_params.round(4), scipy_res.x.round(4)" + ] + }, + { + "cell_type": "markdown", + "id": "8", + "metadata": {}, + "source": [ + "So, scipy thinks it solved the problem successfully but the result is far off. (Note that scipy would have given us a warning, but we disabled warnings in order to not clutter the output).\n", + "\n", + "### optimagic's error handling magic" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=jennrich_sampson,\n", + " params=start_x,\n", + " algorithm=\"scipy_lbfgsb\",\n", + " error_handling=\"continue\",\n", + ")\n", + "\n", + "correct_params, res.params" + ] + }, + { + "cell_type": "markdown", + "id": "10", + "metadata": {}, + "source": [ + "### How does the magic work\n", + "\n", + "When an error occurs and `error_handling` is set to `\"continue\"`, optimagic replaces your criterion with a dummy function (and adjusts the derivative accordingly). \n", + "\n", + "The dummy function has two important properties:\n", + "\n", + "1. Its value is always higher than criterion at start params. \n", + "2. Its slope guides the optimizer back towards the start parameters. I.e., if you are minimizing, the direction of strongest decrease is towards the start parameters; if you are maximizing, the direction of strongest increase is towards the start parameters. \n", + "\n", + "Therefore, when hitting an undefined area, an optimizer can take a few steps back until it is in better territory and then continue its work. \n", + "\n", + "Importantly, the optimizer will not simply go back to a previously evaluated point (which would just lead to cyclical behavior). It will just go back in the direction it originally came from.\n", + "\n", + "In the concrete example, the dummy function would look similar to the following:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "11", + "metadata": {}, + "outputs": [], + "source": [ + "def dummy(params):\n", + " start_params = np.array([0.3, 0.4])\n", + " # this is close to the actual value used by optimagic\n", + " constant = 8000\n", + " # the actual slope used by optimagic would be even smaller\n", + " slope = 10_000\n", + " diff = params - start_params\n", + " return constant + slope * np.linalg.norm(diff)" + ] + }, + { + "cell_type": "markdown", + "id": "12", + "metadata": {}, + "source": [ + "Now, let's plot the two functions. For better illustration, we assume that the jennrich_sampson function is only defined until it reaches a value of 100_000 and the dummy function takes over from there. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "13", + "metadata": {}, + "outputs": [], + "source": [ + "from plotly import graph_objects as go\n", + "\n", + "grid = np.linspace(0, 1)\n", + "params = [np.full(2, val) for val in grid]\n", + "values = np.array([jennrich_sampson(p) for p in params])\n", + "values = np.where(values <= 1e5, values, np.nan)\n", + "dummy_values = np.array([dummy(p) for p in params])\n", + "dummy_values = np.where(np.isfinite(values), np.nan, dummy_values)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "14", + "metadata": {}, + "outputs": [], + "source": [ + "fig = go.Figure()\n", + "fig.add_trace(go.Scatter(x=grid, y=values))\n", + "fig.add_trace(go.Scatter(x=grid, y=dummy_values))\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "15", + "metadata": {}, + "source": [ + "We can see that the dummy function is lower than the highest achieved value of `jennrich_sampson` but higher than the start values. It is also rather flat. Fortunately, that is all we need. " + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/how_to/how_to_logging.ipynb b/docs/source/how_to/how_to_logging.ipynb new file mode 100644 index 000000000..c957341d9 --- /dev/null +++ b/docs/source/how_to/how_to_logging.ipynb @@ -0,0 +1,257 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "(how-to-logging)=\n", + "\n", + "# How to use logging\n", + "\n", + "\n", + "optimagic can keep a persistent log of the parameter and criterion values tried out by an optimizer in a sqlite database. \n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Turn logging on or off\n", + "\n", + "To enable logging, it suffices to provide a path to an sqlite database when calling ``maximize`` or ``minimize``. The database does not have to exist, optimagic will generate it for you. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pathlib import Path\n", + "\n", + "import numpy as np\n", + "import optimagic as om" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere(params):\n", + " return params @ params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Remove the log file if it exists (just needed for the example)\n", + "log_file = Path(\"my_log.db\")\n", + "if log_file.exists():\n", + " log_file.unlink()\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " logging=\"my_log.db\",\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In case the SQLite file already exists, this will raise a `FileExistsError` to prevent from accidentally polluting an existing database. If you want to reuse\n", + "an existing database on purpose, you must explicitly provide the corresponding option for `if_database_exists`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "log_options = om.SQLiteLogOptions(\n", + " \"my_log.db\", if_database_exists=om.ExistenceStrategy.EXTEND\n", + ")\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " logging=log_options,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Make logging faster\n", + "\n", + "By default, we use a very safe mode of sqlite that makes it almost impossible to corrupt the database. Even if your computer is suddenly shut down or unplugged. \n", + "\n", + "However, this makes writing logs rather slow, which becomes notable when the criterion function is very fast. \n", + "\n", + "In that case, you can enable `fast_logging`, which is still quite safe!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "log_options = om.SQLiteLogOptions(\n", + " \"my_log.db\",\n", + " fast_logging=True,\n", + " if_database_exists=om.ExistenceStrategy.REPLACE,\n", + ")\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " logging=log_options,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Reading the log\n", + "To read the log after an optimization, extract the logger from the optimization result:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "reader = res.logger" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alternatively, you can create the reader like this:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "reader = om.SQLiteLogReader(\"my_log.db\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Read the start params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "reader.read_start_params()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Read a specific iteration (use -1 for the last)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "reader.read_iteration(-1)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Read the full history" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "reader.read_history().keys()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Plot the history from a log" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.criterion_plot(\"my_log.db\")\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.params_plot(\"my_log.db\", selector=lambda x: x[1:3])\n", + "fig.show(renderer=\"png\")" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "5cdb9867252288f10687117449de6ad870b49795ca695c868016dc0022895cce" + }, + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/source/how_to/how_to_multistart.ipynb b/docs/source/how_to/how_to_multistart.ipynb new file mode 100644 index 000000000..a4506d4ac --- /dev/null +++ b/docs/source/how_to/how_to_multistart.ipynb @@ -0,0 +1,501 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": {}, + "source": [ + "(how-to-multistart)=\n", + "\n", + "# How to do multistart optimizations\n", + "\n", + "Sometimes you want to make sure that your optimization is robust to the initial\n", + "parameter values, i.e. that it does not get stuck at a local optimum. This is where\n", + "multistart comes in handy.\n", + "\n", + "\n", + "## What does multistart (not) do\n", + "\n", + "In short, multistart iteratively runs local optimizations from different initial\n", + "conditions. If enough local optimization convergence to the same point, it stops.\n", + "Importantly, it cannot guarantee that the result is the global optimum, but it can\n", + "increase your confidence in the result.\n", + "\n", + "## TL;DR\n", + "\n", + "To activate multistart at the default options, pass `multistart=True` to the `minimize`\n", + "or `maximize` function, as well as finite bounds on the parameters (which are used to\n", + "sample the initial points). The default options are discussed below." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1", + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om\n", + "\n", + "\n", + "def fun(x):\n", + " return x @ x\n", + "\n", + "\n", + "x0 = np.arange(7) - 4\n", + "\n", + "bounds = om.Bounds(\n", + " lower=np.full_like(x0, -5),\n", + " upper=np.full_like(x0, 10),\n", + ")\n", + "\n", + "algo_options = {\"stopping_maxfun\": 1_000}\n", + "\n", + "res = om.minimize(\n", + " fun=fun,\n", + " x0=x0,\n", + " algorithm=\"scipy_neldermead\",\n", + " algo_options=algo_options,\n", + " bounds=bounds,\n", + " multistart=True,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "2", + "metadata": {}, + "source": [ + "In this example, we limited each local optimization to 1_000 function evaluations. In\n", + "general, it is a good idea to limit the number of iterations and function evaluations\n", + "for the local optimization. Because of the iterative nature of multistart, this\n", + "limitation will usually not result in a precision issue." + ] + }, + { + "cell_type": "markdown", + "id": "3", + "metadata": {}, + "source": [ + "## What does multistart mean in optimagic?\n", + "\n", + "Our multistart optimizations are inspired by the [TikTak algorithm](https://github.com/serdarozkan/TikTak) and consist of the following steps:\n", + "\n", + "1. Draw a large exploration sample of parameter vectors randomly or using a\n", + " low-discrepancy sequence.\n", + "1. Evaluate the objective function in parallel on the exploration sample.\n", + "1. Sort the parameter vectors from best to worst according to their objective function\n", + " values. \n", + "1. Run local optimizations iteratively. That is, the first local optimization is started\n", + " from the best parameter vector in the sample. All subsequent ones are started from a\n", + " convex combination of the currently best known parameter vector and the next sample\n", + " point. " + ] + }, + { + "cell_type": "markdown", + "id": "4", + "metadata": {}, + "source": [ + "## Visualizing multistart results\n", + "\n", + "To illustrate the multistart results, we will consider the optimization of a slightly\n", + "more complex objective function, compared to `fun` from above. We also limit the\n", + "number of exploration samples to 100." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "5", + "metadata": {}, + "outputs": [], + "source": [ + "def alpine(x):\n", + " return np.sum(np.abs(x * np.sin(x) + 0.1 * x))\n", + "\n", + "\n", + "res = om.minimize(\n", + " alpine,\n", + " x0=x0,\n", + " algorithm=\"scipy_neldermead\",\n", + " bounds=bounds,\n", + " algo_options=algo_options,\n", + " multistart=om.MultistartOptions(n_samples=100, seed=0),\n", + ")\n", + "\n", + "fig = om.criterion_plot(res, monotone=True)\n", + "fig.show(\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "6", + "metadata": {}, + "source": [ + "In the above image we see the optimization history for all of the local optimizations\n", + "that have been run by multistart. The turquoise line represents the history\n", + "corresponding to the local optimization that found the overall best parameter.\n", + "\n", + "We see that running a single optimization would not have sufficed, as some local\n", + "optimizations are stuck." + ] + }, + { + "cell_type": "markdown", + "id": "7", + "metadata": {}, + "source": [ + "## Multistart does not always run many optimization\n", + "\n", + "Since the local optimizations are run iteratively by multistart, it is possible that\n", + "only a handful of optimizations are actually run if all of them converge to the same\n", + "point. This convergence is determined by the `convergence_max_discoveries` option,\n", + "which defaults to 2. This means that if 2 local optimizations report the same point,\n", + "multistart will stop. Below we see that if we use the simpler objective function\n", + "(`fun`), and the `scipy_lbfgsb` algorithm, multistart runs only 2 local optimizations,\n", + "and then stops, as both of them converge to the same point. Note that, the\n", + "`scipy_lbfgsb` algorithm can solve this simple problem precisely, without reaching the\n", + "maximum number of function evaluations." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun,\n", + " x0=x0,\n", + " algorithm=\"scipy_lbfgsb\",\n", + " bounds=bounds,\n", + " algo_options=algo_options,\n", + " multistart=om.MultistartOptions(n_samples=100, seed=0),\n", + ")\n", + "\n", + "fig = om.criterion_plot(res)\n", + "fig.show(\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "9", + "metadata": {}, + "source": [ + "## How to configure multistart\n", + "\n", + "Configuration of multistart can be done by passing an instance of\n", + "`optimagic.MultistartOptions` to `minimize` or `maximize`. Let's look at a few examples\n", + "configurations." + ] + }, + { + "cell_type": "markdown", + "id": "10", + "metadata": {}, + "source": [ + "### How to run a specific number of optimizations\n", + "\n", + "To run a specific number of local optimizations, you need to set the `stopping_maxopt`\n", + "option. Note that this does not set the number of exploration samples, which is\n", + "controlled by the `n_samples` option. The number of exploration samples always needs\n", + "to be at least as large as the number of local optimizations.\n", + "\n", + "Note that, as long as `convergence_max_discoveries` is smaller than `stopping_maxopt`,\n", + "it is possible that a smaller number of local optimizations are run. To avoid this,\n", + "set `convergence_max_discoveries` to a value at least as large as `stopping_maxopt`.\n", + "\n", + "To run, for example, 10 local optimizations from 15 exploration samples, do:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "11", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " alpine,\n", + " x0=x0,\n", + " algorithm=\"scipy_neldermead\",\n", + " bounds=bounds,\n", + " algo_options=algo_options,\n", + " multistart=om.MultistartOptions(\n", + " n_samples=15,\n", + " stopping_maxopt=10,\n", + " convergence_max_discoveries=10,\n", + " ),\n", + ")\n", + "\n", + "res.multistart_info.n_optimizations" + ] + }, + { + "cell_type": "markdown", + "id": "12", + "metadata": {}, + "source": [ + "### How to set a custom exploration sample\n", + "\n", + "If you want to start the multistart algorithm with a custom exploration sample, you can\n", + "do so by passing a sequence of parameters to the `sample` option. Note that sequence\n", + "elements must be of the same type as your parameter.\n", + "\n", + "To generate a sample of 100 random parameters and run them through the multistart\n", + "algorithm, do:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "13", + "metadata": {}, + "outputs": [], + "source": [ + "rng = np.random.default_rng(12345)\n", + "\n", + "sample = [x0 + rng.uniform(-1, 1, size=len(x0)) for _ in range(100)]\n", + "\n", + "res = om.minimize(\n", + " alpine,\n", + " x0=x0,\n", + " algorithm=\"scipy_neldermead\",\n", + " bounds=bounds,\n", + " algo_options=algo_options,\n", + " multistart=om.MultistartOptions(sample=sample),\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "14", + "metadata": {}, + "source": [ + "### How to run multistart in parallel\n", + "\n", + "\n", + "The multistart algorithm can be run in parallel by setting the `n_cores` option to a\n", + "value greater than 1. This will run the algorithm in batches. By default, the batch\n", + "size is set to `n_cores`, but can be controlled by setting the `batch_size` option. The\n", + "default batch evaluator is `joblib`, but can be controlled by setting the\n", + "`batch_evaluator` option to `\"pathos\"` or a custom callable.\n", + "\n", + "To run the multistart algorithm in parallel, do:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "15", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " alpine,\n", + " x0=x0,\n", + " algorithm=\"scipy_lbfgsb\",\n", + " bounds=bounds,\n", + " algo_options=algo_options,\n", + " multistart=om.MultistartOptions(n_cores=2),\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "16", + "metadata": {}, + "source": [ + "## What to do if you do not have bounds\n", + "\n", + "Multistart requires finite bounds on the parameters. If your optimization problem is not\n", + "bounded, you can set soft lower and upper bounds. These bounds will only be used to\n", + "draw the exploration sample, and will not be used to constrain the local optimizations.\n", + "\n", + "To set soft bounds, do:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "17", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " alpine,\n", + " x0=x0,\n", + " algorithm=\"scipy_lbfgsb\",\n", + " bounds=om.Bounds(soft_lower=np.full_like(x0, -3), soft_upper=np.full_like(x0, 8)),\n", + " multistart=True,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "18", + "metadata": {}, + "source": [ + "## Understanding multistart results\n", + "\n", + "When activating multistart, the optimization result object corresponds to the local\n", + "optimization that found the best objective function value. The result object has the\n", + "additional attribute `multistart_info`, where all of the additional information is\n", + "stored. It has the following attributes:\n", + "\n", + "- `local_optima`: A list with the results from all local optimizations that were performed.\n", + "- `start_parameters`: A list with the start parameters from those optimizations \n", + "- `exploration_sample`: A list with parameter vectors at which the objective function was evaluated in an initial exploration phase. \n", + "- `exploration_results`: The corresponding objective values.\n", + "- `n_optimizations`: The number of local optimizations that were run.\n", + "\n", + "To illustrate the multistart results, let us consider the optimization of the simple\n", + "`fun` objective function from above." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "19", + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun,\n", + " x0=x0,\n", + " algorithm=\"scipy_lbfgsb\",\n", + " bounds=bounds,\n", + " algo_options=algo_options,\n", + " multistart=om.MultistartOptions(n_samples=100, convergence_max_discoveries=2),\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "20", + "metadata": {}, + "source": [ + "### Start parameters\n", + "\n", + "The start parameters are the parameter vectors from which the local optimizations were\n", + "started. Since the default number of `convergence_max_discoveries` is 2, and both\n", + "local optimizations were successfull, the start parameters have 2 rows." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "21", + "metadata": {}, + "outputs": [], + "source": [ + "res.multistart_info.start_parameters" + ] + }, + { + "cell_type": "markdown", + "id": "22", + "metadata": {}, + "source": [ + "### Local Optima\n", + "\n", + "The local optima are the results from the local optimizations. Since in this example\n", + "only two local optimizations were run, the local optima list has two elements, each of\n", + "which is an optimization result object." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "23", + "metadata": {}, + "outputs": [], + "source": [ + "len(res.multistart_info.local_optima)" + ] + }, + { + "cell_type": "markdown", + "id": "24", + "metadata": {}, + "source": [ + "### Exploration sample\n", + "\n", + "The exploration sample is a list of parameter vectors at which the objective function\n", + "was evaluated. Above, we chose a random exploration sample of 100 parameter vectors." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "25", + "metadata": {}, + "outputs": [], + "source": [ + "np.row_stack(res.multistart_info.exploration_sample).shape" + ] + }, + { + "cell_type": "markdown", + "id": "26", + "metadata": {}, + "source": [ + "### Exploration results\n", + "\n", + "The exploration results are the objective function values at the exploration sample." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "27", + "metadata": {}, + "outputs": [], + "source": [ + "len(res.multistart_info.exploration_results)" + ] + }, + { + "cell_type": "markdown", + "id": "28", + "metadata": {}, + "source": [ + "### Number of local optimizations" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "29", + "metadata": {}, + "outputs": [], + "source": [ + "res.multistart_info.n_optimizations" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/how_to_guides/optimization/how_to_scale_optimization_problems.md b/docs/source/how_to/how_to_scaling.md similarity index 66% rename from docs/source/how_to_guides/optimization/how_to_scale_optimization_problems.md rename to docs/source/how_to/how_to_scaling.md index ec9b9fcf7..f24eb091c 100644 --- a/docs/source/how_to_guides/optimization/how_to_scale_optimization_problems.md +++ b/docs/source/how_to/how_to_scaling.md @@ -11,24 +11,52 @@ and cons of each approach. ## What does well scaled mean In short, an optimization problem is well scaled if a fixed step in any direction yields -a roughly similar sized change in the criterion function. +a roughly similar sized change in the objective function. In practice, this can never be achieved perfectly (at least for nonlinear problems). However, one can easily improve over simply ignoring the problem altogether. +## TL;DR + +To activate scaling at the default options, pass `scaling=True` to the `minimize` or +`maximize` function. This uses the start values heuristic explained below. The default +options are discussed in the section {ref}`scaling-default-values`. + +```{code-block} python +--- +emphasize-lines: 13 +--- +import numpy as np +import optimagic as om + + +def fun(x): + return x @ x + + +res = om.minimize( + fun=fun, + x0=np.arange(5), + algorithm="scipy_lbfgsb", + scaling=True, +) +``` + ## Heuristics to improve scaling +(scaling-start-values-heuristic)= + ### Divide by absolute value of start parameters In many applications, parameters with very large start values will vary over a wide range and a change in that parameter will only lead to a relatively small change in the -criterion function. If this is the case, the scaling of the optimization problem can be +objective function. If this is the case, the scaling of the optimization problem can be improved by simply dividing all parameter vectors by the start parameters. **Advantages:** -- straightforward -- works with any type of constraints +- Straightforward +- Works with any type of constraints **Disadvantages:** @@ -37,24 +65,15 @@ improved by simply dividing all parameter vectors by the start parameters. **How to specify this scaling:** -```python -import estimagic as em - - -def sphere(params): - return (params["value"] ** 2).sum() - - -start_params = pd.DataFrame(data=np.arange(5), columns=["value"]) -start_params["lower_bound"] = 0 -start_params["upper_bound"] = 2 * np.arange(5) + 1 - -res = em.minimize( - criterion=sphere, - params=start_params, +```{code-block} python +--- +emphasize-lines: 5 +--- +res = om.minimize( + fun=fun, + x0=np.arange(5), algorithm="scipy_lbfgsb", - scaling=True, - scaling_options={"method": "start_values", "clipping_value": 0.1}, + scaling=om.ScalingOptions(method="start_values", clipping_value=0.1), ) ``` @@ -66,9 +85,9 @@ others are soft and derived from simple considerations (e.g. if a time discount were smaller than 0.7, we would not observe anyone to pursue a university degree in a structural model of educational choices; or if an infection probability was higher than 20% for distant contacts, the covid pandemic would have been over after a month). For -parameters that strongly influence the criterion function, the bounds stemming from +parameters that strongly influence the objective function, the bounds stemming from these considerations are typically tighter than for parameters that have a small effect -on the criterion function. +on the objective function. Thus, a natural approach to improve the scaling of the optimization problem is to re-map all parameters such that the bounds are \[0, 1\] for all parameters. This has the @@ -77,33 +96,28 @@ changes become the same. **Advantages:** -- straightforward -- works well in many practical applications -- scaling is independent of start values +- Straightforward +- Works well in many practical applications +- Scaling is independent of start values - No problems with division by zero **Disadvantages:** - Only works if all parameters have bounds -- This prohibits some kinds of other constraints in estimagic +- This prohibits some kinds of other constraints in optimagic **How to specify this scaling:** -```python -def sphere(params): - return (params["value"] ** 2).sum() - - -start_params = pd.DataFrame(data=np.arange(5), columns=["value"]) -start_params["lower_bound"] = 0 -start_params["upper_bound"] = 2 * np.arange(5) + 1 - -res = em.minimize( - criterion=sphere, - params=start_params, +```{code-block} python +--- +emphasize-lines: 5,6 +--- +res = om.minimize( + fun=fun, + x0=np.arange(5), algorithm="scipy_lbfgsb", - scaling=True, - scaling_options={"method": "bounds", "clipping_value": 0.0}, + bounds=om.Bounds(lower=np.zeros(5), upper=2 * np.arange(5) + 1), + scaling=om.ScalingOptions(method="bounds", clipping_value=0.0), ) ``` @@ -124,21 +138,16 @@ effectively make the trust region radius smaller. Setting the magnitude means simply adding one more entry to the scaling options. For example, if you want to scale by bounds and increase the magnitude by a factor of five: -```python -def sphere(params): - return (params["value"] ** 2).sum() - - -start_params = pd.DataFrame(data=np.arange(5), columns=["value"]) -start_params["lower_bound"] = 0 -start_params["upper_bound"] = 2 * np.arange(5) + 1 - -res = em.minimize( - criterion=sphere, - params=start_params, +```{code-block} python +--- +emphasize-lines: 6 +--- +res = om.minimize( + fun=fun, + x0=np.arange(5), algorithm="scipy_lbfgsb", - scaling=True, - scaling_options={"method": "bounds", clipping_value: 0.0, "magnitude": 5}, + bounds=om.Bounds(lower=np.zeros(5), upper=2 * np.arange(5) + 1), + scaling=om.ScalingOptions(method="bounds", clipping_value=0.0, magnitude=5), ) ``` @@ -157,10 +166,12 @@ to a strictly non-zero number for the `"start_values"` and `"gradient"` approach tight bounds. However, this means that the bounds of the re-scaled problem are not exactly \[0, 1\] for all parameters. +(scaling-default-values)= + ### Default values -Scaling is disabled by default. If enabled, but no `scaling_options` are provided, we -use the `"start_values"` method with a `"clipping_value"` of 0.1. This is the default -method because it can be used for all optimization problems and has low computational -cost. We strongly recommend you read the above guidelines and choose the method that is -most suitable for your problem. +Scaling is disabled by default. By passing `scaling=True`, we enable scaling at the +default values. We use the `"start_values"` method with a `"clipping_value"` of 0.1 and +a magnitude of 1.0. This is the default method because it can be used for all +optimization problems and has low computational cost. We strongly recommend you read the +above guidelines and choose the method that is most suitable for your problem. diff --git a/docs/source/how_to/how_to_slice_plot.ipynb b/docs/source/how_to/how_to_slice_plot.ipynb new file mode 100644 index 000000000..bd4d0e9f6 --- /dev/null +++ b/docs/source/how_to/how_to_slice_plot.ipynb @@ -0,0 +1,149 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# How to visualize an optimization problem\n", + "\n", + "Plotting the criterion function of an optimization problem can answer important questions\n", + "- Is the function smooth?\n", + "- Is the function flat in some directions?\n", + "- Should the optimization problem be scaled?\n", + "- Is a candidate optimum a global one?\n", + "\n", + "Below we show how to make a slice plot of the criterion function." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## The simple sphere function (again)\n", + "\n", + "Let's look at the simple sphere function again. This time, we specify params as dictionary, but of course, any other params format (recall [pytrees](https://jax.readthedocs.io/en/latest/pytrees.html)) would work just as well. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere(params):\n", + " x = np.array(list(params.values()))\n", + " return x @ x" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "params = {\"alpha\": 0, \"beta\": 0, \"gamma\": 0, \"delta\": 0}\n", + "bounds = om.Bounds(\n", + " lower={name: -5 for name in params},\n", + " upper={name: i + 2 for i, name in enumerate(params)},\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Creating a simple slice plot" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.slice_plot(\n", + " func=sphere,\n", + " params=params,\n", + " bounds=bounds,\n", + ")\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Interpreting the plot\n", + "\n", + "The plot gives us the following insights:\n", + " \n", + "- There is no sign of local optima. \n", + "- There is no sign of noise or non-differentiablities (careful, grid might not be fine enough).\n", + "- The problem seems to be convex.\n", + "\n", + "-> We would expect almost any derivative based optimizer to work well here (which we know to be correct in that case)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Using advanced options" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.slice_plot(\n", + " func=sphere,\n", + " params=params,\n", + " bounds=bounds,\n", + " # selecting a subset of params\n", + " selector=lambda x: [x[\"alpha\"], x[\"beta\"]],\n", + " # evaluate func in parallel\n", + " n_cores=4,\n", + " # rename the parameters\n", + " param_names={\"alpha\": \"Alpha\", \"beta\": \"Beta\"},\n", + " title=\"Amazing Plot\",\n", + " # number of gridpoints in each dimension\n", + " n_gridpoints=50,\n", + ")\n", + "fig.show(renderer=\"png\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/source/how_to_guides/optimization/how_to_specify_algorithm_and_algo_options.md b/docs/source/how_to/how_to_specify_algorithm_and_algo_options.md similarity index 89% rename from docs/source/how_to_guides/optimization/how_to_specify_algorithm_and_algo_options.md rename to docs/source/how_to/how_to_specify_algorithm_and_algo_options.md index 5212d1ff4..885a994f2 100644 --- a/docs/source/how_to_guides/optimization/how_to_specify_algorithm_and_algo_options.md +++ b/docs/source/how_to/how_to_specify_algorithm_and_algo_options.md @@ -1,14 +1,14 @@ -(algorithms)= +(specify-algorithm)= # How to specify algorithms and algorithm specific options ## The *algorithm* argument The `algorithm` argument can either be a string with the name of an algorithm that is -implemented in estimagic, or a function that fulfills the interface laid out in +implemented in optimagic, or a function that fulfills the interface laid out in {ref}`internal_optimizer_interface`. -Which algorithms are available in estimagic depends on the packages a user has +Which algorithms are available in optimagic depends on the packages a user has installed. We list all supported algorithms in {ref}`list_of_algorithms`. ## The *algo_options* argument @@ -35,7 +35,6 @@ algo_options = { "trustregion.shrinking_factor.not_successful": 0.4, "trustregion.shrinking_factor.lower_radius": 0.2, "trustregion.shrinking_factor.upper_radius": 0.8, - "convergence.scaled_criterion_tolerance": 0.0, "convergence.noise_corrected_criterion_tolerance": 1.1, } ``` diff --git a/docs/source/how_to_guides/optimization/how_to_specify_parameters.md b/docs/source/how_to/how_to_start_parameters.md similarity index 84% rename from docs/source/how_to_guides/optimization/how_to_specify_parameters.md rename to docs/source/how_to/how_to_start_parameters.md index d975ceca4..fc5a031e9 100644 --- a/docs/source/how_to_guides/optimization/how_to_specify_parameters.md +++ b/docs/source/how_to/how_to_start_parameters.md @@ -2,13 +2,13 @@ # How to specify `params` -`params` is the first argument of any criterion function in estimagic. It collects all +`params` is the first argument of any criterion function in optimagic. It collects all the parameters to estimate, optimize, or differentiate over. In many optimization -libraries, `params` must be a one-dimensional numpy array. In estimagic, it can be an +libraries, `params` must be a one-dimensional numpy array. In optimagic, it can be an arbitrary pytree (think nested dictionary) containing numbers, arrays, pandas.Series, and/or pandas.DataFrames. -Below, we show a few examples of what is possible in estimagic and discuss the +Below, we show a few examples of what is possible in optimagic and discuss the advantages and drawbacks of each of them. Again, we use the simple `sphere` function you know from other tutorials as an example. @@ -29,15 +29,15 @@ Again, we use the simple `sphere` function you know from other tutorials as an e .. code-block:: python - import estimagic as em + import optimagic as om def sphere(params): return params @ params - em.minimize( - criterion=sphere, + om.minimize( + fun=sphere, params=np.arange(3), algorithm="scipy_lbfgsb", ) @@ -47,7 +47,7 @@ Again, we use the simple `sphere` function you know from other tutorials as an e ```{eval-rst} .. tabbed:: DataFrame - Originally, pandas DataFrames were the mandatory format for ``params`` in estimagic. + Originally, pandas DataFrames were the mandatory format for ``params`` in optimagic. They are still highly recommended and have a few special features. For example, they allow to bundle information on start parameters and bounds together into one data structure. @@ -65,8 +65,8 @@ Again, we use the simple `sphere` function you know from other tutorials as an e index=["a", "b", "c"], ) - em.minimize( - criterion=sphere, + om.minimize( + fun=sphere, params=params, algorithm="scipy_lbfgsb", ) @@ -81,8 +81,6 @@ Again, we use the simple `sphere` function you know from other tutorials as an e - You can bundle information on bounds and values in one place. - It is easy to compare two params vectors for equality. - Check out our `Ordered Logit Example <../../getting_started/estimation/first_likelihood_estimation_with_estimagic.ipynb>`_, - so you see one small params DataFrame in action. If you are sure you won't have bounds on your parameter, you can also use a pandas.Series instead of a pandas.DataFrame. @@ -104,8 +102,8 @@ Again, we use the simple `sphere` function you know from other tutorials as an e return params["a"] ** 2 + params["b"] ** 2 + (params["c"] ** 2).sum() - res = em.minimize( - criterion=sphere, + res = om.minimize( + fun=sphere, params={"a": 0, "b": 1, "c": pd.Series([2, 3, 4])}, algorithm="scipy_neldermead", ) @@ -114,7 +112,7 @@ Again, we use the simple `sphere` function you know from other tutorials as an e groups of parameters. They are also a good choice if you calculate derivatives with JAX. - While estimagic won't stop you, don't go too far! Having parameters in very deeply + While optimagic won't stop you, don't go too far! Having parameters in very deeply nested dictionaries makes it hard to visualize results and/or even to compare two estimation results. @@ -132,8 +130,8 @@ Again, we use the simple `sphere` function you know from other tutorials as an e return params**2 - em.minimize( - criterion=sphere, + om.minimize( + fun=sphere, params=3, algorithm="scipy_lbfgsb", ) diff --git a/docs/source/how_to/how_to_visualize_histories.ipynb b/docs/source/how_to/how_to_visualize_histories.ipynb new file mode 100644 index 000000000..37b3e43a1 --- /dev/null +++ b/docs/source/how_to/how_to_visualize_histories.ipynb @@ -0,0 +1,221 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": {}, + "source": [ + "# How to visualize optimizer histories\n", + "\n", + "optimagic's `criterion_plot` can visualize the history of function values for one or multiple optimizations. \n", + "optimagic's `params_plot` can visualize the history of parameter values for one optimization. \n", + "\n", + "This can help you to understand whether your optimization actually converged and if not, which parameters are problematic. \n", + "\n", + "It can also help you to find the fastest optimizer for a given optimization problem. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1", + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om" + ] + }, + { + "cell_type": "markdown", + "id": "2", + "metadata": {}, + "source": [ + "## Run two optimization to get example results" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3", + "metadata": {}, + "outputs": [], + "source": [ + "def sphere(x):\n", + " return x @ x\n", + "\n", + "\n", + "results = {}\n", + "for algo in [\"scipy_lbfgsb\", \"scipy_neldermead\"]:\n", + " results[algo] = om.minimize(sphere, params=np.arange(5), algorithm=algo)" + ] + }, + { + "cell_type": "markdown", + "id": "4", + "metadata": {}, + "source": [ + "## Make a single criterion plot" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "5", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.criterion_plot(results[\"scipy_neldermead\"])\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "6", + "metadata": {}, + "source": [ + "## Compare two optimizations in a criterion plot" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.criterion_plot(results)\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "8", + "metadata": {}, + "source": [ + "## Use some advanced options of criterion_plot" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.criterion_plot(\n", + " results,\n", + " # cut off after 180 evaluations\n", + " max_evaluations=180,\n", + " # show only the current best function value\n", + " monotone=True,\n", + ")\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "10", + "metadata": {}, + "source": [ + "## Make a params plot" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "11", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.params_plot(results[\"scipy_neldermead\"])\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "12", + "metadata": {}, + "source": [ + "## Use advanced options of params plot" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "13", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.params_plot(\n", + " results[\"scipy_neldermead\"],\n", + " # cut off after 180 evaluations\n", + " max_evaluations=180,\n", + " # select only the last three parameters\n", + " selector=lambda x: x[2:],\n", + ")\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "id": "14", + "metadata": {}, + "source": [ + "## criterion_plot with multistart optimization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "15", + "metadata": {}, + "outputs": [], + "source": [ + "def alpine(x):\n", + " return np.sum(np.abs(x * np.sin(x) + 0.1 * x))\n", + "\n", + "\n", + "res = om.minimize(\n", + " alpine,\n", + " params=np.arange(7),\n", + " bounds=om.Bounds(soft_lower=np.full(7, -3), soft_upper=np.full(7, 10)),\n", + " algorithm=\"scipy_neldermead\",\n", + " multistart=om.MultistartOptions(n_samples=100, convergence_max_discoveries=3),\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "16", + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.criterion_plot(res, max_evaluations=1000, monotone=True)\n", + "fig.show(renderer=\"png\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/how_to/index.md b/docs/source/how_to/index.md new file mode 100644 index 000000000..8b7cdd37d --- /dev/null +++ b/docs/source/how_to/index.md @@ -0,0 +1,26 @@ +(how-to)= + +# How-to Guides + +How-to Guides show how to achieve specific tasks. In many cases they show you how to use +advanced options. For a more basic introduction, check out the [tutorials](tutorials). + +```{toctree} +--- +maxdepth: 1 +--- +how_to_criterion_function +how_to_start_parameters +how_to_derivatives +how_to_algorithm_selection +how_to_bounds +how_to_constraints +how_to_multistart +how_to_visualize_histories +how_to_specify_algorithm_and_algo_options +how_to_scaling +how_to_logging +how_to_errors_during_optimization +how_to_slice_plot +how_to_benchmarking +``` diff --git a/docs/source/how_to_guides/differentiation/how_to_calculate_first_derivatives.ipynb b/docs/source/how_to_guides/differentiation/how_to_calculate_first_derivatives.ipynb deleted file mode 100644 index 4ad3442b1..000000000 --- a/docs/source/how_to_guides/differentiation/how_to_calculate_first_derivatives.ipynb +++ /dev/null @@ -1,692 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# How to calculate first derivatives\n", - "\n", - "In this guide, we show you how to compute first derivatives with estimagic - while introducing some core concepts." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np\n", - "import pandas as pd" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Introduction\n", - "\n", - "As in the getting started section, let's lookt at the sphere function $$f(x) = x^\\top x.$$" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere_scalar(params):\n", - " return params**2" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The derivative of $f$ is given by $f'(x) = 2 x$. With numerical derivatives, we have to specify the value of $x$ at which we want to compute the derivative. Let's first consider two **scalar** points $x = 0$ and $x=1$. We have $f'(0) = 0$ and $f'(1) = 2$.\n", - "\n", - "To compute the derivative using estimagicm we simply pass the function ``sphere`` and the ``params`` to the function ``first_derivative``:" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array(0.)" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(func=sphere_scalar, params=0)\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array(2.)" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(func=sphere_scalar, params=1)\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Notice that the output of ``first_derivative`` is a dictionary containing the derivative under the key \"derivative\". We discuss the ouput in more detail below." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Gradient and Jacobian\n", - "\n", - "The scalar case from above extends directly to the multivariate case. Let's consider two cases: \n", - "\n", - "| | |\n", - "|:--------|:------------------------------------|\n", - "|Gradient | $f_1: \\mathbb{R}^N \\to \\mathbb{R}$ |\n", - "|Jacobian | $f_2: \\mathbb{R}^N \\to \\mathbb{R}^M$|\n", - "\n", - "\n", - "The first derivative of $f_1$ is usually referred to as the gradient, while the first derivative of $f_2$ is usually called the Jacobian." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Gradient\n", - "\n", - "Let's again use the sphere function, but this time with a vector input. The gradient is a 1-dimensional vector of shape (N,)." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(params):\n", - " return params @ params" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([0., 2., 4., 6.])" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(sphere, params=np.arange(4))\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Jacobian\n", - "\n", - "As an example, let's now use the function\n", - "$$f(x) = (x^\\top x) \\begin{pmatrix}1\\\\2\\\\3 \\end{pmatrix},$$\n", - "with $f: \\mathbb{R}^N \\to \\mathbb{R}^3$. The Jacobian is a 2-dimensional object of shape (M, N), where M is the output dimension." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere_multivariate(params):\n", - " return (params @ params) * np.arange(3)" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[ 0., 0., 0., 0.],\n", - " [ 0., 2., 4., 6.],\n", - " [ 0., 4., 8., 12.]])" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(sphere_multivariate, params=np.arange(4))\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## The output of ``first_derivative``\n", - "\n", - "As we have already seen in the introduction, the output of ``first_derivative`` is a dictionary. This dictionary **always** contains an entry \"derivative\" which is the numerical derivative. Besides this entry, several additional entries may be found, conditional on the state of certain arguments.\n", - "\n", - "**``return_func_value``**\n", - "\n", - "If the argument ``return_func_value`` is ``True``, the output dictionary will contain an additional entry under the key \"func_value\" denoting the function value evaluated at the params vector.\n", - "\n", - "**``return_info``**\n", - "\n", - "If the argument ``return_info`` is ``True``, the output dictionary will contain one to two additional entries. In this case it will always contain the entry \"func_evals\", which is a data frame containing all internally executed function evaluations. And if ``n_steps`` is larger than 1, it will also contain \"derivative_candidates\", which is a data frame containing derivative estimates used in the Richardson extrapolation.\n", - "\n", - "> For an explaination of the argument ``n_steps`` and the Richardson method, please see the API Reference and the Richardson Extrapolation explanation in the documentation.\n", - "\n", - "\n", - "The objects returned when ``return_info`` is ``True`` are rarely of any use directly and can be safely ignored. However, they are necessary data when using the plotting function ``derivative_plot`` as explained below. For better understanding, we print each of these additional objects once:" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [], - "source": [ - "fd = em.first_derivative(\n", - " sphere_scalar, params=0, n_steps=2, return_func_value=True, return_info=True\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "True" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "assert fd[\"func_value\"] == sphere_scalar(0)" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
stepeval
signstep_numberdim_xdim_f
10001.490116e-092.220446e-18
1002.980232e-098.881784e-18
-10001.490116e-092.220446e-18
1002.980232e-098.881784e-18
\n", - "
" - ], - "text/plain": [ - " step eval\n", - "sign step_number dim_x dim_f \n", - " 1 0 0 0 1.490116e-09 2.220446e-18\n", - " 1 0 0 2.980232e-09 8.881784e-18\n", - "-1 0 0 0 1.490116e-09 2.220446e-18\n", - " 1 0 0 2.980232e-09 8.881784e-18" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd[\"func_evals\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
dererr
methodnum_termdim_xdim_f
forward1004.470348e-098.467417e-08
backward100-4.470348e-098.467417e-08
central1000.000000e+000.000000e+00
\n", - "
" - ], - "text/plain": [ - " der err\n", - "method num_term dim_x dim_f \n", - "forward 1 0 0 4.470348e-09 8.467417e-08\n", - "backward 1 0 0 -4.470348e-09 8.467417e-08\n", - "central 1 0 0 0.000000e+00 0.000000e+00" - ] - }, - "execution_count": 12, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd[\"derivative_candidates\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## The ``params`` argument\n", - "\n", - "Above we used a ``numpy.ndarray`` as the ``params`` argument. In estimagic, params can be arbitrary [pytrees](https://jax.readthedocs.io/en/latest/pytrees.html). Examples are (nested) dictionaries of numbers, arrays, and pandas objects. Let's look at a few cases." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### pandas" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
value
categoryname
time_prefdelta0.9
beta0.6
priceprice2.0
\n", - "
" - ], - "text/plain": [ - " value\n", - "category name \n", - "time_pref delta 0.9\n", - " beta 0.6\n", - "price price 2.0" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "params = pd.DataFrame(\n", - " [[\"time_pref\", \"delta\", 0.9], [\"time_pref\", \"beta\", 0.6], [\"price\", \"price\", 2]],\n", - " columns=[\"category\", \"name\", \"value\"],\n", - ").set_index([\"category\", \"name\"])\n", - "\n", - "params" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere_pandas(params):\n", - " return params[\"value\"] @ params[\"value\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "category name \n", - "time_pref delta 1.8\n", - " beta 1.2\n", - "price price 4.0\n", - "dtype: float64" - ] - }, - "execution_count": 15, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(sphere_pandas, params)\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### nested dicts" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'a': 0,\n", - " 'b': 1,\n", - " 'c': 0 2\n", - " 1 3\n", - " 2 4\n", - " dtype: int64}" - ] - }, - "execution_count": 16, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "params = {\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])}\n", - "\n", - "params" - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "metadata": {}, - "outputs": [], - "source": [ - "def dict_sphere(params):\n", - " return params[\"a\"] ** 2 + params[\"b\"] ** 2 + (params[\"c\"] ** 2).sum()" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'a': array(0.),\n", - " 'b': array(2.),\n", - " 'c': 0 4.0\n", - " 1 6.0\n", - " 2 8.0\n", - " dtype: float64}" - ] - }, - "execution_count": 18, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "fd = em.first_derivative(\n", - " func=dict_sphere,\n", - " params=params,\n", - ")\n", - "\n", - "fd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Description of the output\n", - "\n", - "The output of `first_derivative` when using a general pytree is straight-forward. Nevertheless, this explanation requires terminolgy of pytrees. Please refer to the [JAX documentation of pytrees](https://jax.readthedocs.io/en/latest/pytrees.html).\n", - "\n", - "The output tree of `first_derivative` has the same structure as the params tree. Equivalent to the numpy case, where the gradient is a vector of shape `(len(params),)`. If, however, the params tree contains non-scalar entries, like `numpy.ndarray`'s, `pandas.Series`', or `pandas.DataFrame`'s, the output is not expanded but a block is created instead. In the above example, the entry `params[\"c\"]` is a `pandas.Series` with 3 entries. Thus, the first derivative output contains the corresponding 3x1-block of the gradient at the position `[\"c\"]`:" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Multiprocessing\n", - "\n", - "For slow-to-evaluate functions, one may increase computation speed by running the function evaluations in parallel. This can be easily done by setting the ``n_cores`` argument. For example, if we wish to evaluate the function on ``2`` cores, we simply write" - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "metadata": {}, - "outputs": [], - "source": [ - "fd = em.first_derivative(sphere_scalar, params=0, n_cores=2)" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "estimagic", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8 | packaged by conda-forge | (main, Nov 22 2022, 08:27:35) [Clang 14.0.6 ]" - }, - "vscode": { - "interpreter": { - "hash": "e8a16b1bdcc80285313db4674a5df2a5a80c75795379c5d9f174c7c712f05b3a" - } - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/source/how_to_guides/differentiation/how_to_calculate_second_derivatives.ipynb b/docs/source/how_to_guides/differentiation/how_to_calculate_second_derivatives.ipynb deleted file mode 100644 index c782c21ce..000000000 --- a/docs/source/how_to_guides/differentiation/how_to_calculate_second_derivatives.ipynb +++ /dev/null @@ -1,674 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# How to calculate second derivatives\n", - "\n", - "In this guide, we show you how to compute second derivatives with estimagic, while introducing some core concepts." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np\n", - "import pandas as pd" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Introduction\n", - "\n", - "Instead of the sphere function, let's now look at an ellipse $$f(x) = x^\\top W x,$$\n", - "with a weighting matrix $W$.\n", - "\n", - "The second derivative of $f$ is given by $f''(x) = W + W^\\top$. With numerical derivatives, we have to specify the value of $x$ at which we want to compute the derivative. Note that in this case the second derivative should be independent of the value of $x$." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "def ellipse_scalar(params):\n", - " weight = 1\n", - " return weight * params**2" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Let's first consider two **scalar** points $x = 0$ and $x=1$. Since the second derivative here is constant, we have $f''(0) = f''(1) = 2$.\n", - "\n", - "To compute the derivative using estimagic, we simply pass the function ``ellipse_scalar`` and ``params`` to the function ``second_derivative``:" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array(2.)" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(func=ellipse_scalar, params=0)\n", - "sd[\"derivative\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array(1.99999625)" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(func=ellipse_scalar, params=1)\n", - "sd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Notice that the output of ``second_derivative`` is a dictionary containing the derivative under the key \"derivative\". We discuss the ouput in more detail below." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Hessian and Batch-Hessian\n", - "\n", - "The scalar case from above extends directly to the multivariate case. Let's consider two cases: \n", - "\n", - "| | |\n", - "|:--------|:------------------------------------|\n", - "|Hessian | $f_1: \\mathbb{R}^N \\to \\mathbb{R}$ |\n", - "|Batch-Hessian | $f_2: \\mathbb{R}^N \\to \\mathbb{R}^M$|\n", - "\n", - "\n", - "The second derivative of $f_1$ is usually referred to as the Hessian, while the second derivative of $f_2$ is usually called a Batch-Hessian." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Hessian\n", - "\n", - "Let's again use the ellipse function, but this time with a vector input. The hessian is a 2-dimensional object of shape (N, N)." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "def ellipse(params):\n", - " weight = np.arange(len(params) ** 2).reshape(len(params), len(params))\n", - " return params @ weight @ params" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[ 0., 5., 10., 15.],\n", - " [ 5., 10., 15., 20.],\n", - " [10., 15., 20., 25.],\n", - " [15., 20., 25., 30.]])" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(ellipse, params=np.arange(4))\n", - "sd[\"derivative\"].round(2)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Batch-Hessian\n", - "\n", - "As an example let's now use the function\n", - "$$f(x) = (x^\\top x) \\begin{pmatrix}1\\\\2\\\\3 \\end{pmatrix},$$\n", - "with $f: \\mathbb{R}^N \\to \\mathbb{R}^3$. The Batch-Hessian is now a 3-dimensional object of shape (M, N, N), where M is the output dimension." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [], - "source": [ - "def ellipse_multivariate(params):\n", - " weight = np.arange(len(params) ** 2).reshape(len(params), len(params))\n", - " return (params @ weight @ params) * np.arange(3)" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[[ 0., 0., 0., 0.],\n", - " [ 0., 0., 0., 0.],\n", - " [ 0., 0., 0., 0.],\n", - " [ 0., 0., 0., 0.]],\n", - "\n", - " [[ 0., 5., 10., 15.],\n", - " [ 5., 10., 15., 20.],\n", - " [10., 15., 20., 25.],\n", - " [15., 20., 25., 30.]],\n", - "\n", - " [[ 0., 10., 20., 30.],\n", - " [10., 20., 30., 40.],\n", - " [20., 30., 40., 50.],\n", - " [30., 40., 50., 60.]]])" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(ellipse_multivariate, params=np.arange(4))\n", - "sd[\"derivative\"].round(2)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## The output of ``second_derivative``\n", - "\n", - "As we have already seen in the introduction, the output of ``first_derivative`` is a dictionary. This dictionary **always** contains an entry \"derivative\" which is the numerical derivative. Besides this entry, several additional entries may be found, conditional on the state of certain arguments.\n", - "\n", - "**``return_func_value``**\n", - "\n", - "If the argument ``return_func_value`` is ``True``, the output dictionary will contain an additional entry under the key \"func_value\" denoting the function value evaluated at the params vector." - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [], - "source": [ - "sd = em.second_derivative(\n", - " ellipse_scalar, params=0, return_func_value=True, return_info=True\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "True" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "assert sd[\"func_value\"] == ellipse_scalar(0)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## The ``params`` argument\n", - "\n", - "Above we used a ``numpy.ndarray`` as the ``params`` argument. In estimagic, params can be arbitrary [pytrees](https://jax.readthedocs.io/en/latest/pytrees.html). Examples are (nested) dictionaries of numbers, arrays and pandas objects. Lets look at a few cases.\n", - "\n", - "### pandas" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
value
categoryname
time_prefdelta0.9
beta0.6
priceprice2.0
\n", - "
" - ], - "text/plain": [ - " value\n", - "category name \n", - "time_pref delta 0.9\n", - " beta 0.6\n", - "price price 2.0" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "params = pd.DataFrame(\n", - " [[\"time_pref\", \"delta\", 0.9], [\"time_pref\", \"beta\", 0.6], [\"price\", \"price\", 2]],\n", - " columns=[\"category\", \"name\", \"value\"],\n", - ").set_index([\"category\", \"name\"])\n", - "\n", - "params" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [], - "source": [ - "def ellipse_pandas(params):\n", - " weight = np.arange(len(params) ** 2).reshape(len(params), len(params))\n", - " return params[\"value\"] @ weight @ params[\"value\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
categorytime_prefprice
namedeltabetaprice
categoryname
time_prefdelta0.0000004.0000097.999982
beta4.0000097.99965911.999973
priceprice7.99998211.99997315.999964
\n", - "
" - ], - "text/plain": [ - "category time_pref price\n", - "name delta beta price\n", - "category name \n", - "time_pref delta 0.000000 4.000009 7.999982\n", - " beta 4.000009 7.999659 11.999973\n", - "price price 7.999982 11.999973 15.999964" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(ellipse_pandas, params)\n", - "sd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### nested dicts" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'a': 0,\n", - " 'b': 1,\n", - " 'c': 0 2\n", - " 1 3\n", - " 2 4\n", - " dtype: int64}" - ] - }, - "execution_count": 14, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "params = {\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])}\n", - "\n", - "params" - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": {}, - "outputs": [], - "source": [ - "def dict_sphere(params):\n", - " return params[\"a\"] ** 2 + params[\"b\"] ** 2 + (params[\"c\"] ** 2).sum()" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'a': {'a': array(2.00072215),\n", - " 'b': array(0.),\n", - " 'c': 0 0.0\n", - " 1 0.0\n", - " 2 0.0\n", - " dtype: float64},\n", - " 'b': {'a': array(0.),\n", - " 'b': array(1.9999955),\n", - " 'c': 0 0.0\n", - " 1 0.0\n", - " 2 0.0\n", - " dtype: float64},\n", - " 'c': {'a': 0 0.0\n", - " 1 0.0\n", - " 2 0.0\n", - " dtype: float64,\n", - " 'b': 0 0.0\n", - " 1 0.0\n", - " 2 0.0\n", - " dtype: float64,\n", - " 'c': 0 1 2\n", - " 0 1.999995 0.000004 -0.000003\n", - " 1 0.000004 2.000001 0.000000\n", - " 2 -0.000003 0.000000 1.999997}}" - ] - }, - "execution_count": 16, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd = em.second_derivative(\n", - " func=dict_sphere,\n", - " params=params,\n", - ")\n", - "\n", - "sd[\"derivative\"]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Description of the output\n", - "\n", - "The output of `second_derivative` when using a general pytrees looks more complex but is easy once we remember that the second derivative is equivalent to applying the first derivative twice. This explanation requires terminolgy of pytrees. Please refer to the [JAX documentation of pytrees](https://jax.readthedocs.io/en/latest/pytrees.html).\n", - "\n", - "The output tree is a product of the params tree with itself. This is equivalent to the numpy case, where the hessian is a matrix of shape `(len(params), len(params))`. If, however, the params tree contains non-scalar entries like `numpy.ndarray`'s, `pandas.Series`', or `pandas.DataFrame`'s, the output is not expanded but a block is created instead. In the above example, the entry `params[\"c\"]` is a 3-dimensional `pandas.Series`. Thus, the second derivative output contains the corresponding 3x3-block of the hessian at the position `[\"c\"][\"c\"]`:" - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
012
02.00.0-0.0
10.02.00.0
2-0.00.02.0
\n", - "
" - ], - "text/plain": [ - " 0 1 2\n", - "0 2.0 0.0 -0.0\n", - "1 0.0 2.0 0.0\n", - "2 -0.0 0.0 2.0" - ] - }, - "execution_count": 17, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "sd[\"derivative\"][\"c\"][\"c\"].round(3)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Multiprocessing\n", - "\n", - "For slow-to-evaluate functions, one may increase computation speed by running the function evaluations in parallel. This can be easily done by setting the ``n_cores`` argument. For example, if we wish to evaluate the function on ``2`` cores we simply write" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": {}, - "outputs": [], - "source": [ - "sd = em.second_derivative(ellipse_scalar, params=0, n_cores=2)" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "estimagic", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8 | packaged by conda-forge | (main, Nov 22 2022, 08:27:35) [Clang 14.0.6 ]" - }, - "vscode": { - "interpreter": { - "hash": "e8a16b1bdcc80285313db4674a5df2a5a80c75795379c5d9f174c7c712f05b3a" - } - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/source/how_to_guides/differentiation/how_to_plot_derivatives.ipynb b/docs/source/how_to_guides/differentiation/how_to_plot_derivatives.ipynb deleted file mode 100644 index 7e245ffef..000000000 --- a/docs/source/how_to_guides/differentiation/how_to_plot_derivatives.ipynb +++ /dev/null @@ -1,178 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "8430a5c1", - "metadata": {}, - "source": [ - "# How to plot derivatives\n", - "\n", - "In this guide, we show you how to plot numerical derivatives that were calculated using estimagic's `first_derivative` function." - ] - }, - { - "cell_type": "markdown", - "id": "9d8927f1", - "metadata": {}, - "source": [ - "## Why plot your derivatives?\n", - "\n", - "In estimagic, derivatives are mainly used to help in optimization. When an optimization process is stuck, it may be helpful in the debugging procedure to examine the derivative more closely." - ] - }, - { - "cell_type": "markdown", - "id": "d155660a", - "metadata": {}, - "source": [ - "## Univariate functions\n", - "\n", - "The function ``derivative_plot`` works on the dictionary returned by ``first_derivative``. Note that this **requires** ``return_func_value`` and ``return_info`` to be set to True, **and** ``n_steps`` to be larger than 1." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "1c033ff9", - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "b8df45e8", - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(params):\n", - " return params @ params" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "d3578f81", - "metadata": {}, - "outputs": [], - "source": [ - "fd = em.first_derivative(\n", - " func=sphere, params=np.zeros(1), n_steps=4, return_func_value=True, return_info=True\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "0c4f9327", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAAyAAAAH0CAYAAADFQEl4AAAgAElEQVR4XuydB3RVxfbGv/TeK71KCUqRLgJKEVApFkSlyFNRrFjf3woKKKjv2VBRUcTefWChKR0EQSlSBJJQQksgvXf+a0+4IQkpt99z7v1mrSxI7pk9e377BM539uwZt7Nnz54FGwmQAAmQAAmQAAmQAAmQAAnYgYAbBYgdKHMIEiABEiABEiABEiABEiABRYAChDcCCZAACZAACZAACZAACZCA3QhQgNgNNQciARIgARIgARIgARIgARKgAOE9QAIkQAIkQAIkQAIkQAIkYDcCFCB2Q82BSIAESIAESIAESIAESIAEKEB4D5AACZAACZAACZAACZAACdiNAAWI3VBzIBIgARIgARIgARIgARIgAQoQ3gMkQAIkQAIkQAIkQAIkQAJ2I0ABYjfUHIgESIAESIAESIAESIAESIAChPcACZAACZAACZAACZAACZCA3QhQgNgNNQciARIwh8DgwYMxYcIE/Otf/1Ldr7/+ekyaNAljxowxx5zD+zz11FNIT0/Hu+++q3xZuXIlXnvtNSxduhRubm429S8+Ph7Tp0/Hnj174O/vj48++ghxcXFWGfP48eO49tprsWjRInTt2lXZXLZsGd58800kJSWhUaNGuOeee3DDDTeYNF59NnJycjB06FA899xzGD58uEl2eTEJkAAJkIDjCFCAOI49RyYBEjCCQE0BIg+bI0aMQO/evY3orb1LagqQnTt34uuvv8acOXNs7uxNN92EkJAQPPnkk5CHdxEfXl5eVhn3jjvuQHh4OF555RVlb/PmzZg8eTIeeeQR9O/fH3///Tdmz56N//73vxg2bJhRYxpj49tvv8Wrr76KVatWKVHFRgIkQAIkoH0CFCDajxE9JAGXJlBTgOgdRk0BYs/5XHLJJXj55ZeVgLNmS0hIUDaXLFlSmVER8REVFVUpSGS8119/XWV8JNtjTDPGRnFxMfr164fHHnsM48aNM8YsryEBEiABEnAwAQoQBweAw5MACZwnIJmA999/H6dOnUKLFi3w6KOP4j//+Y96sDQswRo4cCDuvPNOTJw4UXWU7//v//4Pq1evVm/By8vLcdlll+GFF17AL7/8opYEpaSkoFWrVnjiiSfUw2pDbdeuXWrMDz/8sPJ6edAdOXKkepv/zDPPNGRC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NF2nLTmDRLb/lSVYsrSNjQRIgARIQB8EKED0ESd6SQIkQAIkQAIkQAIkQAJOQYACxCnCyEmQAAmQAAmQAAmQAAmQgD4IUIDoI070kgRIgARIgARIgARIgAScggAFiFOEkZMgARIgARIgARIgARIgAX0QoADRWJwuuugiyPaUbCRAAiRAAiRAAiRAAiTgjAQoQDQWVQoQjQWE7pAACZAACZAACZAACViVAAWIVXFabowCxHKGtEACJEACJEACJEACJKBdAhQgGosNBYjGAkJ3SIAESIAESIAESIAErEqAAsSqOC03RgFiOUNaIAESIAESIAESIAES0C4BChCNxYYCRGMBoTskQAIkQAIkQAIkQAJWJUABYlWclhujALGcIS2QAAmQAAmQAAmQAAlolwAFiMZiQwGisYDQHRIgARIgARIgARIgAasSoACxKk7LjVGAWM6QFkiABEiABEiABEiABLRLQFcCJC8vD48++qii+e6779ZK9c8//8SECRPg7e1d+fmmTZsQFBSE8vJyvPDCC/j555/h5eWFe+65B+PHj7c4OmvWrMEjjzyCzz//HHFxcZX28vPz8corr+C3336Du7s7nnnmGQwdOrTe8ShALA4HDZAACZAACZAACZCA0xB47733UFRUhAcffNBp5qQbAXLq1ClMnToV3bp1Q3Jycp0CZMWKFdi8eTOee+65C4L07bff4qeffsL7778PEQc333wzXn31VVx88cVmB/TDDz/E6tWrlT0RN1UFiPjbsWNH3HvvvUrwGNMoQIyhxGtIgARIgARIgAScicCyZcvUy1xfX9/Kacn3EydOtPo0N2zYgB49esDPz0/ZfuCBBzB58mR0797damONGDEC8uzq5uambAYEBGDjxo1m2beGACkuLlbPxwMHDlQ+7N27F6+//joWLFhglk+WdtKNAMnNzcWBAwcgAD/++OM6BcgXX3yB9PR03H///RewueOOO9QN1r9/f/XZokWL1M3x5JNPQrIrM2bMwI4dO9QNOX36dPTq1atBvlu2bMGll16K2267Dc8++2ylANm/fz+efvppfP/99w3aqHoBBYhJuHgxCZAACZAACZCAnQhkZmZiyZIlOHLkCLp27YrRo0dbbWQRIL/88gveeustq9mszdDZs2cxduxY9TI6PDxcXbJr1y60adMGgYGBVhtbBMgbb7yBdu3aWWzT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ADFdyOgwCZAACZAACZAACZAACZiXAAWIeWNHz0mABEiABEiABEiABEjAdAQoQEwXMjpMAiRAAiRAAiRAAiRAAuYlQAFi3tjRcxIgARIgARIgARIgARIwHQEKENOFjA6TAAmQAAmQAAmQAAmQgHkJUICYN3b0nARIgARIgARIgARIgARMR4ACxHQho8MkQAIkQAIkQAIkQAIkYF4CFCDmjR09JwESIAESIAESIAESIAHTEaAAMV3I6DAJkAAJkAAJkAAJkAAJmJcABYh5Y0fPSYAEXBB49NFHUVlZiQcffFAbTjr6pA0cOkICJEACJBAyBChAQibUHCgJmIfAxRdfjKuuugpXXnnlCU4fOXIE5557Lj799FP079/f5YB0vNn31Kc//vGPuP766zF48GA11jVr1uDJJ5/Ef/7zH8OD2bovwzugQRIgARIgARI4RoAChJcCCZCAdgReeOEFfP7553j33XdP8O3ll1/GRx99hAULFnTos6c3+x0aNOAAT3yqra3FxIkT8corrzQLEBFgy5cvP0mY+epaW335apPnkwAJkAAJkEB7BChAeG2QAAloRyAnJwfnn3++utnu1atXs3//93//h5/97Ge45pprUFhYiEceeQTr1q1DaWkphg8frn4fMGCAOr7lzf7Bgwfxgx/8ANu2bUNERESzvUGDBmHp0qXo16+f+psInueff17ZHjVqFP70pz8hPT39JD4VFRU477zz8P777+Puu+9GZmamykoMGzYMGzZswJ///Gfs3r1b2ZXXRUi09kl+37JlC/72t7+pnw6HQ2V3xG+73Y5LL71U+ZuQkACbzYaHH35Y+f7YY4+pDJD4VlZWhr/+9a/N/sk4pa8vv/wSXbt2dWs89fX1bfZ14YUX4ttvv1X+yPiSkpIwffp0/Pa3v0V4ePhJTP7+97/jq6++wjvvvIOwsDAIo6lTp2LGjBnqJxsJkAAJkAAJOAlQgPBaIAES0JKATME655xzcMsttyj/5Ib+hz/8IVavXo2UlBTU1dXhww8/VMfExsbioYceQm5uLl566SWvBIjctMtN/dNPP62Ew7x589TNtGRcoqKiTmAkN9djxoxBRkaGmiI1cuRIdcMvgkButkUInXXWWeoG/te//jXmz58PETutMyD79+/Hvn37lJ3q6mr86le/gkw/k5/SRowYgf/+97/NGRARZE4B8t13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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.derivative_plot(fd)\n", - "\n", - "fig = fig.update_layout(width=800, height=500)\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "37abbcc5", - "metadata": {}, - "source": [ - "### Description:\n", - "\n", - "The figure visualizes the function evaluations, the best estimate of the derivative, as well as forward, central and, backward derivative estimates. Forward and backward estimates come with bands that are calculated by applying the standard (forward/backward) formula on the smallest and largest possible steps. **These bands are not confidence intervals**, they shall merely give a rough overview as to where the true derivative may lie." - ] - }, - { - "cell_type": "markdown", - "id": "b6a0ba22", - "metadata": {}, - "source": [ - "## Multivariate functions" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "101c6d0f", - "metadata": {}, - "outputs": [], - "source": [ - "def multivariate(params):\n", - " y1 = params[0] ** 3 + params[1]\n", - " y2 = params[2] ** 2 - params[0]\n", - " return np.array([y1, y2])" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "ed0102c6", - "metadata": {}, - "outputs": [], - "source": [ - "fd = em.first_derivative(\n", - " func=multivariate,\n", - " params=np.zeros(3),\n", - " n_steps=4,\n", - " return_func_value=True,\n", - " return_info=True,\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "b9d37dd0", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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IIAAAggg4BwBEnTnxIqSIoAAAggggAACCCCAAAIIuFiABN3FwaVqCCCAAAIIIIAAAggggAACzhEgQXdOrCgpAggggAACCCCAAAIIIICAiwVI0F0cXKqGAAIIIIAAAggggAACCCDgHAESdOfEipIigAACCCCAAAIIIIAAAgi4WIAE3cXBpWoIIIAAAggggAACCCCAAALOESBBd06sKCkCCCCAAAIIIIAAAggggICLBUjQXRxcqoYAAggggAACCCCAAAIIIOAcARJ058SKkiKAAAIIIIAAAggggAACCLhYgATdxcGlaggggAACCCCAAAIIIIAAAs4RIEF3TqwoKQIIIIAAAggggAACCCCAgIsFSNBdHFyqhgACCCCAAAIIIIAAAggg4BwBEnTnxIqSIoAAAggggAACCCCAAAIIuFiABN3FwaVqCCCAAAIIIIAAAggggAACzhEgQXdOrCgpAggggAACCCCAAAIIIICAiwVI0F0cXKqGAAIIIIAAAggggAACCCDgHAESdOfEipIigAACCCCAAAIIIIAAAgi4WIAE3cXBpWoIIIAAAggggAACCCCAAALOESBBd06sKCkCCCCAAAIIIIAAAggggICLBUjQXRxcqoYAAggggAACCCCAAAIIIOAcARJ058SKkiKAAAIIIIAAAggggAACCLhYgATdxcGlaggggAACCCCAAAIIIIAAAs4RIEF3TqwoKQIIIIAAAggggAACCCCAgIsFSNBdHFyqhgACCCCAAAIIIIAAAggg4BwBEnTnxIqSIoAAAggggAACCCCAAAIIuFiABN3FwaVqCCCAAAIIIIAAAggggAACzhEgQXdOrCgpAggggAACCCCAAAIIIICAiwVI0F0cXKqGAAIIIIAAAggggAACCCDgHAESdOfEipIigAACCCCAAAIIIIAAAgi4WIAE3cXBpWoIIIAAAggggAACCCCAAALOESBBd06sKCkCCCCAAAIIIIAAAggggICLBUjQXRxcqoYAAggggAACCCCAAAIIIOAcARJ058SKkiKAAAIIIIAAAggggAACCLhYgATdxcGlaggggAACCCCAAAIIIIAAAs4RIEF3TqwoKQIIIIAAAggggAACCCCAgIsFSNBdHFyqhgACCCCAAAIIIIAAAggg4BwBEnTnxIqSIoAAAggggAACCCCAAAIIuFiABN3FwaVqCCCAAAIIIIAAAggggAACzhEgQXdOrCgpAggggAACCCCAAAIIIICAiwVI0F0cXKqGAAIIIIAAAggggAACCCDgHAESdOfEipIigAACCCCAAAIIIIAAAgi4WIAE3cXBpWoIIIAAAggggAACCCCAAALOESBBd06sKCkCCCCAAAIIIIAAAggggICLBUjQXRxcqoYAAggggAACCCCAAAIIIOAcARJ058SKkiKAAAIIIIAAAggggAACCLhYgATdxcGlaggggAACCCCAAAIIIIAAAs4RIEF3TqwoKQIIIIAAAggggAACCCCAgIsFSNBdHFyqhgACCCCAAAIIIIAAAggg4BwBEnTnxIqSIoAAAggggAACCCCAAAIIuFiABN3FwaVqCCCAAAIIIIAAAggggAACzhEgQXdOrCgpAggggAACCCCAAAIIIICAiwVI0F0cXKqGAAIIIIAAAggggAACCCDgHAESdOfEipIigAACCCCAAAIIIIAAAgi4WIAE3cXBpWoIIIAAAggggAACCCCAAALOESBBd06sKCkCCCCAAAIIIIAAAggggICLBUjQXRxcqoYAAggggAACCCCAAAIIIOAcARJ058SKkiKAAAIIIIAAAggggAACCLhYgATdxcGlaggggAACCCCAAAIIIIAAAs4RIEF3TqwoKQIIIIAAAggggAACCCCAgIsFSNBdHFyqhgACCCCAAAIIIIAAAggg4BwBEnTnxIqSIoAAAggggAACCCCAAAIIuFiABN3FwaVqCCCAAAIIIIAAAggggAACzhEgQXdOrCgpAggggAACCCCAAAIIIICAiwVI0F0cXKqGAAIIIIAAAggggAACCCDgHAESdOfEipLmkkBsbKx0795devXqZa543333yUMPPST33ntvLpXA2ssMHz5c4uPj5dVXXzUn/uCDD+SFF16Q9957T0JCQqy9WLqzHTx4UEaPHi1ffvmlREREyIIFC+TGG2+05Jo//fSTtG/fXhYuXCi1a9dOPee+ffvk0UcfFY3js88+m+1rvf/++/Liiy/KkSNHpGzZsjJgwADp2LGjOc/p06elVatWMnbsWGnTpk22z80BCCDgLgHaC+vi6cT2QmufWZtDe2HdvcGZEAg2ARL0YIs49c1SIP0DlyZjbdu2lVtuuSXLY+24Q/oEXR8mli5dKpMnTw54cTt37ixFixaVYcOGmeRWk/MCBQpYct1H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lZMFqwlrmnNL2EWA9sIukaAcCCCAAAIIWCdAgm6dpSVn4oHLEkZOgoBlAqxpbhklJ7JYgPbCYlBOhwACCCCAgA0ESNBtEIS0ReCBy2YBoThBK8Ca5kEbesdUnPbCMaGioAgggAACCPgsQILuM1Xu7MgDV+44cxUEMhPwdU3zIpdOyu8/75Jho0aBiUCeCNBe5Ak7F0UAAQQQQCCgAq5I0F966SV5+eWXJV++fAarWrVqsnz58qvgUlJSZOLEibJ27Vqz/M2AAQOkW7duZj+dmVmXxdElc6Kjo2XSpElSr169HOEvXLhQXn/9dblw4YLcddddZtZfTxkzOzEPXDki52AEciTg65rmBRP3ybGEX2XQ44PM8lxsCOSFAO1FXqhzTQQQQAABBAIr4IoEffz48WZt2rZt23rV0qRd17t97bXXJCkpSbp06SIzZsyQGjVqyNNPP22W3Bk0aJBJ0vXP9evXS6FChfyKwCeffGKS/DfeeMOsiavr5Orau7169fJ6Ph64/OLmIARyJMCa5jni4+A8EqC9yCN4LosAAggggEAABVyRoGsy3b17d5Oke9t0HduePXumrlerPdxHjx6VoUOHSv369WXHjh0SHh5uTqG96506dZIWLVqIrms7ZswY2bt3r/l89OjR0rBhQ6/Xmjp1qlx33XXStWtXs9/XX39t1ttdtWoVCXoAb2hOjUB2BHRUzYb31su3vxVlTfPswLGvLQRI0G0RBgqBAAIIIICApQKuSND79Okj33//vVy8eFHKlCkjTzzxhDRq1OgqqNjYWFm0aJHpKddt69at5u8TJkwwvelbtmxJPWb69Olm6KqeW5PzwoULmyHwhw4dMkm+9q5HRkZmGgzt1b/pppukY8eOZp9Tp05J8+bNTZLvbeOBy9L7m5MhkKnAN1/ul12fHZOTodGsac594kgB2gtHho1CI4AAAggg4FXAFQn6uXPnzLvd+fPnl08//VQef/xxeffdd6Vs2bJXVL5x48ayevVqKVGihPm57jtz5kwzFF2HoK9bty51/1mzZon2rmnvfN26dWXz5s1StGhR87m+tz5w4EA5cOCArFy58irgxYsXy86dO+Wf//ynzJkzx3yuPep67T179qTur+/Dp9+0V//gwYPctgggECABXdP8wzVb5cfksletaV66XAW5r9sQqXJjAymRckIaN46RylWrB6gk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LSWztwABur3rx9a544XL1tWTpczxwpUlPltfzAtX2gF6t27dzFxwz1DzCRMmmCBd54Hrqu66CJweuuJ6//79ZevWraYXfcSIEd7V3nVIuw49V2cd1q3D3bWH3FePuqap+62PHz9edA59vXr1zFB6p0xD8OeBp73wR8mZ59BeOLPe/Mk17YU/SpyDgPUCBOjWm4ZMirxwubeqeeFyb93ywuXeurVzyWgv7Fw7Wcsb7UXW/Ox8Ne2FnWuHvLlZgADdzbUb4LLpgkkVK1aUChUqBPhOJB9sAV0QS+ega28ih7sEdEj2Dz/8YLYK40AgWAK0F8GSDv59aC+Cbx6sO9JeBEua+yBwrQABOk8EAggggAACCCCAAAIIIIAAAjYQIEC3QSWQBQQQQAABBBBAAAEEEEAAAQQI0HkGEEAAAQQQQAABBBBAAAEEELCBAAG6DSqBLCCAAAIIIIAAAggggAACCCBAgM4zgAACCCCAAAIIIIAAAggggIANBAjQbVAJ2ZWFAwcOSPfu3c1qzp07d041G/Hx8fL888+LruRZsGBBszdvtWrVzLn6s3/+85/y66+/Srly5eRf//qXFClSJNPF+eOPP2TIkCGyfft2SUpKkoYNG8qgQYMkR44cmU4zVC70ty58naf7PU+ePNns3dy4cWMZOXKkhIeHZ5rQ17OT6URD9MK1a9fKc889J/PmzZPy5cunquCrbv19Pvzl5XfVXyn3nEd74Z669PffA9oLZ9Y57YUz641cI5BcgAA9RJ+HzZs3mwDstttukypVqqQZoPfr10+KFy8uvXv3NgG5/rly5UrJlSuXCeJGjBghdevWlTlz5simTZvkrbfeyrTom2++KYcOHZIXX3xRLl26JF26dJG//e1v8uCDD2Y6zVC48MqVK37Vha/z9u/fL4899pi899575kuWvn37SuXKleWJJ57wi/DYsWOSO3duiY2N9Z6f1rOj53H4LzBjxgxZs2aNnDt3TkaPHp1qgO6rbv19PvzPkQi/qxnRcv65tBfOr0NPCfz994D2wpl1TnvhzHoj1wikFCBAD9FnYs+ePZIvXz4TkOXPnz/VAF17satXry4bN26UPHnyGKmePXtK69atpVChQjJq1ChZsGCB+bmee88998iqVatMutrbor3fx48fNwH++PHjpWjRoj619Zy4uDh5/PHHzXka/N95553mfhxp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J+Hdd99V7Yq3Rbzf1dXVSuA/8sgjGDhwYJe0pc6AAQNw+eWXq3oi/o899lh1P5bOCaxdu7ZLW0Su7Kreyy+/jIaGBoiolrJhwwbcdtttePPNN9XvchbqY489BrfbjRNPPFHZxm63Rzv1+9//HiNGjIh+mdLVs3PaaafRnHEQEHE0adIk9Xdx5513dijQu7Lttm3bunw+urNtR13l32ocBsyAqpwvMsCIrUPgfJE5tuxoJJwvMtu+HF32EKBAzx5bdzjSxx9/HH369OlQoItXVLa/ywI+UkSkiZdUvKziMZeFeqR8//vfx1133YXx48fjnHPOwa233opTTjlFifi///3vWLBgQZe0KyoqlNf8xz/+MZqamtQ1Tz/9NHJzc7PcSl0P/6233urUFscdd1z04q7qyRc18mXMeeedp+p7PB71+/r161FVVYXZs2fjf//3f9WXLLfccguOPvpoFR4RKe0FelfPztVXX017JkDgwgsvxN13392hQO/KtrI7orO/1b59+3Zr2466yr/VBAyYAZdwvkh/I3K+SH8bxjICzhexUGIdEjAuAQp049omqZ59/PHHuO+++45oQ2LGp0+fHn2/qwWXeMHnzZuHt99+O1r/ySefVN5y8XR/+eWXapt8pFx66aW47rrrUFhYqGLTFy1apD7y+/0QoSjf3ItoF29M2zJ06FD87ne/QygUwqOPPqruV1tbq7x+IvRZuiYgwrkzW0ybNi16cVf1/vznP+P000/H2WefHa0v4Q9fffUVFi5ciD179uCOO+5Qn3300UcqVl287pdcconKQVBXV6fCHvLy8pS3V56bzp4dCZNgiZ9AVwuurmy7c+fOTp8P2SnRkW2fe+65DneuyN+jfDHDv9X47WfkKzhfGNk6evvG+UIvT6O2xvnCqJZhv0ggNgIU6LFxythaXQl02Z5+/vnnY+XKldHxS5K4srIyJdBXrFihEsNFyrnnnqu+FJDkYCLCpE6k1NfXY8mSJRCPXWdF+iJCT7yEBw8exE9+8hMVg/7d7343Y/nrGJh8EdKZLSZMmBC9RVf1RKBLXfGUS5EdDCLuP//8czz88MN44403VCiEFIlNlF0UklQuUtp70Lt6dq655hodw866NrpacHVlWxHonT0fskulO9t2BJp/q1n3+KkBc75If7tzvkh/G8YyAs4XsVBiHRIwLgEKdOPapkd6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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.derivative_plot(fd)\n", - "\n", - "fig = fig.update_layout(height=1000, width=1000)\n", - "fig.show(renderer=\"png\")" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/source/how_to_guides/differentiation/index.md b/docs/source/how_to_guides/differentiation/index.md deleted file mode 100644 index c97a1a5bf..000000000 --- a/docs/source/how_to_guides/differentiation/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# Differentiation - -```{toctree} ---- -maxdepth: 1 ---- -how_to_calculate_first_derivatives -how_to_calculate_second_derivatives -how_to_plot_derivatives -``` diff --git a/docs/source/how_to_guides/index.md b/docs/source/how_to_guides/index.md deleted file mode 100644 index 4d9f4d081..000000000 --- a/docs/source/how_to_guides/index.md +++ /dev/null @@ -1,118 +0,0 @@ -# How-to Guides - -How-to Guides show how to achieve specific tasks that potentially require to use -advanced options of estimagic functions. If you are completely new to estimagic and want -an introduction to its basic functionality, check out our tutorials. - -`````{grid} 1 2 2 2 ---- -gutter: 3 ---- -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/optimization.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} optimization/index.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Optimization -``` - -Learn how to use constraints, parallelize function evaluations, and configure every aspect of your optimization. - -```` - -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/differentiation.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} differentiation/index.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Differentiation -``` - -Learn how to influence step sizes, parallelize function evaluations, and use advanced options for numerical differentiation. - -```` - -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/bullseye.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} inference/index.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Estimation -``` - -Learn how to calculate different types of standard errors and do sensitivity analysis. - -```` - -````{grid-item-card} -:text-align: center -:img-top: ../_static/images/miscellaneous.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} miscellaneous/index.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Miscellaneous -``` - -Learn how to create publication quality LaTeX tables, use custom batch evaluators, and check out the FAQ. - -```` - -````{grid-item-card} -:text-align: center -:columns: 12 -:img-top: ../_static/images/video.svg -:class-img-top: index-card-image -:shadow: md - -```{button-link} ../videos.html ---- -click-parent: -ref-type: ref -class: stretched-link index-card-link sd-text-primary ---- -Videos -``` - -Collection of tutorials, talks, and screencasts on estimagic. - -```` - -````` - -```{toctree} ---- -hidden: true -maxdepth: 1 ---- -optimization/index -differentiation/index -inference/index -miscellaneous/index -``` diff --git a/docs/source/how_to_guides/inference/how_to_calculate_likelihood_standard_errors.ipynb b/docs/source/how_to_guides/inference/how_to_calculate_likelihood_standard_errors.ipynb deleted file mode 100644 index 12e507700..000000000 --- a/docs/source/how_to_guides/inference/how_to_calculate_likelihood_standard_errors.ipynb +++ /dev/null @@ -1,37 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# How to calculate standard errors for likelihood models" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "(to be written.)\n", - "\n", - "In case of an urgent request for this guide, feel free to open an issue \n", - "[here](https://github.com/OpenSourceEconomics/estimagic/issues)." - ] - } - ], - "metadata": { - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.9.13" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/source/how_to_guides/inference/how_to_calculate_msm_standard_errors.ipynb b/docs/source/how_to_guides/inference/how_to_calculate_msm_standard_errors.ipynb deleted file mode 100644 index 47e3d311c..000000000 --- a/docs/source/how_to_guides/inference/how_to_calculate_msm_standard_errors.ipynb +++ /dev/null @@ -1,37 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# How to calculate standard errors for method of simulated moments" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "(to be written.)\n", - "\n", - "In case of an urgent request for this guide, feel free to open an issue \n", - "[here](https://github.com/OpenSourceEconomics/estimagic/issues)." - ] - } - ], - "metadata": { - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.9.13" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/source/how_to_guides/inference/how_to_do_bootstrap_inference.ipynb b/docs/source/how_to_guides/inference/how_to_do_bootstrap_inference.ipynb deleted file mode 100644 index d1305c37a..000000000 --- a/docs/source/how_to_guides/inference/how_to_do_bootstrap_inference.ipynb +++ /dev/null @@ -1,861 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Bootstrap Tutorial\n", - "\n", - "This notebook contains a tutorial on how to use the bootstrap functionality provided by estimagic. We start with the simplest possible example of calculating standard errors and confidence intervals for an OLS estimator without as well as with clustering. Then we progress to more advanced examples.\n", - "\n", - "In the example here, we will work with the \"exercise\" example dataset taken from the seaborn library.\n", - "\n", - "The working example will be a linear regression to investigate the effects of exercise time on pulse." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np\n", - "import pandas as pd\n", - "import seaborn as sns\n", - "import statsmodels.api as sm" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Prepare the dataset" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
iddietpulsetimekindconstant
01low fat851rest1
11low fat8515rest1
21low fat8830rest1
32low fat901rest1
42low fat9215rest1
\n", - "
" - ], - "text/plain": [ - " id diet pulse time kind constant\n", - "0 1 low fat 85 1 rest 1\n", - "1 1 low fat 85 15 rest 1\n", - "2 1 low fat 88 30 rest 1\n", - "3 2 low fat 90 1 rest 1\n", - "4 2 low fat 92 15 rest 1" - ] - }, - "execution_count": 2, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "df = sns.load_dataset(\"exercise\", index_col=0)\n", - "replacements = {\"1 min\": 1, \"15 min\": 15, \"30 min\": 30}\n", - "df = df.replace({\"time\": replacements})\n", - "df[\"constant\"] = 1\n", - "\n", - "df.head()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Doing a very simple bootstrap" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The first thing we need is a function that calculates the bootstrap outcome, given an empirical or re-sampled dataset. The bootstrap outcome is the quantity for which you want to calculate standard errors and confidence intervals. In most applications those are just parameter estimates.\n", - "\n", - "In our case, we want to regress \"pulse\" on \"time\" and a constant. Our outcome function looks as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [], - "source": [ - "def ols_fit(data):\n", - " y = data[\"pulse\"]\n", - " x = data[[\"constant\", \"time\"]]\n", - " params = sm.OLS(y, x).fit().params\n", - "\n", - " return params" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In general, the user-specified outcome function may return any pytree (e.g. numpy.ndarray, pandas.DataFrame, dict etc.). In the example here, it returns a pandas.Series." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now we are ready to calculate confidence intervals and standard errors." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(constant 90.858983\n", - " time 0.151361\n", - " dtype: float64,\n", - " constant 96.880057\n", - " time 0.654426\n", - " dtype: float64)" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "results_without_cluster = em.bootstrap(data=df, outcome=ols_fit)\n", - "results_without_cluster.ci()" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "constant 1.548116\n", - "time 0.126410\n", - "dtype: float64" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "results_without_cluster.se()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The above function call represents the minimum that a user has to specify, making full use of the default options, such as drawing a 1_000 bootstrap draws, using the \"percentile\" bootstrap confidence interval, not making use of parallelization, etc.\n", - "\n", - "If, for example, we wanted to take 10_000 draws, while parallelizing on two cores, and using a \"bc\" type confidence interval, we would simply call the following:" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(constant 91.309379\n", - " time 0.192349\n", - " dtype: float64,\n", - " constant 96.286624\n", - " time 0.607616\n", - " dtype: float64)" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "results_without_cluster2 = em.bootstrap(\n", - " data=df, outcome=ols_fit, n_draws=10_000, n_cores=2\n", - ")\n", - "\n", - "results_without_cluster2.ci(ci_method=\"bc\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Doing a clustered bootstrap" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In the cluster robust variant of the bootstrap, the original dataset is divided into clusters according to the values of some user-specified variable, and then clusters are drawn uniformly with replacement in order to create the different bootstrap samples. \n", - "\n", - "In order to use the cluster robust boostrap, we simply specify which variable to cluster by. In the example we are working with, it seems sensible to cluster on individuals, i.e. on the column \"id\" of our dataset." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "constant 1.185239\n", - "time 0.101723\n", - "dtype: float64" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "results_with_cluster = em.bootstrap(data=df, outcome=ols_fit, cluster_by=\"id\")\n", - "\n", - "results_with_cluster.se()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We can see that the estimated standard errors are indeed of smaller magnitude when we use the cluster robust bootstrap. \n", - "\n", - "Finally, we can compare our bootstrap results to a regression on the full sample using statsmodels' OLS function.\n", - "We see that the cluster robust bootstrap yields standard error estimates very close to the ones of the cluster robust regression, while the regular bootstrap seems to overestimate the standard errors of both coefficients.\n", - "\n", - "**Note**: We would not expect the asymptotic statsmodels standard errors to be exactly the same as the bootstrapped standard errors.\n" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " OLS Regression Results \n", - "==============================================================================\n", - "Dep. Variable: pulse R-squared: 0.096\n", - "Model: OLS Adj. R-squared: 0.086\n", - "Method: Least Squares F-statistic: 13.75\n", - "Date: Sat, 14 Jan 2023 Prob (F-statistic): 0.000879\n", - "Time: 17:54:58 Log-Likelihood: -365.51\n", - "No. Observations: 90 AIC: 735.0\n", - "Df Residuals: 88 BIC: 740.0\n", - "Df Model: 1 \n", - "Covariance Type: cluster \n", - "==============================================================================\n", - " coef std err z P>|z| [0.025 0.975]\n", - "------------------------------------------------------------------------------\n", - "constant 93.7611 1.205 77.837 0.000 91.400 96.122\n", - "time 0.3873 0.104 3.708 0.000 0.183 0.592\n", - "==============================================================================\n", - "Omnibus: 20.828 Durbin-Watson: 0.827\n", - "Prob(Omnibus): 0.000 Jarque-Bera (JB): 26.313\n", - "Skew: 1.173 Prob(JB): 1.93e-06\n", - "Kurtosis: 4.231 Cond. No. 31.7\n", - "==============================================================================\n", - "\n", - "Notes:\n", - "[1] Standard Errors are robust to cluster correlation (cluster)\n" - ] - } - ], - "source": [ - "y = df[\"pulse\"]\n", - "x = df[[\"constant\", \"time\"]]\n", - "\n", - "\n", - "cluster_robust_ols = sm.OLS(y, x).fit(cov_type=\"cluster\", cov_kwds={\"groups\": df[\"id\"]})" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Splitting up the process" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In many situations, the above procedure is enough. However, sometimes it may be important to split the bootstrapping process up into smaller steps. Examples for such situations are:\n", - "\n", - "1. You want to look at the bootstrap estimates\n", - "2. You want to do a bootstrap with a low number of draws first and add more draws later without duplicated calculations\n", - "3. You have more bootstrap outcomes than just the parameters\n", - "\n", - "### 1. Accessing bootstrap outcomes\n", - "\n", - "The bootstrap outcomes are stored in the results object you get back when calling the bootstrap function. " - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[constant 93.732040\n", - " time 0.580057\n", - " dtype: float64,\n", - " constant 92.909468\n", - " time 0.309198\n", - " dtype: float64,\n", - " constant 94.257886\n", - " time 0.428624\n", - " dtype: float64,\n", - " constant 93.872576\n", - " time 0.410508\n", - " dtype: float64,\n", - " constant 92.076689\n", - " time 0.542170\n", - " dtype: float64]" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "result = em.bootstrap(data=df, outcome=ols_fit, seed=1234)\n", - "my_outcomes = result.outcomes\n", - "\n", - "my_outcomes[:5]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "To further compare the cluster bootstrap to the uniform bootstrap, let's plot the sampling distribution of the parameters on time. We can again see that the standard error is smaller when we cluster on the subject id. " - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [], - "source": [ - "result_clustered = em.bootstrap(data=df, outcome=ols_fit, seed=1234, cluster_by=\"id\")\n", - "my_outcomes_clustered = result_clustered.outcomes" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "# clustered distribution in blue\n", - "sns.histplot(\n", - " pd.DataFrame(my_outcomes_clustered)[\"time\"], kde=True, stat=\"density\", linewidth=0\n", - ")\n", - "\n", - "# non-clustered distribution in orange\n", - "sns.histplot(\n", - " pd.DataFrame(my_outcomes)[\"time\"],\n", - " kde=True,\n", - " stat=\"density\",\n", - " linewidth=0,\n", - " color=\"orange\",\n", - ");" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Calculating standard errors and confidence intervals from existing bootstrap result" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "If you've already run ``bootstrap`` once, you can simply pass the existing result object to a new call of ``bootstrap``. Estimagic reuses the existing bootstrap outcomes and now only draws ``n_draws`` - ``n_existing`` outcomes instead of drawing entirely new ``n_draws``. Depending on the ``n_draws`` you specified (this is set to 1_000 by default), this may save considerable computation time. \n", - "\n", - "We can go on and compute confidence intervals and standard errors, just the same way as before, with several methods (e.g. \"percentile\" and \"bc\"), yet without duplicated evaluations of the bootstrap outcome function. " - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(constant 90.709236\n", - " time 0.151193\n", - " dtype: float64,\n", - " constant 96.827145\n", - " time 0.627507\n", - " dtype: float64)" - ] - }, - "execution_count": 12, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "my_results = em.bootstrap(\n", - " data=df,\n", - " outcome=ols_fit,\n", - " existing_result=result,\n", - ")\n", - "my_results.ci(ci_method=\"t\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You can use this to calculate confidence intervals with several methods (e.g. \"percentile\" and \"bc\") without duplicated evaluations of the bootstrap outcome function." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 2. Extending bootstrap results with more draws\n", - "\n", - "It is often the case that, for speed reasons, you set the number of bootstrap draws quite low, so you can look at the results earlier and later decide that you need more draws. \n", - "\n", - "In the long run, we will offer a Dashboard integration for this. For now, you can do it manually.\n", - "\n", - "As an example, we will take an initial sample of 500 draws. We then extend it with another 1500 draws. \n", - "\n", - "*Note*: It is very important to use a different random seed when you calculate the additional outcomes!!!" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(constant 90.768859\n", - " time 0.137692\n", - " dtype: float64,\n", - " constant 96.601067\n", - " time 0.607616\n", - " dtype: float64)" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "initial_result = em.bootstrap(data=df, outcome=ols_fit, seed=5471, n_draws=500)\n", - "initial_result.ci(ci_method=\"t\")" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(constant 90.689112\n", - " time 0.128597\n", - " dtype: float64,\n", - " constant 96.696522\n", - " time 0.622954\n", - " dtype: float64)" - ] - }, - "execution_count": 14, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "combined_result = em.bootstrap(\n", - " data=df, outcome=ols_fit, existing_result=initial_result, seed=2365, n_draws=2000\n", - ")\n", - "combined_result.ci(ci_method=\"t\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 3. Using less draws than totally available bootstrap outcomes" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You have a large sample of bootstrap outcomes but want to compute summary statistics only on a subset? No problem! Estimagic got you covered. You can simply pass any number of ``n_draws`` to your next call of ``bootstrap``, regardless of the size of the existing sample you want to use. We already covered the case where ``n_draws`` > ``n_existing`` above, in which case estimagic draws the remaining bootstrap outcomes for you.\n", - "\n", - "If ``n_draws`` <= ``n_existing``, estimagic takes a random subset of the existing outcomes - and voilà! " - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(constant 90.619182\n", - " time 0.130242\n", - " dtype: float64,\n", - " constant 96.557777\n", - " time 0.625645\n", - " dtype: float64)" - ] - }, - "execution_count": 15, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "subset_result = em.bootstrap(\n", - " data=df, outcome=ols_fit, existing_result=combined_result, seed=4632, n_draws=500\n", - ")\n", - "subset_result.ci(ci_method=\"t\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Accessing the bootstrap samples" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "It is also possible to just access the bootstrap samples. You may do so, for example, if you want to calculate your bootstrap outcomes in parallel in a way that is not yet supported by estimagic (e.g. on a large cluster or super-computer)." - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
iddietpulsetimekindconstant
8830no fat11115running1
8730no fat991running1
8830no fat11115running1
3412low fat10315walking1
156no fat831rest1
.....................
7827no fat1001running1
7726no fat14330running1
8730no fat991running1
2910no fat10030rest1
7526no fat951running1
\n", - "

90 rows × 6 columns

\n", - "
" - ], - "text/plain": [ - " id diet pulse time kind constant\n", - "88 30 no fat 111 15 running 1\n", - "87 30 no fat 99 1 running 1\n", - "88 30 no fat 111 15 running 1\n", - "34 12 low fat 103 15 walking 1\n", - "15 6 no fat 83 1 rest 1\n", - ".. .. ... ... ... ... ...\n", - "78 27 no fat 100 1 running 1\n", - "77 26 no fat 143 30 running 1\n", - "87 30 no fat 99 1 running 1\n", - "29 10 no fat 100 30 rest 1\n", - "75 26 no fat 95 1 running 1\n", - "\n", - "[90 rows x 6 columns]" - ] - }, - "execution_count": 16, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "from estimagic.inference import get_bootstrap_samples\n", - "\n", - "rng = np.random.default_rng(1234)\n", - "my_samples = get_bootstrap_samples(data=df, rng=rng)\n", - "my_samples[0]" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "kernelspec": { - "display_name": "estimagic", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8 | packaged by conda-forge | (main, Nov 22 2022, 08:27:35) [Clang 14.0.6 ]" - }, - "vscode": { - "interpreter": { - "hash": "e8a16b1bdcc80285313db4674a5df2a5a80c75795379c5d9f174c7c712f05b3a" - } - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/source/how_to_guides/inference/index.md b/docs/source/how_to_guides/inference/index.md deleted file mode 100644 index 8f3231ca4..000000000 --- a/docs/source/how_to_guides/inference/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# Inference - -```{toctree} ---- -maxdepth: 1 ---- -how_to_calculate_likelihood_standard_errors -how_to_calculate_msm_standard_errors -how_to_do_bootstrap_inference -``` diff --git a/docs/source/how_to_guides/miscellaneous/faq.md b/docs/source/how_to_guides/miscellaneous/faq.md deleted file mode 100644 index 48cdffbb5..000000000 --- a/docs/source/how_to_guides/miscellaneous/faq.md +++ /dev/null @@ -1,33 +0,0 @@ -# Frequently Asked Questions - -**Question**: I used a covariance constraint but my covariance matrix is not positive -definite. - -**Answer**: `covariance` and `sdcorr` constraints can only ensure positive -semi-definiteness and there are valid covariance matrices that are not positive -definite. If your covariance matrix is very ill conditioned, e.g. if some variances are -very large and some are very small, the constraints might even fail to ensure -semi-definiteness, due to numerical error. - -There are several ways to deal with this: - -If you only need positive definiteness to do a cholesky decomposition, you can use -{func}`~estimagic.utilities.robust_cholesky`, which can also decompose semi-definite and -slightly indefinite matrices. - -If you really need positive definiteness for some other reason, you can construct a -penalty. {func}`~estimagic.utilities.robust_cholesky` can optionally return all -information you need to construct such a penalty term. - -Finally, if the real problem is just that your covariance matrix is ill conditioned, you -can rescale some variables to make all variances approximately the same order of -magnitude. - -______________________________________________________________________ - -**Question**: I want to re-run the Azure Pipelines test suite because some random error -occurred, e.g., a HTPT timeout error. - -**Answer**: Starting from the Github page of the PR, select the tab called "Checks". In -the upper right corner you find a button to re-run all checks. In a column on the -left-hand-side you can re-run tests for individual platforms. diff --git a/docs/source/how_to_guides/miscellaneous/how_to_use_batch_evaluators.ipynb b/docs/source/how_to_guides/miscellaneous/how_to_use_batch_evaluators.ipynb deleted file mode 100644 index c1089f56a..000000000 --- a/docs/source/how_to_guides/miscellaneous/how_to_use_batch_evaluators.ipynb +++ /dev/null @@ -1,42 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# How to use batch evaluators" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "(to be written.)\n", - "\n", - "In case of an urgent request for this guide, feel free to open an issue \n", - "[here](https://github.com/OpenSourceEconomics/estimagic/issues)." - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/source/how_to_guides/miscellaneous/how_to_visualize_and_interpret_sensitivity_measures.ipynb b/docs/source/how_to_guides/miscellaneous/how_to_visualize_and_interpret_sensitivity_measures.ipynb deleted file mode 100644 index cc23f63fe..000000000 --- a/docs/source/how_to_guides/miscellaneous/how_to_visualize_and_interpret_sensitivity_measures.ipynb +++ /dev/null @@ -1,39 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "hollow-buffalo", - "metadata": {}, - "source": [ - "# How to visualize and interpret sensitivity measures" - ] - }, - { - "cell_type": "markdown", - "id": "501fad6b", - "metadata": {}, - "source": [ - "(to be written.)\n", - "\n", - "In case of an urgent request for this guide, feel free to open an issue \n", - "[here](https://github.com/OpenSourceEconomics/estimagic/issues)." - ] - } - ], - "metadata": { - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.9.13" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/source/how_to_guides/miscellaneous/index.md b/docs/source/how_to_guides/miscellaneous/index.md deleted file mode 100644 index fe04c5b6a..000000000 --- a/docs/source/how_to_guides/miscellaneous/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# Miscellaneous Topics - -```{toctree} - ---- -maxdepth: 1 ---- -how_to_generate_publication_quality_tables -how_to_use_batch_evaluators -how_to_visualize_and_interpret_sensitivity_measures - -faq -``` diff --git a/docs/source/how_to_guides/optimization/how_to_benchmark_optimization_algorithms.ipynb b/docs/source/how_to_guides/optimization/how_to_benchmark_optimization_algorithms.ipynb deleted file mode 100644 index f14a2fcae..000000000 --- a/docs/source/how_to_guides/optimization/how_to_benchmark_optimization_algorithms.ipynb +++ /dev/null @@ -1,687 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "6be356db", - "metadata": {}, - "source": [ - "# How to Benchmark Optimization Algorithms\n", - "\n", - "Benchmarking optimization algorithms is an important step when developing a new algorithm or when searching for an algorithm that is good at solving a particular problem. \n", - "\n", - "In general, benchmarking constists of the following steps:\n", - "\n", - "1. Define the test problems (or get pre-implemented ones)\n", - "2. Define the optimization algorithms and the tuning parameters you want to try\n", - "3. Run the benchmark\n", - "4. Plot the results\n", - "\n", - "Estimagic helps you with all of these steps!" - ] - }, - { - "cell_type": "markdown", - "id": "8671802f", - "metadata": {}, - "source": [ - "## 1. Get Test Problems\n", - "\n", - "Estimagic includes the problems of [Moré and Wild (2009)](https://doi.org/10.1137/080724083) as well as [Cartis and Roberts](https://arxiv.org/abs/1710.11005).\n", - "\n", - "Each problem consist of the `inputs` (the criterion function and the start parameters) and the `solution` (the optimal parameters and criterion value) and optionally provides more information.\n", - "\n", - "Below we load a subset of the Moré and Wild problems and look at one particular Rosenbrock problem that has difficult start parameters." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "83c2f8e4", - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "c3640855", - "metadata": {}, - "outputs": [], - "source": [ - "problems = em.get_benchmark_problems(\"example\")" - ] - }, - { - "cell_type": "markdown", - "id": "c628b987", - "metadata": {}, - "source": [ - "## 2. Specify the Optimizers\n", - "\n", - "To select optimizers you want to benchmark on the set of problems, you can simply specify them as a list. Advanced examples - that do not only compare algorithms but also vary the `algo_options` - can be found below. " - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "2340cd3a", - "metadata": {}, - "outputs": [], - "source": [ - "optimizers = [\n", - " \"nag_dfols\",\n", - " \"scipy_neldermead\",\n", - " \"scipy_truncated_newton\",\n", - "]" - ] - }, - { - "cell_type": "markdown", - "id": "9703f954", - "metadata": {}, - "source": [ - "## 3. Run the Benchmark\n", - "\n", - "Once you have your problems and your optimizers set up, you can simply use `run_benchmark`. The results are a dictionary with one entry for each (problem, algorithm) combination. Each entry not only saves the solution but also the history of the algorithm's criterion and parameter history. " - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "f0ef15da", - "metadata": {}, - "outputs": [], - "source": [ - "results = em.run_benchmark(\n", - " problems,\n", - " optimizers,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "61c365ab", - "metadata": {}, - "source": [ - "## 4a. Profile plots\n", - "\n", - "**Profile Plots** compare optimizers over a whole problem set. \n", - "\n", - "The literature distinguishes **data profiles** and **performance profiles**. Data profiles use a normalized runtime measure whereas performance profiles use an absolute one. The profile plot does not normalize runtime by default. To do this, simply set `normalize_runtime` to True. For background information, check [Moré and Wild (2009)](https://doi.org/10.1137/080724083). " - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "07918672", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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WBJ18L59+3rKvXbt2n7JFi1a2NixY61evXr+86xZs2zSpEku6O3atTMcgGD8W82aNa179+7/xHT/tddYsmSJN7bBkbp4VNBXr15dKlcEnXo7jXDByKIMHjzYmjRp8q/loYmLgAiUTkCCrrtjswksWrTI+vTp4//f87322it1fo8ePaxjx46puviYMWMM0SFV3LRpU5s9e7ZVr17dj+/WrZsfS+OWrHQCo0eP9ka2ypUr+0Hr1q2z9evXW/369f1tgtK41qlTx7lPnz49dV6zZs18Dyh1yERABJJHQIKevD2t0BURMZL6HTFihDVo0KDEtWbMmGFTpkxJdbl36NDBhg4d6qLTv39/j8h79+7tXe6k4GnQqlatWoXON2mDRyN01lYa16pVq1qrVq28WZEmRbrc4T1hwoSkIdF6REAE/ktAgq5bYbMIEJkTGYaIkZOrVKniIo0NGzbMRb1SpUrekR2a3tauXesp+nnz5nmUzutUoRt+syZQ5AenC3pZXMmkwHzVqlWeSRk+fLjVrVu3yAlq+SKQXAIS9OTurVYmAiIgAiJQRAQk6EW02VqqCIiACIhAcglI0JO7t1qZCIiACIhAERGQoBfRZmupIiACIiACySUgQU/u3mplIiACIiACRURAgl5Em62lioAIiIAIJJeABD25e6uViYAIiIAIFBEBCXoRbbaWKgIiIAIikFwCEvTk7q1WJgIiIAIiUEQEJOhFtNlaqgiIgAiIQHIJSNCTu7damQiIgAiIQBERkKAX0WZrqSIgAiIgAsklIEFP7t5qZSIgAiIgAkVEQIJeRJutpYqACIiACCSXgAQ9uXurlYmACIiACBQRAQl6EW22lioCIiACIpBcAhL05O6tViYCIiACIlBEBCToRbTZWqoIiIAIiEByCUjQ/6V7O3ToUPv999/tpptuKvgK5s+fb9ddd50tW7bMTjvtNBsyZEjB55TECfz222924IEH2ltvvWU777xzEpeoNYmACJSDgAQ9Jry+ffvaq6++ai+88ILtsMMOJUZp3ry5Pfzww7bvvvvGHD37af9Pgn7WWWdZixYt7KKLLnIno0aNGiUWAKtp06aV+Ldtt93WcAQq2rjur7/+auedd17qUueff7516dLFTjjhhAq5/JQpU+zaa6/dZOypU6da48aNY1+zIgSdebJve++9t88LZ+HOO++0p59+OvY8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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.profile_plot(\n", - " problems=problems,\n", - " results=results,\n", - ")\n", - "\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "4ada4410", - "metadata": {}, - "source": [ - "The x axis shows runtime per problem. The y axis shows the share of problems each algorithm solved within that runtime. Thus, higher and further to the left values are desirable. Higher means more problems were solved and further to the left means, the algorithm found the solutions earlier. \n", - "\n", - "You can choose:\n", - "\n", - "- whether to use `n_evaluations` or `walltime` as **`runtime_measure`**\n", - "- whether to normalize runtime such that the runtime of each problem is shown as a multiple of the fastest algorithm on that problem\n", - "- how to determine when an evaluation is close enough to the optimum to be counted as converged. Convergence is always based on some measure of distance between the true solution and the solution found by an optimizer. Whether distiance is measured in parameter space, function space, or a combination of both can be specified. \n", - "\n", - "Below, we consider a problem to be solved if the distance between the parameters found by the optimizer and the true solution parameters are at most 0.1% of the distance between the start parameters and true solution parameters. " - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "efc15318", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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iIAIiIAIpExAgp7yAWh6ERABERABEUiCgAQ9CYoaQwREQAREQARSJiBBT/kANL0IiIAIiIAIJEFAgp4ERY0hAiIgAiIgAikTkKCnfACaXgREQAREQASSICBBT4KixhABERABERCBlAlI0FM+AE0vAiIgAiIgAkkQkKAnQVFjiIAIiIAIiEDKBCToKR+AphcBERABERCBJAhI0JOgqDFEQAREQAREIGUCEvSUD0DTi4AIiIAIiEASBCToSVDUGCIgAiIgAiKQMgEJesoHEHf6IUOG2O+//2633HJL3CESu+6dd96x/v372xdffGFt27a1wYMHJza2BvqPwG+//WYHH3ywLVq0yHbddVehEQEREIFSBCToMW+Ivn372osvvmjz5s2zatWqlRrlyCOPtHvvvdcaNGgQc/TCl5UnQT/zzDOtefPmdv7557uTsfPOO5faAKxmz55VsyW/AAAKiklEQVRd6v9tt912hiOwuY15f/31V+vWrVtmqnPOOcfOPfdcO+mkkzbL9I899phde+21G409a9YsO+igg2LPuTkEnXVybvXr1/d14SyMGDHCHn300djr1IUiIALpEJCgx+SOSD333HPWokULGzp0aCqC/ueff9pNN90UcwfJXUbUOGPGDDvggANyDgqrHXfc0S655JLM51tsscVGjlByK/pvpCuuuMIOO+ywUoKOWDVp0sT22WefzTGlIehTp051py5qO+20k1WqVCn2nEkL+rp169ypmTx5ckbQv/32W5s/f76dddZZsdepC0VABNIhIEGPyR2RqlOnjk2aNMnGjRvnAhEsGqF/9dVXduKJJ9oHH3xQ6mFer149dwj23XdfI9quUqWKp6yXLl1qCHXnzp3t+OOPt0GDBtmqVats2223teuvv96aNm3q04QIne8+++yzttVWW1n79u3tuuuuy8zDw/mGG26wV155xapXr+5j9urVyxBTxIHxiRqvuuoqe//99z0qyxZlHvq33367zZkzx9auXWuNGjXydfC9jz/+2Od7++23XbBZA2vJFaGTIr7mmms2og3H3Xff3fr06ZP5bPTo0c7ijjvu8HUeddRR/udRo0b537fffnuf99hjj81c89BDD9nEiRPtm2++8fGGDRtmTzzxhIvr1ltvbZUrV7bTTz/dr4NTjx49rE2bNn79m2++6TxhULVqVevYsaNdfvnltuWW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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.profile_plot(\n", - " problems=problems,\n", - " results=results,\n", - " runtime_measure=\"n_evaluations\",\n", - " stopping_criterion=\"x\",\n", - " x_precision=0.001,\n", - ")\n", - "\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "70744c8b", - "metadata": {}, - "source": [ - "## 4b. Convergence plots\n", - "\n", - "**Convergence Plots** look at particular problems and show the convergence of each optimizer on each problem. They look similar to what you've seen from estimagic's dashboard." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "df3dc55b", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAA+gAAAFACAYAAAAvc1ZOAAAgAElEQVR4XuydB3RUxRfGvzRIIPQivf/pvSO9iDSlV+kgvUsH6b1IR4oiCiqKIk1BFCliQ0WUDoIKCNJ7TYD/+QZf3CzJ5gUCbHa/ew4HyM6bN/Obl533zb1zx+fevXv3IBMBERABERABERABERABERABERABEXiqBHwk0J8qf91cBERABERABERABERABERABERABAwBCXQ9CCIgAiIgAiIgAiIgAiIgAiIgAiLgBgQk0N1gENQEERABERABERABERABERABERABEZBA1zMgAiIgAiIgAiIgAiIgAiIgAiIgAm5AQALdDQZBTRABERABERABERABERABERABERABCXQ9AyIgAiIgAiIgAiIgAiIgAiIgAiLgBgQk0N1gENQEERABERABERABERABERABERABEZBA1zMgAiIgAiIgAiIgAiIgAiIgAiIgAm5AQALdDQZBTRABERABERABERABERABERABERABCXQ9AyIgAiIgAiIgAiIgAiIgAiIgAiLgBgQk0N1gELyhCUuWLMGoUaPCuho/fnzkyJED7dq1Q9WqVd0WQf/+/XH9+nXMnj37qbXx+PHjqFixItavX4+sWbNGqx1Xr17Fu+++a649duwYbt68iZQpU6JgwYJo06YN8uXLF636HqXw4MGDcf78ecybNy/CakJCQvDGG29gxYoVOHHiBBIkSIBs2bKhefPmqFat2qPcWteKgAiIgNsRcJ4X48SJg1SpUqFcuXLo3r07kiZN+ljbfO3aNSxevBjr1q3DH3/8geDgYOTPnx+vvPIKcubMGXbvbt264fPPPw83f2fJkgUvvPACXnrpJbDdMhEQAREQgZgjIIEecyxVkwsCfBGZOXMmFi1ahLt37+LcuXNYu3Yt1qxZYwRk8eLF3ZJfbBbof/75p1kAuX37Nlq0aIE8efLg3r17+Ouvv7Bhwwb07t3bCPUnZVEJ9NGjR+OTTz5Br169zOLNhQsX8NNPPyFv3ryoU6eOaebRo0fBMVm2bFmMNftx1BljjVNFIiACHkvAmhfffvtt00cuqO7fv98sCFMAx+T3XEQQeV+K8yZNmuB///ufWcCdM2cO9uzZYwR54sSJzWUU6Fyo7tu3r/k/F1p//PFHLF26FJkzZzYin+JeJgIiIAIiEDMEJNBjhqNqiYIAX0Q48X///ffhSjZo0ADp06fHtGnT3JIhxeCNGzcwa9asp9a+h/Gg0xtdv359+Pv7gy9h9EY/bYtKoBctWhRdu3Y1nv3IjB72L774Ah988EGMdedx1BljjVNFIiACHksgsnnxww8/xJAhQ/Dzzz8jYcKEj63/XLD18fEJV/+lS5fA7+KFCxeiQoUKYQLdz88PM2bMCFeWi5sNGzZEpUqVMH78+MfWTlUsAiIgAt5GQALd20b8KfU3shcRvoQcPHgQy5cvD2vZ119/bV4E9u3bh8DAQJQvXx4DBw40odm00NBQTJ8+3Xjfz549iyRJkpgXCnpgLSF65MgRjB07Ftu3b0fcuHFRo0YNUCCyPtrHH38MvgR17NjR3Ov3339HsmTJjKe2Z8+e4MsIjQL9zp07yJ07N9555x2cOXPGhJn369fPhCFaxjZOmTLFeB7mz59vPBH0/rIeerInTJiAH374ARTO9Frz+gIFCoQbjc2bNxvPCfsdFBRkPN6MODh58uQDIe5cMHj//fdNH9KlS/fAqH755Zfo3Lmz8Y4wTNyOvfXWW3jvvffw999/Gxa1a9c2LAICAsIup4eH/aR3hS9yGTNmNAwtD7dVkC+W48aNM94gjk+zZs3wzz//4PTp05GGuBcuXNh4atq2bRthc0eMGGGiLRyNHpwSJUpg48aNxotz4MABw5he92HDhhmvEI2LHJUrV8bOnTsxZswYE73B69KkSRNpnXaYqYwIiIAIPCyByOZFfj8xzHzXrl1h4eNRfff++uuvaNy4Md58802ULl3aNInRUwxDL1u2LIYOHWqrmYywqlKliplfOK/S+L0ckUDnZ/xO5tz77bffPvaQfFsdUCEREAER8AACEugeMIixoQuRvYgw9JpikIKbtm3bNrRv396INO47vnz5sgmNv3jxIlauXIl48eJhwYIFJvSPQov79SgoKby4Z4/G8DsKcgrgLl26mLDB4cOHm5cNCmUaBfqrr76KXLlymXooun/77Te8/PLLRjxTUNIo0Cl2KR4pRHl/7pHmS8mnn34atiecAj179uzm3izHhYJSpUoZQV+rVi0jytkn7tX76KOPsGrVKtMGhnLTuCjBcPSmTZuaflNkch82Qw+dPehczKD4pZhm+yMyvozxhY2LGHaM/OlpZ3/JjQsc9IiULFkSU6dONVXQ28L94OzTgAEDDHu+lPFa8m3UqJEpx88phulVYZ9u3bplvDFcsChWrFikAp33/uabb0y0Ank7Gxc9XnvtNfzyyy9GjNO44MIXRy5kkFmZMmVMOynmeV+r/xZDeoQSJUpkFh+4v5PjHlmddripjAiIgAg8LAHneZGC+tChQ2ZBmguIlqi2+93L77LVq1fjs88+M3MVF1OZf4SC31qcjqyt/L7cu3evyRWTIkUKs9BsedddCXQuIHOx+vXXXzfCXiYCIiACIvDoBCTQH52harBBwPlFhEKWQpPim2LX2gvNcLm0adOGCXZWfeXKFfMC0KdPH7OXml53em8jS9xGjzgF/KZNm8JeSiiAKfzppU6dOrURx3wJ4t9MimMZvexcDJg7d675EUUjvbMUovTEW8bQfApyCmUaBTr31nNvN73flvEFiWKcbWG4uWVMrEPPstUHitvkyZOH3dcRqaNAZ0ghvdoMy3a1b5+LAXxBc2bE6APLfH19wT9cwKAQJ1cuEFhGjz8FORci2FcyZL3OXnmOIRcLKK4pltlnviSyz1YkAl88yYjiP7IkcWwHx4TeeQp0LpLUrFkzHLfJkycboR9ViPvWrVvN4gAXbpiQ0GLIhITcauFoduu08ZiriAiIgAjYJmAlieP3MI1zCP/NheUePXqECWS73738nq1Xr55ZCOVcyj+MMipUqFCkbbIixHhv2osvvmgWXB1D610JdC4ecKGZi6LWwrZtACooAiIgAiIQIYEoBTpDfxk2ymyfzmZ5zMRWBKIiENGLCJPLUOBaYXR8uWBW8UmTJhkPp6N16tTJCDUKToZPt2zZEs8//zxatWr1QKg4xS9FOIWiZfTEFylSJGxfHYU5xTg9BpaIZFl6IL777ruwkHsKdIZmM7zd0Vg3vf306tMoPum1p2fZ0egBZ7IfS8hbnzGcnIsATLTDfnORgN5951BxlrfEJYUw2zNx4kRzL1dGPvQUO+6dP3z4cLhs6PTws19cfCBHvgTSK+5ofLGzFkaYJ4CeGC5YOBoZcrwsIU8Rz3qc+8yXTr4ERibQrTp3795tvPmsjyH09ORkyJDBfGxXTPN7q3r16mF9shg67qu07me3zqiecW/6XPOCN422+vq4CFhJ4qytO4wS4vc0vdFcFOX3N73Ydr972U5+H1OY0wvOeYJzRlTGbWbMtcLvSS628m8uglrzgSuBToHPjO/cUqZ3wqhI63MREAERsEfApUCnl47hq1wdjSg8ynk/qL1bqpQ3EnB+EaGHm95mekvp4aQxaze9wgxX5p45R6OYpveY3gAaBQKFHr25DPPm51ZYNF9KeGSM495pXsMXEIpGvrxQoFMQUyA7GgU6BSvD0Gl8uaFn1/KoW2XZRopsiloaBTo9thTGjsa2MNTbyn5rfUavOn/GcEZGEzCcMaJ+s7wlLhmSzRc4RgJY4fyRPUsM0ycjZkW3jCGMfBGjkR0jEyjQGQLJ+rh/3vm4HIaqc9GAn48cORIUz475AlgXFzA4XlY2fu55JA/nPtM7zuiEqAS61V72u0OHDib3gBXSHpGYpujnfkkuHnC/P//PP7yXtehgMWQZa1uBdR8J9Oh9I2leiB4vlRaByAhEtvWLW4y4AM3tXDxi0+53r3UfRpoxIeuWLVtMno3oGLcKcXGT8xbnVZorgW7tWefed8e8LNG5p8qKgAiIgAiEJ+BSoPOlmxNIpkyZxE0EHomA84sIRS/3qzEcz1rhp6hiMjZ6iCPyoNPT7RyezCRxDGmn4KbHlV55JsphZviIRCz3u/M4mOgI9Mg86AzptgQwBSmFM1+MHI0h4vT+RuRBZ18Yrk0POpOa0SvP8EJns8Ql94RzMYPHkFGQRrRP27qWIpr7FxlmHtELGvff88WKAp2J9Bh1EJkHncexceGB3hxGDETmQbfEb+vWrQ1/Jg5yNEZBWIsDdh8min6y4+IBLSIxzcUTikbyY3IkbkXgQkLdunUfEOiWl9/x/hLodkfjfjnNC9HjpdIiEBmByAQ6w8Y5FzJRHOcVu9+9vA9PueB3NpOMclGX3vjoGgU5t0NZi6muBDojnBjdxQUBdzgtJLp9VXkREAERcEcCLgU6V275gi8TgUclENGLCEUkM21TNDEMnEYhyLNXOeFbRjHPlXnuyaP4i8gYrk0PLYU9hRpFJBOEOe77drwuOgKdSeLoVXeMIuF9GI7PBHO0yAQ6RTijBb766qtwHn0KeS4UWC9P9FJzIcxKlufYVuckcewnX4bYv8heiHhmLT0gfMnjS5azZ9xRoNOzzsgFLpRQqFvG6ALuKeR+ckYpcDGBe9Sd96Bz24EVKk/eXEggf74oWkmG6JVhe/jSaNeDznbwxZQi3Tqej//neDACwTKG5/NF1PGoPj5b9P44e9AjEugR1fmoz7snX695wZNHV317kgQiE+g8/YKRSIzo4t92v3sZjUXvNxdD+Tf/cD95RFunIusnF4yZqJQL6FF50BlOzzmCC+2cy2UiIAIiIAIxQ8ClQGc2aobtukpGFTPNUC2eTiCiFxF6zOnlZLI0K4SZSb0oEvncMUEYw7ApWpkplqKMopaCjfurue+NwpOJ3xiuTg8uhT696nypoaik4GfyNf6MLznWsWHREegU19wjTi8CPdjW8WYUqtwj7Uqgc+87+0FhypcmK4s79/fxiDT+nEbRyT3aPAOcoY0UtGTB30Fngc58EPS0c4EgIkFvPUtM8sYQcXrQyZR7Gimgz507Z/bic8HB2lvP8EQKbSaK475zbhGgB5xJ3RwXS9geet754sZ6uV+fEQ+DBg0KE/ccK77csY3kz74wfJ+Cnd7XiAQ662QkBLOwM0kgPUg7duwwWwt4NjqPjKNxWwQjI/hzjj+fB7abWYt5PcPhOc7sD8P57Qj0iOrk8yWLmIDmBT0ZIhAzBJy3flEcc2sSFw05P/J7zUo6aue7l9+NPMqScxSTzXGe4fcz63HOL8IecKGWC8Oc3xhdxu9ufnfypAzOt1buD859XPTltiXuOec9mIOFC6FM8MoIpqiyxMcMMdUiAiIgAt5BwKVA50szPYX88mbSLcdkWsTjHLbrHcjUy4chEJmnwAqv5gsJV+1p9NzSc8AwZQpaes+tY734OcOsGVbH49X4EsJzvilu6aG17NixYyYcmmHo3HvOlw+KQ4pOPsfREeh8/imKuTBAoc+zteltts6adSXQ+RlfeuhV5gsNX8Aoevmi45xZl3vB6VHnvnS+7HBhjGLWWaCzTop3JqDj7yC9F5EZf4fJivfm8Wf0aJMFPetcOHAMqeeCAffV8xqW4Wdc0HD0vtPbbp1BT28NFygYglm/fv1wTaDHm4smFMnMBmwda8YXv4gEOutiFmB+zn+z/1xsYaSBYxsp3Lkfk9EDVsI5CnW+aFKM8+WR0RT0GnH/P5nyxdRiGJEHPaI6mRNAFjEBzQt6MkQgZghYyVOt2jif8V2LC5X87mWiN8ui+u7ldyIXSvk3t3pZxggj6yhK51ZTYFPEc0GW+U34Xcl5h/MptylZRoHOfDE0ziH8Tuf3Lr/XucgeWaRazFBSLSIgAiLgfQRcCnSuxvIFm5NFRKujTEQlEwEREAER8B4Cmhe8Z6zVUxEQAREQAREQgSdPwKVApxeJe0kZRioTAREQAREQAc0LegZEQAREQAREQARE4PERcCnQecSSc8bmx9cU1SwCIiACIuDuBDQvuPsIqX0iIAIiIAIiIAKxmYBLgc69qzQmrnLOAh2bO622i4AIiIAIPBwBzQsPx01XiYAIiIAIiIAIiIAdAi4FOjNpb9261YhzJitxFunMfiwTAREQARHwHgKaF7xnrNVTERABERABERCBJ0/ApUDn8VKuzDFr9pNvuu4oAiIgAiLwpAloXnjSxHU/ERABERABERABbyLgUqB7Ewj1VQREQAREQAREQAREQAREQAREQASeJoEoz0F31TiegeyNxnOweVa1TAREQAS8jQDPQde8EPWo9+rVC1WqVEGtWrWiLqwSIiACIiACIiACIvAvAZcCnUI0MkubNi02b97slSAl0L1y2NVpERABAJoX7D0GEuj2OKmUCIiACIiACIhAeALRCnG/desWjh49ipkzZ6J8+fJo0KCBV/KUQPfKYVenRUAEIiCgeSHix0ICXb8uIiACIiACIiACD0MgWgLdugFfyGrXro3169c/zD1j/TUS6LF+CNUBERCBGCbg7fOCM04J9Bh+wFSdCIiACIiACHgJgYcS6GRDD/qWLVu8BFP4bkqge+Wwq9MiIAJREPDmeUECXb8eIiACIiACIiACMUHApUAPDQ194B43b97EqlWr8OGHH5q/vdEk0L1x1NVnERABEtC8YO85kAfdHieVEgEREAEREAERCE/goZLEpUmTBq+99hqKFCnilTwl0L1y2NVpERABF0nivH1ekAddvx4iIAIiIAIiIAIxQcClQD9+/PgD94gfPz6SJEkSE/d2izru3buHOXPm4K233sLPP/9sq00S6LYwqZAIiIAHEvCGeSGiYdu0aRP69OmDd999F7lz545yZOVBjxKRCoiACIiACIiACERA4KH3oHsCzZCQEPTu3RspU6bEmjVr8OOPP9rqlgS6LUwqJAIiIAIeQeDNN9/EV199hevXr2Ps2LES6B4xquqECIiACIiACLgnAZcC/fbt2/j444+xb98+XLt27YEeTJ061T17FY1Wbd26FWXKlDHh+r/88outKyXQbWFSIREQAQ8k4A3zgvOwff/99yhcuDBatWqFV199VQLdA59rdUkEREAEYhOB9957DwcPHsSIESNMs7dv327mJzof582bh+zZs0fanTx58mDPnj2xqbte11aXAr1v377Yv38/ypUrh8DAwAfg9OjRwyOAMelRsWLFoiXQm8zrH9b3TIGJ0K50I49goU6IgAiIgCsC3jIvRMSgcePGGD58uG2B/r/8+fB7Kj+0SZAUuYKSwj93QfjEC9YDJgIiIAIiIAKPRMBZoDds2BD9+vUzeobm4+Mjgf5IhJ/uxS4FOj3LGzZsQLx48Z5uKx/z3V0J9BdeeOGBu3PR4vdlfcJ+Xub0ZXxdfcBjbqWqFwEREIGnT8Bb5oXoCPTJkyeD0ViOliJFCiT93/8wtWpivL3ya7x44ChCu09D8rL3X55kIiACIiACIvCwBJwFevHixc1WrODgqBeB5UF/WOpP7jqXAr1y5crYuHHjk2vNU7qTK4F+48aNB1qVP39+FOzzCnJk88HYpHeR79R5/FZjyFNqvW4rAiIgAk+OgLfMC9ER6AwpdD5+buDAgYibNQsml46DWWt2o/neX3G+2XhkqVP2yQ2W7iQCIiACIvBYCbRt2xaVKlUKy1NCpyZPukqcOLG576hRo7BlyxYTel6wYEFwe3BAQADOnTuHAQMG4OrVqyZamZ8/99xzmD59eoTttcofPnwYqVOnNtuueC3nmkGDBuGzzz5Dzpw5Ubp0afTv3x9MbDplyhRTJmPGjBgzZgwyZMhg6rYEOuctRoX98MMP4PY1JkBleLzs6RNwKdA5mEmTJsXLL79sHiZPtYcJcS9fYy/emBEAn59fN1juFensqXjULxEQAREII+At80J0BHpEZZnFPUXpQhia5Tomf30J7b9di3P1hiFrk6p6mkRABERABB6SwE877+Hvk3cf8uqHv6xYQV+kSf1g2DgFOjXS3Llz4efnh3HjxiFBggTo3r27udmOHTtAxx7tpZdeQuvWrVG9enUj3NOnT482bdrg0KFD4Jzx6aefRtpAfk6BzdNEzp8/D4a0ly1bNmwPeqFChbBt2zbwtK1jx46hWbNm5tQRXrN+/XrMmjXLJMT29fUNE+h0wq5cudJ8RuN1bJPs6RNwKdCZfKBevXrgUWQM1+OD52ie4l1/WIE+Z1IAAndLoD/9x1gtEAEReFIEvGVeiAmBnrJ0IQzJch1jv7mOLts+wbma/ZC1Ve0nNVS6jwiIgAh4HIH5i+/gx1+evEDv2MoPxQr7PsCTAp1imaKbRpFtea+dC9N7zqOqeQ2TjvIkKXrVaRTYrpJVU+RTgCdMmNCUnzZtGi5duhShQF+0aBFOnDiBoUOHhjWhZs2a4HYsesktDzrn806dOhnv+rPPPutxz0ps7pBLgU5xniVLFlStWjXCJHFMHucJ9rACfcb4AATvuy/QQwJLwD9PYU/AoT6IgAiIQKQEvGVeiEmBPuq7UHTf+gHOVemOrB0a6+kSAREQARF4SALu6EHv0KEDSpYsaXq0bt0647GeMWMGuE12zpw52L17t/Fc//XXX2jatCnat2+P0aNHmyjlrl27YufOncbz/uGHH0ZIhSdplShRwtRj2ZIlS8BwdyuLu6MHnXUlT54cbJdlXBRo0aIFKlasGCbQ+dnPP/9s2njq1CkTLk+vvOzpE3Ap0Lma8s0337jMBPj0u/DkW8Bj1hji/tqYACQ6KIH+5EdAdxQBEXhaBDQv2CPPcMRnShfC4CzXMWK7L3puWoJz5doha7c29ipQKREQAREQAbcnQOHbsWNHI6CdBfqECRNw/fp1DBs2DP7+/hg/fryJSKZAv3jxIpiImo7QRIkSgSekWHvEI+p0vnz58N1334UlgWNYOvelRyTQFy5caAR3VB50x/tQ/Ldr1w6ff/552P55t4fvwQ10KdAZrrFq1SrEiRPHgxFEv2uWQJ88KgBJf5dAjz5BXSECIhBbCWhesDdyjgJ92I646P3FIpwt3gzZ+naxV4FKiYAIiIAIuD0BVwKdx55RM9CTTcHMfeGWB52nZFFwM0mbHePR1jzbvFu3brhw4QKaNGmCUqVKRSjQjx49ava708ueKVMmI7qZfI7h94570E+ePGkipBl2Ty89w+BXrFhhPPuyp0vApUDfvHkzli1bZlZU0qRJ84BQ5yqQN5ol0CcMD0CKP+4L9BuH4yCwUTtvxKE+i4AIeBEBzQv2BttRoA/5NSH6rn8d5wvWQ5bB/x3Raa8mlRIBERABEXBXAq4E+oEDB8w+c26lTZcunRHUPJ+cHvQff/zRhJwHBQUZ73rWrFnNXvBs2bJF2NUzZ86YrO+///47UqZMaTLHnz59OkKBzgqYJ2zSpEkmzJ6eedZNsU6z9qAzgR3D2tk+JrpjXxo31jYsd3jWXAp0JiSI6Jgxq+HMOuiNZgn0sUMDkOqoBLo3PgPqswh4KwHNC/ZGngI9VelCGJTlOgbtTYb+a2biQu7qyDxCR3LaI6hSIiACIuCZBCi2mc2doeh0gPKINZ5rvmvXLnM0mkwEXAp0hju4Mqby90azBPqoQf5I+/f98wLlQffGJ0F9FgHvI6B5wd6YOwr0AQefwcBPXsOFbBWQedwYexWolAiIgAiIgEcS2Lt3L4YMGYKPPvrInJB19+5dcz46/2amdmfr0qVLWJZ4jwSiTj1AwKVAF6+ICVgCfXh/f2T4575Av7rxL8TvP0HIREAEREAERMCcaZu6dGEMzHIN/Q6nx+CPJuBixhLINHmq6IiACIiACHg5AR6TxjB0hpZTmBctWhT9+/dH3LhxvZyMuk8CEQp0pudnmn0mMHBlPCLAG80S6ENf8UfmM/cF+pU1exA8YrY34lCfRUAEvICA5oXoDbKjQH/lz6wY+sEoXElTAOmnz4leRSotAiIgAiIgAiLgVQQiFOhM3c/jAriy48oGDRrkVbCszloCfVAvf2Q7L4HulQ+BOi0CXkZA80L0BtxRoPf+OweGLR2Gq8mzI93cRdGrSKVFQAREQAREQAS8ioBC3B9iuC2B3r+HP3JcvC/QL85ahUSL1z9EbbpEBERABETA0whQoKcpXQQDslxFr1N5MHzxYFxPlAFpFr7naV1Vf0RABERABERABGKQgEuB3rBhQyxfvvyB2zGzO9Pwr169OgabEnuqsgT6K139kfvKfYF+YeK7SPzhg4kdYk+v1FIREAERiJqA5oWoGbGEo0DvcbYARr7ZHzfjp0Sqt1bYq0ClREAEREAEREAEvJKAS4FerFgxc06fs/F4gMqVK+O3337zSmiWQO/VyR/5rkuge+VDoE6LgJcS0Lxgb+Ap0NOWKYL+ma+i+8XiGDW/J0LiJkCKJevsVaBSIiACIiACIiACXkkgQoHevXt33Lt3D1999RUqVaoUDsydO3fMOX2FCxfGzJkzvRKaJdC7v+yPVr7L8euNc/h13irkHfsWfFOm9kom6rQIiIBnE9C8EL3xdRToXa+XxZhZnUwFirSKHkeVFgEREAEREAFvIxChQD9x4gQ2b96MiRMngmfvOZqvry/SpUuH5557Dv7+/t7Gy/TXEuhd2vqjT+BqbLl6Amve/xLV2gyBf57CXslEnRYBEfBsApoXoje+4QT6zTIYM6OzBHr0EKq0CIiACIiACHglAZch7h9//DHq16/vlWBcddoS6B1b+aFf/DUS6HpCREAEvIaA5gV7Q02Bnq5MEfTLfBXdbpXG4Bn9EXTvqkkm6hMv2F4lKiUCIiACIiACIuB1BKLM4n7z5k188cUXOHr0qIGTKVMmVKlSBXHjxvU6WFaHLYHerrkfBiX8T6BXrdUOcSrU8Fou6rgIiIB3ENC8EPU4hxPoIaXxyoxXkfjOOSSa9wl8kmtNvxgAACAASURBVKaIugKVEAEREAEREAER8EoCLgX6jh070LlzZyRNmhTZsmVDSEgI9uzZA+5DnzdvHvLnz++V0CyB3rqZH4Ym/k+gVyleA4GN2nklE3VaBETAOwhoXrA3zo4CvXvos+g+fTxS3DmOhNPfg2+aDPYqUSkREAEREAEREAGvI+BSoL/44oto2bIlGjRoEAaG4nzq1Kn49ttvsXLlSq8Dxg5bAr1FYz8MTyaB7pUPgTotAl5KQPOCvYEPJ9DvlELH6dORNvR3JJi4CH6Zs9urRKVEQAREQAREQAS8joBLgV6mTBls2/bg2d6XLl1CqVKlsHfvXlvA9u3bZzzwAQEBtsq7eyFLoDdr4IdRKf8T6JXzlkNQ657u3ny1TwREQAQemoDmBXvoKNDTlymKvpmvoPvdUmgzfT4yh+xC8Mg58M9VwF4lKiUCIiACIiACIuB1BFwK9Nq1a2PZsmUICgoKB+bQoUPo1q0bPv/8c1vAcufOjS+//BJp0qSxVd7dC1kCvXFdP4xN/Z9ArxCcGsEjZrt789U+ERABEXhoApoX7KGjQM9QtiheyXQFPVASjacvRe5bPyB40BT4FypprxKVEgEREAEREAER8DoCLgX6Z599hk8++QQvv/wy0qdPj1u3buHw4cOYM2cOOnTogKJFi5rz0i1LkSLixDcMke/YsaM5ms0TzBLoDV70w4R0EuieMKbqgwiIgD0CmhfscQon0H1Lou60j1Hw5mbE7z0KAaUq2atEpURABERABERABLyOgEuBXrBgQVy7ds02FHrWI7I///wTgwYNQr169VCiRIkHPPKRCXvbN37CBS2BXremHyZn/E+gl/dNgASTFj/h1uh2IiACIvDkCGhesMfaUaD39C2J6jPWocT1zxCv8yDEqVjTXiUqJQIiIAIiIAIi4HUEXAr06IhzkosfP36EAIsUKYLLly9HCjcyYe+uo2EJ9Ber++G1zP8J9DJHTyHxhw/u2XfXfqhdIiACIhBdApoX7BELJ9D9S6Dy9M0oe20Fgtr0Qtzq/yVetVebSomACIiACIiACHgLgSjPQY8JEFG90EUm7GPi3o+jDkug16zqixnZ1mLL1RNY8/6XkEB/HLRVpwiIgCcS8LR5wXmMKNAzli2GPpkuo2dACZSd/gMqX30XgU07IrBuC08cUvVJBERABEQgFhHYuXMnJk+ejHfffTfCVpcsWRLc1sbjtt3d3nvvPRw8eBAjRoxw96baap9Lgb5x40aTCO7YsWOmMu5Df/7551G5cmVblXtqIUugV6vsi9k5JNA9dZzVLxEQgQcJaF6w91RQoGcqWwy9KdDjlkDxabtQ48pCI84p0mUiIAIiIALeRWDPnj2YPn06Fi5c6BYdl0B3i2GIsBERCvTQ0FD07NkTmzdvNoI8Y8aM8PX1xV9//YX169ejfPnymDFjBvz9/W33bNeuXWZlg4nmnK1Zs2a263GHgpZAf66CL17PfV+gf/btnyj19TcIHj4T/nkKu0Mz1QYREAERiDECmheihzK8QC+OAjOOoO6lGSa8nWHuMhEQAREQAe8icOPGDRw4cADM5eIOJoHuDqMQcRsiFOjz5883x6vxzzPPPBPuytOnT6Np06Zo1KiRycxux5j1natFBQoUwK+//oq8efMasX/16lVQnPfr189ONW5TxhLolcr6YkE+CXS3GRg1RARE4LER0LwQPbThBHpQMeSafhKNL040CeKYKE4mAiIgAiIQ+wksXboUS5Yswe3bt5EgQQIsWLAAqVKlwpEjRzBs2DBz+lXcuHGxePFiXLx4MSyknOJ43rx5CA4OxqlTp4wm6tOnD8qWLYtx48YhYcKE5khr2p07d8zPV6xYYep2Ns7PzPVFbcV7XL9+HSNHjkS+fPlMUSbrHjx4sLlP2rRpMXHiRKROnRrOAn358uWmTXHixEH16tXx8ccfm9O8GOLuqo7333/f1EcOAwYMQPbs2fH666+DScDZprNnz5pk4XTykgu3uA0dOtQkDqfRIcxQ+5s3b5qfMUydbbhw4YLRiLwmJCQEzZs3D9Oe586dM/ciX967cOHChqFHh7hXq1YNPXr0QI0aNSL8zfniiy/w2muvYd26dbZ+s5599lksWrQIOXPmxAsvvIA1a9bg7t27mDBhApIkSYLOnTvbqsddClkCvfyzvjhcdgdGnvwJE/f8gw5rN8qD7i6DpHaIgAjEKAHNC9HDGU6gxyuGrNMvosWFEeaINR61JhMBERABEYg+gZDvN+HO0SPRv/ARr4hTqhJ802cOV8uVK1eMVvryyy+NCD9+/DjSpUtnBHXNmjVNNDKFLoVmokSJ8Ntvv4UT6HR2rly5Erlz5zbbifl/bi0+efIkunfvjg0bNpj7fffdd5g1axa4zzoio0DnQgH1VeLEicGtaG+99Zb5GfVWrVq1jJhlBDRFOPUbdZmjQKfQbdGiRdgiAK/nQsEPP/xg6nRVB4/jbtmypdFzjK5mvewL25MjRw5zP+pK7nUvXrw4fvrpJ4wfP94sALCvLPvBBx8Yod2/f39ky5bNCHG2fceOHeZYb4r8qlWrGtZcMDCJWDNkMIsa58+fR8OGDc0ihkcLdD4oTAqQKVOmCB+EEydOmDPNuZfCjnEF5+effzarIRzgtWvXmssuXbpkQui///57O9W4TRlLoJcp4Ys/K9wX6EPO+6LvwiUIbNAGgY3auU1b1RAREAERiAkCmheiR5EvD5nLFkMv7kGPVwTpZoSg/fkB8C9UEsGDpkSvMpUWAREQAREwBK5NH4aQb7964jTi9xqJgGfD5+CiEKce6tChgzlKmjqHtnfvXiM0Lb1jNdZREPPf9GpTb1lGgVu3bl0jRGvXro0xY8YYLzi9zXny5DERzJEJdApdS5xSzLKer7/+2rRl4MCBWL16tbmU29Xy589vIpqp46wkcYx0poed96IxIoD35uLAP//847IOLiZs3boVPj4+5lrnvh09ehSNGzc2ddEY6l+uXDn8+OOPZiGBunLIkCHmMy4IcJ8+vfLORiE/fPhww4J92LZtm4k0oE2bNs3oSo8W6IUKFTLAItsjwcF+6aWX8Msvv9j6BXnxxRfNSgmBtmrVyjy0/PeZM2fMg82BjE1mCfRSxXxxrJIEemwaO7VVBETg4QhoXoget3ACPX4RpJjhj67nesA/VwEEj5wTvcpUWgREQAREwBBwJw862/P333+DW3kpFtu0aWP+bNq0yXiv33zzzXCj5izQqY3oObaMIpX6iNt/3377beORp7immKXYZ9RxREYPOsPD6bGn0aNMzz4doGwLf+4YGk8hy/rYdkugsy3JkiUziw2WFStWzHj0KeZd1TFp0qRw3n320/Fn7Efbtm3DIgKYj4wZ4qkjGU3NMHpGGNC46EGPPb3rFPYMlecCAcU/28GtAlmyZDGh8Lt37w5rK8PrGQXg0QK9devWJtyCQjoi48oG4ROSHeOqDcMWONBcKeK+CIZZEHSuXLnMSklsMkugFyvsi5PPSaDHprFTW0VABB6OgOaF6HGjQM9Stjh6ZrqEHsGFkWhGQvQ5+zL8MmdHgomLoleZSouACIiACLg1ATodGepNIZs8eXLjHWeIt6M5C3SGZ3/11X/RABT39JLTg06RXb9+feNFp95ylfmdAp2il2HkzgKdTtVXX33VCF5nc2wP67f2iltCmTnDvvnmGyOQ7dRh1e+8t92VQKdDmOwi0pyMAuC7B6MJaHXq1MHo0aONZ9/y7nMPP41bALgv3aMF+vbt2w0QhixwT4F1TjlDErgiREHNVSGufjyMcW8EV3W4T6NJkyZm30ZsMkugFy7gg9PVfjEh7kPvpsArk6cjoGgZxO8/ITZ1R20VAREQgSgJaF6IElG4Ao4CvWdwYQTOegYDTzeHb+r0SDjjwdC96NWu0iIgAiIgAk+bAHURxWvmzJnNfmkKZOba4nHU3MJL7zcjhZm8jB7gQ4cOhduDzn3T9BBXqVLFOD7bt29vBLsVts2Qd+5zZzlLpEbUZ1cCnR5pXtu1a1ezH/7evXv4448/jBfaUUizbfRyf/TRRyZBOPUeHaoMOad3204dDyPQGd7ORYk33ngD1FdcaGBCch7tzcgBCm8mGWc4PLUpE5hTnJM1k9ExkR73+FNPlipVyrMFOgEzMQEHhpA4UHywuDeBq0LMSsiEQVEZV5K4J8Ba3WAYB5MmWP+P6np3/dwS6AXy+uBczfsC/VW/tOgzbhL8cxdE8IjZ7tp0tUsEREAEHpqA5gX76MJ50BMWht/MTBh2qj58kiRHovkr7VekkiIgAiIgAm5JgJnT6fWm55nJ0ZikjJ5mPz8/7N+/3+yXZhbzePHiGccmQ8utkHKK4ylTppgIYyZC4/Xc/806LGNCtN69exunpuUsja5AZ3mGitOzzDZxIYGLB9R4zp7uDz/80GRxZ/srVapk7ksPN5Oy2a2D94uOB53l6aVnZnlqTu7jp4OYixKMQCAj9p1Z2rkvnonsKNDpdWfiu99//x0pU6Y07eX1Hu1BtwafKe15fjkzC9Lo8eam/ICAAFu/KBSyXHnhwNK4h5GwWc/jNoZy0NPPweTqFR9EPnDOxgeRGQ1pXE3iXgjuwXBllkDPm8sHF1+UQH/cY6n6RUAE3IdAbJ4XnCkyoy49HJzoecrI1KlTzUTvbNzDx5cE7vGjZ4MvXVGdY0uBnrVscfTIdAk9ExVCyMxcGPtPTSAoHhK/fT8zr0wEREAERMA7CVgCnZ7qyOzTTz8FT86KbVuBvXNEY7bXEZ6DHlO3eFoCnaEbDM1nGARftl555RXzMsXQDUdjcgK+aLEcV7f4C8DzA6NafbEEeq7sPrhSVwI9pp4X1SMCIuD5BJ7WvOBM1sq+y+97htExIc+3334Lhgo6GhckypQpA3oWMmbMaLLQjho1KspjRsMJ9CSFcHVGEUw5WdFUnfjDbZ4/0OqhCIiACIhApAScvczOBbkgzLBtetV5zBitb9++OHDgQLiinL94VrjMswh4pEBfsGABGHbCB5m2b98+DBo0yJw16GibN282L11z5841P+Y5fdwfT0+JK7MEevasPrjeQALds34l1BsREIHHScBdBDqTlDL5jhVBxbA/7l9jSGGCBAnCEHDvIKOwmKGXUVhM3MO9eDy+xpVRoGcrWwLdM11EjyQFcW1GUYz7pzri3LuJxEs3AnFiV+6Vx/lMqG4REAER8DYCrgQ6M6ozqTYFOveOy7yPwGMX6DNmzAjbc86N/PRWcB+7o3H1JyaNmRO52sQzCWlMOMD/M1zf0ay9DM8++6wJ3Z89e7bZA5EtWzZbAj1rZh/cahReoPtlyoYEk+xlt4/JPqsuERABEYgNBCjQn8a84Mxm1apVxmPO73zLGjRoYHKscD5wtHHjxplzWrn3jduimFm3Vq1aUQv0ciXQPeNF9EhaENemF8WI03URfOciEr2xFj4JE8eG4VIbRUAEREAEREAEnjCBxyrQeZSaHduyZYudYrbL8NgCZkTkGYCW8aXw4MGDJtmdo3FvB1/I6D2hV4Rp/pmowTImRXI2rmaVr7EXmTL4ILTpfYE+PHVR9OrV2xRV+KLtoVJBERABLyPwtOYFZ8xMWsrjZ5ifxLLmzZubjLDOJ5QcOXIE7dq1g6+vL9KkSWMWGKzcKryWe9mZydfRGLGVu0rZ+wI9WQFcm1YMg880Q9LQk0g4+0P4pkzjZSOv7oqACIiACIiACNghYEugM+sf0+8zNT+9yzwj3Z1tyJAhJiV/o0aNTDMZosgXLscD7flzhijOnDnTZFYMDAzE2LFjwf2G9JZYNmnSpAe6yrMCKdDTp/XBveYS6O78LKhtIiACj4dAbJsXnCmsXr0aXBxmYjjLuEjL/eWcPyzjuaqcS3gUDo90WbFihTmPlh54ZpulMfkpt1I5GjPLFqhWEd2MQM+Pa9OKo+/ZdkgVcgRxq9ZFUIuuQNzAxzM4qlUEREAEREAERCDWEnAp0HmuHBOs/fzzzyY5Dr3Pf/75p3l5YUI1Rw+COxFYtGiRORKO+85p9G5QtPMlytGYeIGZ5RmuSGPIO4U8jztwZdYe9DSpfeDbUgLdncZebREBEXi8BGLrvOBMZc+ePWZesHKThIaGonjx4uYM2sSJ/ws/57zBxVzHxVoe/0LPu6vFau5B/1+5Ekag90yZD1enlEDXs92QOWSPaUqCUXPhlzN8KP3jHTnVLgIiIAIiIAIiEBsIuBToPHuPopweBevscnqjecYfQ8IZ5ueOdvz4cTRr1gzvv/9+WBZ36zB7eky4l7Bp06bGc86XNL54Max9/fr15rw/hj7aEejPpAQC2uxUiLs7PgRqkwiIwGMhEFvnBWcYnMOqVatm5jOeO8ss7kwQt2TJEjO/UYDzLFaGrnPbFBOKUrjzLFjOL0wq6phMzrl+CvTs5UqgKz3oKfPh2pQSKHrjc7yUYg3uHNqDoJbdEbdW48cyRqpUBERABERABEQg9hJwKdB5NNnnn3+OZ555JlwP6Z3miw2PKXNXW7t2rUn+w2MKuOeRYesMR2RoIo8oYKZ2esyZxZeJgpidl/3kYkSmTJlsCfTkyYBUnfah97FvtAfdXR8EtUsERCBGCcTmecEZBMP0mXeEi7ZZs2Y180L69OlNYlHmMWE0FiOmKNrfffdds82L26Eo2KPaS+8o0LunzIfrU0qY28994TNcXzAZAaWrIH7PETE6NqpMBERABERABEQg9hNwKdCZyXbTpk1IlixZuJ6eOXMGVatWdWuB/jiHxgpxT5IYqNn3DCoeXIXywWmw8tXJ5rZKEvc46atuERCBp0lA84I9+o4CvWuKvLg5taS5cH7PI7gysB18U6VFwpmuo7Xs3UmlREAEREAEREAEPImAS4HeuXNnI84ZAhg37v0zW+mR5lFpN27ceKgQ99OnTxsvhLNXPjZBtQR6wgTAiwMcBPr4ucD1a0j01jr4xP/vHN3Y1De1VQREQARcEdC8YO/5oEDPUa4kumS8gC4p8uDezFK4HQLMnRKA6y+VMZUkWrwePvGC7VWoUiIgAiIgAiIgAl5BwKVA5967Ll26mD13WbJkMcL68OHD5t8LFiywnSSO+/kYWs5rLl++bMByT3v79u3RqVMnE14em8wS6PHjAXUH/yfQ177/BUL37kTw8Jnwz1M4NnVJbRUBERABWwQ0L9jCBEeB3ilFHvjNLoWbt4DZkwIQMrQ17vz1OxJMeAN+WXLaq1ClREAEREAEREAEvIJAlMesUZT/+OOPRpgzy22OHDlQtGhRcx6sXZs2bRo2btwIZk3PmzevuYxHnnH/d8WKFU2m+NhklkAPjAs0eFUCPTaNndoqAiLw6AQ0L0TNkAI9Z/mS6JzhAjomz424857FtevAjPEBuDep2/3F3BGz4J+7UNSVqYQIiIAIiIAIiIDXEHAp0Dds2GD2mjsbE+gw223NmjVtgSpVqhQWL15sxL2jMVlbmzZtTJK22GSWQA8IABoPl0CPTWOntoqACDwaAc0L9vjdF+il0DnDeXRInhvxFz6Ly1eAaWMD4DOrL0J/+R7BAyfDv3ApexWqlAiIgAiIgAiIgFcQcCnQixUrZrznzkZPOjP50gtux3hW7Pbt28OOarOuuXLlCije7dZj515Poowl0Hmv5mMk0J8Ec91DBETAPQhoXrA3Do4CvX3yXEj0ZmlcvARMHR0A/zeHIeS7rxC/1ygEPFvJXoUqJQIiIAIiIAIi4BUEIhToBw8eNJ1v0qQJli1bFg7EnTt3sHnzZnMmLDO827H69eujUaNGaNw4/JmvPLZmzZo1D9zDTp1Ps4wE+tOkr3uLgAg8DQKaF6JHnQI9V/lS6JThPNolz4lkb5XBuQvAxBEBCFo2Hrc3fYp4nQYiTqVa0atYpUVABERABERABDyaQIQCfeDAgfjmm2/AZEA8O9zRuPc8Xbp0GDJkCMqUuZ+JNiqjF75Dhw4oXLgw6E3n/sW9e/di586dePvtt5EvX76oqnCrzynQK7+4F6Gh8qC71cCoMSIgAo+NgOaF6KF1FOhtkuXEM++UwZlzwPhhAQheNQ231n+MoDa9ELd6g+hVrNIiIAIiIAIiIAIeTSDSEPfbt2+jQYMGWL16dYwAOHv2LN5///1wyeboVY+Nx61RoFetuxe3bgFNRpzBc0fun4P+6arvEPLTNsTvOw4BxcvFCDdVIgIiIALuQkDzgv2RoEDPXb4UOmY4j9bJciDNu2Vx6jQwdkgAEn05HzdXLkFg044IrNvCfqUqKQIiIAIiIAIi4PEEXO5B515zf39/j4cQ3Q5SoNdosNdk5G007Aye//O+QF//61nc/OgtBDZog8BG7aJbrcqLgAiIgNsT0Lxgb4gcBXqrZDmQYVk5nDh5D6MG+SPpt+/g5rKFCKzXEoFNOtirUKVEQAREQAREQAS8gkCUx6w9CoUdO3YgSZIkyJw5c1g1586dw4wZM3Dy5ElUqlQJTZs2fZRbPJVrKdBfaLzXZOStP/QMahyVQH8qA6GbioAIxDoCnjovOA+Eo0BvkTQ7si4vj2N/38Pw/v5I+ety3Fg8E3FrNERQ656xbgzVYBEQAREQARF4XARKliyJzz77DEmTJn1ct3D7eh+rQH/ppZdQu3ZtkyDOMiaeS5AggTlLfenSpejcuTOaNWvm9qAcG0iBXqfpXly4BNQdfAa1jkugx6oBVGNFQASeGgFPnRciEuh5ypdChwzn0TxpdmT/uDz+OnYPr/b1R+qDa3F9/kSTII6J4mQiIAIiIAKeT2DPnj2YPn06Fi5cGKOd5faz7777DuXLl4/Reh+lssiOZLVT59MW6F9//bXRqUFBQXaa+1jKPFaBzs699957yJ49u2n8Dz/8gJEjR2Lt2rVgsrmtW7di4sSJ+PTTTx9L5x5XpRTo9ZvvxdnzwIsDz6D2CQn0x8Va9YqACHgWAU+dF1wJ9GZJ/4c8n1TAkb/uYXAff6Q/vhHXZoxAwLOVEb/XSM8aYPVGBERABEQgQgI3btzAgQMHzFHVMWk8XYt/RowYEZPVPnRdly9fRosWLbBq1aqHquNpCnQmMm/YsCEWLFjwVD34UQr0W7dumWzrzOhObziNKzU05wzvzqPA7Ozr1q0zWd9pPXv2BKFbYe1nzpwxYe67du16qAF8WhdRoDdqtRenzgC1+p1B3VMS6E9rLHRfERCBJ09A80LUzBninrf8s3g5wzk0TZoN+VdXxO9H7mFgT39kPP8Nrk0aiIDCzyL+wElRV6YSIiACIiACbkmA0cBLliwx2ogRwhR2qVKlwpEjRzBs2DCTHDtu3LhYvHgxLl68iMmTJ4PHTFNbzZs3D8HBwTh16hSuXr2KPn36oGzZshg3bhwSJkyIbt26mT7ziGv+fMWKFaZuR6Pg7969Oy5duoTUqVOjXbt2SJ8+vUnMzf+zbQMGDDDX8d+O3nuexsVk4AwlL1euHNq0aYNt27aBib158tbw4cPNrSha58+fb47YvnbtGl544QUMHTrU9GH06NG4cOGCcbyyvyVKlDBt+OWXX0C9xP8PGjQIf/75JwYPHmz6mjZtWuOgZftoy5cvNyyoK6tXr46PP/4Yn3zySaQCmW3hIsBff/1lmF6/ft04gK1TwSK6V7JkyUxbvv32W+MZ3759OxjRx1PLUqZMiUOHDhmdSs7vvPMOsmXLhkSJEplob47NqFGjwFPJ2E9Gg7/88sum7VG15WEfWpcC/ffff0f79u1Nxwli//795j48G53u/zlz5ri8b506dcwqBAHwWLVWrVqZFZ748eOb644ePWpEPwcxNhkfuKZt9+HEP/fQYcBNlDi5FAWDkuG73VeUJC42DaTaKgIiEG0CmhfsIXMU6I2TZEPRzypi/6F76NfNH1lv/YKro3rAP09hBA+faa9ClRIBERABEcBHFw5j943zT5xEw6RZkScw/J7oK1euoEaNGvjyyy+NCD9+/LhxSlJQ16xZ0wg+Ck4KWIq93377LZxA5xbglStXmiOojx07ZrYEf/755yZPF0U3w8RpDF+fNWuWiUqOyCicqbMsDzqFMwVky5YtzVZiJvxm1LIrgZ4nTx7TXh6LzfZTv/F41eLFixsRT6H6xhtvmEUI9oeinmL75s2byJgxI7Zs2YIJEyYYxyyFc6dOncy/aXfv3kWtWrXMQgHD8CnI+dmiRYvMAga97dbiw1tvvWUWKBh1HdkedIpitmfNmjVInDgxNm7cCF7Hn7m6F+/TpUsXlCpVyowDtSx/xr6SLd9vuMjguHDB9nNhgePXv39/s0DRtm1bs5jBsXXVlkd5SF0K9ObNmxuQHGQOHPdOWMKanSE8V0ZgPXr0MCs5fGi5+lCvXr2wS7766itMnTo1Voa4N395n0n4M2KAP9KfnGf6dPOfZLjxthL/PMoDqWtFQATcm4DmBXvj4yjQGyXJipKfV8Ke/ffQp4s/cvjtw5XBHeCXNScSjH/DXoUqJQIiIAIigCZHvsAHF35/4iSWZXkOXGx1NArZ5557zoha6hsrsphimWKOW3odjcLZ0YNO4cdkaJZRTNetWxdVq1Y1DswxY8YYrzC91dRhkSXWjkigU+BTlPv4+Jjq7Qh0ClZLFFOo8t7UexTb7B/bFZmFhISgWLFixqvuLNDJg2LfOrqbp8Hkz58fv/76q4ksoNBnH2mMROB9uSjhSqBzEcNakKDHn9zYflf3ophmNADZcMGAvLlQMHv2bPTu3RvVqlXD888//4BAL1SokFmAYFQDjYso9PDT6886I2vLozykLgU64X3//feIFy9eOIF+/vx503hCiMr++OMPI+xz5cqFrFmzhitOkNyP4WrAo6r/aXxOD3qrTvvw59H7CX8ynb4v0EMCS+DqyB7wz10QwSNmP42m6Z4iIAIi8FgJaF6wh5cCPV/50mif4SwaJsmK0l9Uwq6999Crkz9yJ/gTl/u0gG+6TEj42lJ7FaqUCIiA+emSJQAAIABJREFUCIiAW3nQORx///23iShmaDi9qvyzadMm48198803w42Ys0AfP348Pvjgg7AyQ4YMMXqLybPffvtt49yksGX4OcU+T8aKyCIS6JMmTQrncY9IoJcuXdp4oSmEed/du3eHCXqKX+YQY1sofvn/AgUKhLs9NSLDwelFp/30008mSsBZoJMHvfOO4fkMyWef6JVn+DkXOSyj0KcIdiXQeU/WSaMuZSQD2+PqXgx9nzt3rvHQd+3a1USEV6xY0YhvbrnmnnkydvSgM7yd27PJxjKOI0PqKdIp0CNry6P8uroU6HwguDrA0AtHDzrDMfjz9evXP8q9Y+21FOhtu+7D4T/uJ/zJelYCPdYOphouAiIQLQKaF+zhchTo9RNnQfmvKuPX3ffQvYM/8qU8hctdG8An+TNINPdjexWqlAiIgAiIgNsSYF4tRhxTNCZPntyERVP8OpqzQOeec0YTW0ZxTy85HZcUnfXr1zdedHqZXWV+Z8g4naGOIe6Wp96qm3utGVJuLRrQk5w3b17jdbYEuhUpzWscBTr7xfB7RgtYxr3fVapUMfvSs2TJYkK/GTpOgc4tzB07dgwLcadD99VXXzV7y52N/aIHnPvUaYxKYLvYXlcCnblwGKXtLNBd3YveeUaGc28/+dKTzugAes3JxYp44D50inXen5yY1I8LHAxzpzl70CNry6M8rC4FOuPxOZjsAMFx1YGrI1zV4QNjJY17lAbExmsp0F/uvg8HD9/DgJ7+yH5BAj02jqPaLAIiEH0CmhfsMaNAz1++NNplOIt6iTOj0uYq+OW3e+ja3h8FM13GpXY14ROcAIkW3d+jJxMBERABEYhdBBgFzCTamTNnNnufKRiZQK1y5cpG9NH7TVFLLyxDzZmIzDHEneHjr7/+uhG6FO/M+0XBboVSMwSb+9xZzpXm+uKLL4zHnvqM5rgQYBHlHnfmBGNZ7penGGVYt7XX29ERy2scBfpHH31kxDXFNJPasc8MaW/QoIHxWDPSmsnxGEnAsHV6x+mRpqhl3jGKbrafXmvu26boZYQ1hT2ZcE837/HMM8+YftA7HdUe9MhEsat7sV/cc872jR071oTSM5ke78nFBSvMnmPIBHk8dYbGxRb2m1rY2oPOvGrMM0AP+hMX6GwU3f4U6dw4z04zqx1XRbi64K1Ggd6p1z7sO3gPfbv5I9dlCXRvfRbUbxHwRgKaF6IedSPQK5RGu/RnUSdxZjy/tQp+2nkPndv6o0iuEFxsXslUkvjDbVFXphIiIAIiIAJuR4AJtOn1pgeYidiojegp9vPzM4m1KfIY7k0BSw8thaGjQJ8yZYrJZL5jxw5zPQWio75i8jmKaIZuWwm2I4JAzzC93AzhpghmaLqzB53XUUAz+pkefm49Zlg+vfNRedC5+DBjxgyT0I7h3BTbFK0M0edR2QxRp4edIeNW1ABD7LnnnB5rimF61Sn6yYX1cQGDQpxGLzwjs8mNwp79ZdK3h/Ggsz5X9yIDJsvjHncumnD/OCMD6YS2IgTIiG2mx5wLGVxgYdt5TWBgoOkrQ/J5/VMT6G732+AGDaJA7/rKPuzedw+9O/sj7zUJdDcYFjVBBERABNyGgKNAr504E6pvq4ofd9xFx9Z+KFbIFxcblZFAd5vRUkNEQARE4MkSoJebAp3e28iM4pce7+nTpz/ZxuluT52AyxB3hmrwLDvnpABcQeDGeK6O2DGGZnB/hLMxNKRx48ZhWf3s1OUOZSjQe/TfZ/YT9ujgjwI3JdDdYVzUBhEQgcdPQPOCPcYU6AUqlEbb9GfxYqJMeOG7qvj+p7t4uaUfShTxxcVWVYEb15Fo8Xr4xAu2V6lKiYAIiIAIeASBiMLQHTtGTzXP26ZX3Qq17tu3L3juuaPR+9uvXz+PYOLcCW/rr2P/XQp0CnNuhHfMuseLmQiBCQzsnl/ObHw83N3ZWA/3aTChQGwyCvTeg/Zhx6/30LWdPwqH3Bfoocmq4Er/NvBNkQoJ53wUm7qktoqACIiALQKaF2xhgqNAr5UoI+r+8Dy+3X4X7Zr7oVQxX1zqWAf3LpxFonmfwCdpCnuVqpQIiIAIiIBHEHAl0Bk6zuPXKNAZsi7zPgJRHrPG2PsMGTKEI3PixAmzd2DXrl0uiTG5HBMBMOEB9xQ4Gvez8/rChQtj5syZsYo8BXrfoftNuGInhivenW/af69IZ4UtxqqRVGNFQASiS4DHrGleiJoaBXrBCqXRJv1Z1EyUEQ1+fB7bvr+L1s38UKaELy73aoa7J44i4fT34Jsm/Bwbde0qIQIiIAIiIAIi4KkEXAp0pp5nUgJmbA8KCjIMmKmOSQ/OnTvnMuU/y1LIb968GRMnTkSXLl3CMfT19UW6dOnMhnwmRohNRoE+YNj+sHDFkpBAj03jp7aKgAg8PAHNC/bY3RfoZdAm/RlUT5gBTXZUw9Zv76JVEz+ULeWLK4Pa487h/Ugw4Q34Zclpr1KVEgEREAEREAER8HgCLgU6BTaFNbPhZc2a1WSrO3z4sMk4yGx3zp71yGgxNT/P8vMUo0AfPHI/vvnhLtq+5IfSfhLonjK26ocIiIBrApoX7D0hjgK9WsL0aL6zOjZtu4vmjfxQobQvro7sgdA9OxA8Yhb8cxeyV6lKiYAIiIAIiIAIeDwBlwKdvWeIOvePHzlyxKTF51l/JUqUAD3gdo3Xpk2b1py7R2NKex4Az5/VqlXLCP/YZBTor47ZH+YNKRdHAj02jZ/aKgIi8GgENC9EzY8CvVCFMmid/gyeT5geLX+rjq+23kWzBn6oVNYX1yYNRMhP2xB/wEQEFCkddYUqIQIiIAIiIAIi4BUEohToMUHBOi+uSpUq5vw8HlLPM/qOHz9u9rIzK3BsMgr0EeP3Y9PXd/FSQz9UCpJAj03jp7aKgAg8fQKeNi84E3UU6M8lTIe2u2rgyy130aSeH6qU98X1maNwe9sGxO8xHAFlnnv6A6IWiIAIiIAIiIAIuAWBKAU6swzu2bPHHNLubB07drTViYIFC2LLli3mwPf33nsP69atM4fEU6A3a9YMW7dutVWPuxSiQB89cX/Yy9ZzwRLo7jI2aocIiMDjJ6B5IWrGRqBXLIPW6c6gSoJ06LCvBj7/6i4a1fFD1Yq+uL5gMm5/uQrxOvRHnCovRl2hSoiACIiACIiACHgFAZcCff78+Zg3b57JtG4liXOkMnv2bFuQChUqhG+++cbUUaNGDQwePBhly5ZFSEgIKN65ABCbjAJ93JT95mWrYW0/DEj1EX69cQ5/5GuOpL1a4+7ZU0g4ezl8U6aOTd1SW0VABEQgSgKaF6JEZAo4CvRKCdKi8/6aWL/xLhq86IdqlX1xY8kc3FrzPoJadkPcWk3sVapSIiACIiACIiACHk/ApUCvUKECli5darKtP4rR0846uG9x+/btWLNmTVjCudatW+Prr79+lOqf+LUU6BOn7cdnX9xFvVp+mJRhDbZcPYFN2Wuj6NRxCN27E8HDZ8I/T+En3jbdUAREQAQeJwHNC/boUqAXrlgWrdKdRsUEadD9UC18uuH+nFHjOV/cXL7I/Als1A6BDdrYq1SlREAEREAEREAEPJ6AS4FesWJFbNq06ZEhnDp1CuPHjzdJ5vr164f06dObOj/77DP8+eefDxzB9sg3fMwVUKBPmbkfa9bfRe0afpiaSQL9MSNX9SIgAm5CQPOCvYGgQC9SsSxapjuNCgnSoNfvtbDm87uoU8MPtZ73xa21y3DjndmI+0JTBLXoaq9SlRIBERABERABEfB4Ai4FevPmzTF69GiTuV32HwEK9GlzDmDlp3fMi9b0rGvlQdcDIgIi4BUENC/YG2ZHgV4uODX6/vkiVn12By9U80Xt6n5m/zn3ocd5rg7ivdzXXqUqJQIiIAIiIAIi4PEEXAr0FStW4LXXXkODBg3Mmedx4sQJB4RHpNkxes4/+OADrF27FvSmf/nll+aybdu24dq1ayaTe0wbz16fPn06bt++jeeeew4jR46En5/fA7e5fv06Jk+ebNrEo+OGDh1qyrsyCvRZ8w7go9V3UL2KL2Zll0CP6fFTfSIgAu5JIDbPC85Ef/vtNwwcOBBnzpxBzpw5MXXqVKRMmTJC8G+//Tbeffdd3Lp1y+RSGTBggMsBchToZYNTY8BfL+ITLupW9UWdmn4I2fYFrs0ciThlqiJej2HuOdhqlQiIgAiIgAiIwBMn4FKg16lTx2WDVq5caavBTCZHcU7Py7hx47B3715z3U8//YRhw4aZUPeYtD/++AMtW7bEsmXLzMvWK6+8YpLRtW3b9oHbdOrUCbly5TJh9gEBAbaaQYE+d8EBfLDyjsnGOzeXBLotcCokAiIQ6wnE1nnBGfydO3fMYuyIESNQrlw5UIB/++23YBI8Z1u0aBG+//57TJgwAUmTJrU1ho4CvXT8VBj6d+2wRd36L/iZM9B5FnpA0TKI33+CrTpVSAREQAREQAREwPMJRHnMWkwgYMZ2vvxkyZIFefLkCcvafuHCBZPNfffu3TFxm7A6FixYgMuXL6Nv3/thg/v27cOgQYPgvKCwf/9+DBkyBPS2R8co0Oe/eQDvfXwHlcv5Yn5eCfTo8FNZERABEXjS84Iz8V9//RVjxozB8uXLzUeM9CpVqpSJpkqQIEFYcQr5SpUqmfkjSZIktgeOAr1oxbJoke40no2fCsNO1MbyVXfwfCVfc/pH6J4duDqyB/zzFkbwsJm261VBERABERABERABzybwRAR63rx5jfchODg4nED//fff0ahRI+zYsSNGKfMYt6JFi6JevXqmXoYk8v+7du0Kd5933nnHePN5xvvhw4eRKVMmDB8+HKlSpXLZHgr0NxYfwJIP76BCaV+8UeA/gV78nbdwe8s6xOsyGHEq1IjRfqkyERABEfAUAk96XnDmtmrVKuMxnzhxYthH3M7FqK78+fOH/ezAgQMmnJ3ifcuWLUa8M9kp5xRXRoFerGI5NE93CiXjP4PRp+pg2Yo7eK6CLxrX9cOdI/txZWB7+GXNiQTj3/CUYVU/REAEREAEREAEHpGAS4F+5MgRk3394MGDRuQ6Gvdz82xzO/byyy+bF57u3buHCfSLFy+iT58+SJQoEaZNm2anGttlWG+VKlXMPkHLKKrZDx8fn7Cfce85w+tff/11s/+QR8p99dVXYDijZV27Pphdd8OGDXhryQEsfv8OypbyxVuF/hPoJdetw82P3jLH5vD4HJkIiIAIeBKB2DovOI8B86JwgZb5SSzjNqxu3bqhZMmSYT/bunWr2QLF+YL5UngNt0ZxHogXL54pxznj559/DncLzpkVX6hhBHqJ+Ckx7nTdsKirpvX9cPfEUVzu1Qy+aTMi4bR3PekRUV9EQAREQAREQAQegYBLgd6kSRNQ2HLPIT0I3D/O/d2LFy82yXRy585t69YnT5404pwh7ceOHQM9J/SeUxTPnTsXyZMnt1WP3UIMWy9QoIDxztPoIecLl3MoPRPgMTEcPR00hjLSK0KPviXkKeqdrWbNmnjnvQN4c+kdPFvcF+8UlUC3OzYqJwIiELsJxNZ5wZn66tWrjUecc5lltWvXxqhRo8z8YRkXoplH5f333w/7WYsWLcJym/CHnOOuXLkS7hazZs1CySoVjUAvHi8lJp6vi6Uf3kHFMr54qaEf7p0/i0ud6sAnaQokmvdJ7H4o1HoREAEREAEREIEYI+BSoOfLlw8//vgjAgMDwYztTPRGo4CdNGmSScIWHaOHgcKcQjhbtmwoXrx4dC63XZbeDGaL575zGjP1UrSvWbMmXB3ce2jtQ+QHzPjOMEZnT4jzjblo8e4HB7Dg7TsoUcQX75aQQLc9OCooAiIQqwnE1nnBGfqePXvMvGDlJgkNDTVzEqOoEidOHFb86NGjaNeuHb744ouwnzVu3Nhsh3K1SO0Y4l40XgpMvVAP73xwB+Wf9UWLxn7A9Wu42Pp5+MQLRqLF62P1M6HGi4AIiIAIiIAIxBwBlwKdYvXTTz81WWvpWaAHgSF9FLKFChUKS/YW3ebcu3cP/EPv9eOw48ePo1mzZqa9Vhb37Nmzm9BFekxOnDiBpk2b4tKlS6hWrRrefPNN86LF7L18aZs503XCHgr0ZR8dxOuLQlG0kC+WlZJAfxzjqDpFQATcj0BsnRecSTIpHL//X331VZOslIlMmSBuyZIlJmEcQ98Z+cUIL0YN1K1bFxTmXKDmNiqGuDsfPep4Dwr04hXL4aV0p1AkXgpMv1wPi9+7gzIlfdG66f0jPy82KmP+TvzhNvcbaLVIBERABERABETgqRBwKdD5ElK+fHkjzq1zxFu3bm08DHyZ2bhxo8tGU8hzf/ehQ4fMnnCGylMEM6ydAt06n5zJ42La6O1n8p+bN2+aPjA8ny9TCxcuBJP+TJkyxdyS+wuZyZfnsTP0fuzYsVGG3FOgL19xELPfCEWh/D5YXuZTbLl6Apuy14b2oMf0SKo+ERABdyIQm+cFZ448yaN///5m0TZr1qxmXkifPr3JucI5i9FY/L6nF53l+DcXfTkfOobBRzQ+FOglKpZHs3T/oFBQcsy+Wh+L3r2/LartS/8K9OaVgdu3kHjpV0CcOO40zGqLCIiACIiACIjAUyLgUqCfP3/eZKzl+eAMGe/QoYNJkMPwP77IUPi6Mr7EbNq0ySRroxBu2LCh8WpboedMusO94UOHDn1K3X+42/KFbcWqg5gxPxT58/hgRXkJ9IcjqatEQARiGwHNC/ZGzFGgFwxKhtevN8AbS+6gZFFftG9xX6BfevkF3Lt0AYneWAufhP+F1du7g0qJgAiIgAiIgAh4IoFoH7PGRDj0eDtmQ48MTIUKFUwWeIZEMokOPRJMtlOxYkVzyU8//WQS7TDsPDYZBfqqtQfx2txQ5Mnpg1WV/hPoz/68E9fnjkOc8tURr+uQ2NQttVUEREAEHoqA5oUHsTkK9AJBybDwZgPMf/sOihf2RYdW9wX65e6NcPfUCSSc9SF8n0nzUOx1kQiIgAiIgAiIgGcRcCnQ6fFmIjVnu3HjhtmLxyy4rixXrlzmKDbuYacxJJCJ2jJkyGD+zz3gxYoVM8efxSajQF+77iAmzwpFzv/54Gq9XzDy5E+Ylr40up0JxdWRPeCfuyCCR8yOTd1SW0VABEQgSgKaF6JEZAo4CvR8QUmx6HYjzHsrFEUL+qBTG39T5krfVrhz9DASTnkHvhmy2KtYpURABERABERABDyagEuBTvHMLO7OdubMGVSuXNlkR3dlFLI7d+5E/PjxTTHWR4GeKlUq83/u+y5YsKDZox6bjP1at+EgJkwPxf+y+OBGw/sCfXjqohh6wU8CPTYNptoqAiIQLQKaF+zhokAvWak8mqb9B3kDk+KdO40w581QFM7vgy7t/hXog9rjzuH9SDDhDfhlyWmvYpUSAREQAREQARHwaAIRCnRmrmUSNyaDq1SpUjgAPCJt165dKFy4sK1s50wIFzduXFNHz549MWLECCRJksT8n4l4unTpEisF+oaNBzF2aiiyZPTB7SYS6B79W6LOiYAImIzmmhfsPwgU6KUqlUeTtP8gd2ASvHevMWYtDEWBvD7o/vK/An1YF9zZ/xsSjH4dfjny2a9cJUVABERABERABDyWQIQCnRltN2/ebLKgU0A7Go9GS5cuncnA7u9//yUjMosqiZx1XWzcg75x80GMmhSKjOl9cKeZBLrH/oaoYyIgAoaA5oXoPQiOAj1XYGJ84NPEJBbNl9sHPTvenzuvjuqJ0N0/I3jYTPjnLRy9G6i0CIiACIiACIiARxJwGeL+8ccfo379+h7Z8UfpFEPct2w9iGETQpEujQ/QQgL9UXjqWhEQgdhDQPOCvbFyFOg5AxPjI78mmPb6/cSivTv/K9DH90XoL98jePAU+Bcsaa9ilRIBERABERABEfBoAi4F+oYNG5AjRw5kzJjRQPj666/NubBp06ZFv379kChRIo+GE1nnKNC3fXMIQ8aGIPUzgF/rndqD7pVPgjotAt5HQPOCvTF3FOjZ4ybCyjhNMXVOKHJl98ErXe8L9GtTBiNk+1bE7zceAcXK2qtYpURABERABERABDyagEuBXr16dYwZMwZFihTB6dOn8fzzz5t9iDwLnXsRp06d6tFwXAn0774/hIGjQpAyORCn3X8CfZh/Olzu1hC+KVIh4ZyPvJKPOi0CIuC5BDQv2BtbCvRnK1VA47Qn8b+4ibAmsKk5+SNHNh/06/6vQJ8+HCHfbkT8XqMQ8Gz4fC/27qJSIiACIiACIiACnkbApUDPkyePOas8KCgIr732Gs6ePYtx48aZ49G4B3379u2exsNWf+hB3/7jIfQbHoJkSYCgDv8J9BFpiuFiozKmnsQfbrNVnwqJgAiIQGwhoHnB3khRoJeuVAGN0p5E1rgJsT5eM0yYcf/kjwE97wv063PG4vaWdYjXbSjilKtmr2KVEgEREAEREAER8GgCLgV6yZIlsXbtWsSLFw8VK1bEkiVLkD17dty8eRNFixbF7t27PRpOZJ2jQP95xyH0GRqCRAmBBJ0l0L3yQVCnRcALCWhesDfojgI9S5yE+CJBM4ybFoqsmX0wqNe/An3BJNz+cjXidRyAOJVfsFexSomACIiACIiACHg0AZcCffTo0eZItbt37yJNmjRhx6r98ssvGDhwID7//HOPhuNKoO/89RB6DgpBcHwgcTcJdK98ENRpEfBCApoX7A26EeiVK6JRmhPIFCcBNiV6CWOmhiJzBh8MeeW+QL/x1nTcWvcRgtr2RtxqSshqj6xKiYAIiIAIiIBnE3Ap0ENDQ7F8+XIj0Bs0aBB2njlD269evfrAGemRoTp27JjZr75v3z5cu3btgWLbtsWuUHB60HftPoRu/UMQFAQk6yGB7tm/JuqdCIiARUDzgr1ngQK9TOWKaJjmBDLGCcbWJM0xavL9ozlf7fuvQF86F7dWv4eglt0Qt1YTexWrlAiIgAiIgAiIgEcTcCnQY6rnTZs2RebMmU2SucDAwAeqLVGiREzd6onUQ4G+d+8hdO4bgjhxgJS9JdCfCHjdRAREwGMIeNq84DwwjgI9Q5xgfJOsOUZMvH8054gB9wX6zWULcXPF2whs2hGBdVt4zNiqIyIgAiIgAiIgAg9PIEKB/uWXX5q95r/99pvLmmvVqmXrzmXLljVHtHmKUaAfOnQI7XuGmC6lGyCB7iljq36IgAhETEDzQvSeDAr0spUrokGaE0gXEB8/pGyBYeNDkSa1D0YN/Fegf7wYNz94A4ENWiOwUfvo3UClRUAEREAEREAEPJJAhAK9ZcuWePHFF7F06VKXnV65cqUtKPScr169OixE3tZFblwoKoF+pV9r3PnrdySY9Bb8Mv3PjXuipomACIiAPQKaF+xxsko5CvS0AfHxc6qWGDI2BKlSAmOGBJhiDG+/sXQu4tZ+CUEvdY7eDVRaBERABERABETAIwk8kRB37mPfuHEj2rdvj9SpU8PPzy8czFSpUsUquM4CPe+Qfeh97BsMT10UPGbt6ohuCN27E8HDZ8I/T+FY1Tc1VgREQASeBAFPmxecmTkK9NQB8bAzTSsMHh2ClCmAcUP/FeifLceNxTMQt0YjBLXu8SSw6x4iIAIiIAIiIAJuTsClQGdyOCZ2Y5I3imruI8+WLVu0u7Rhwwb07t0bt2/fjvBahovHJrMEepd+IWCXmo48gyqHV6F8cBpszlFbAj02DabaKgIiEC0Cmhfs4aJAL1e5IuqnOYFU/kHYlb41Bo4MQfKkwITh9wX67S9W4vrCKYhTtQ7ite9rr2KVEgEREAEREAER8GgCkQr0H374AYMHD8bRo0cRHByMOHHi4Pz588iRIwcmTJiAvHnz2gZTqVIldOzYEdWqVYswSVzcuHFt1+UOBS2B3n1gCG7cABoNP4Pn/5BAd4exURtEQAQeHwHNC/bZOgr0Z/yDsC9ja/QbHoKkSYBJI/4V6Js/w/W54xCnYk3E6zzIfuUqKQIiIAIiIAIi4LEEIhToBw4cQP369c3Rap07d8YzzzxjAPzzzz+YM2cO1q5da/aUp0+f3haYcuXKYevWrbbKxoZClkDvNTgEV68BDV49g+p/SaDHhrFTG0VABB6OgOaF6HGjQC9fuRLqpfkbKfwDcShzG7zyaggSJQSmjr4v0EO2fYFrM0ciTpmqiNdjWPRuoNIiIAIiIAIiIAIeSSBCgc4XC4a08+zyiKxHjx5ImDAhxowZYwtKkyZNMGPGjDChb+siNy5kCXS+bF26DNQbcgY1j0mgu/GQqWkiIAKPSEDzQvQAOgr05P6BOJK1DXoPCUHCBMBrY/4V6Nu34NqUIQgoWQHx+9ibT6PXCpUWAREQAREQARGIbQQiFOilSpXC7NmzUaRIkQj7s337dgwYMACbNm2y1V963KdNm4a6desiTZo0Jlze0ewe12brZk+gkCXQ+48IwfkLQJ2BZ/DCCQn0J4BetxABEXhKBDQvRA+8o0BP6hcXR7O3Rc9BIYgfD5gx/r5AD93xHa5O6IeAIqURf8DE6N1ApUVABERABERABDySQIQCnWegf/fdd0iWLFmEneZe9DJlymDv3r22oNSpU8dlObvHtdm62RMoZAn0QaNCcOYc8EL/M6jzz38CnVl5b322HEGteiBuzUZPoEW6hQiIgAg8XgKaF6LHlwK9QuXKqJvmOJL4xcXfOdui+4AQBAXh/+ydB3RUxRfGv3RICEQp0osgIB0ERKVK74gUQUR6E1SKSBGkicCfjihFmooiRWmCIFWKKCC9g4AgvYT0vv9zB17Y3Wx23yabsptvzuGQZOdN+c3bN/O9e+cO5kx6ItBPHELI+A/hWa4Ksnwyw74KmJsESIAESIAESMAlCVgU6CJAjx49Cj8/P4udDg0NRYUKFeBs0dcdNYKaQP/ks2jcugM0HXIXre88FegRKxchYvXp9JFKAAAgAElEQVQSZGrTFZnadXdUtSyHBEiABNKMAOcF+9AbC/QAD2/cKtUd730UDR9vYO7/ngj0s8cRMrofPEtVQJYxX9hXAXOTAAmQAAmQAAm4JIFEBXrXrl3h5fV4EWGeoqOjsWTJkiQJ9Dt37sBgMDj1fnRNoH86KQb/3TSg8aC7aHOPAt0lvyHsFAmQgCIgzz3OC/pvBmOBntXdC48q9kCPD6Ih0+pXUx/PrbEXzyB4RE94vFAa/p/N1184c5IACZAACZAACbgsAYsCfejQobo6PGXKFF355NzchQsXYsGCBQgKClLXyNFtPXr0QJ8+fVRAOmdKmkAf978Y/HvdgAYf3kX7BxTozjSGbCsJkIB9BDgv2MdLBHqdunXRKu91+Lt7IeiJQJdSvp71RKBfvYjgj7rAo/AL8J+yxL4KmJsESIAESIAESMAlCSR6DrojeysB4rZv345PPvkk/vz0kydPqijwderUweDBgx1ZXYqXpQn0z6bH4PJVA+q9fxcdAinQUxw8KyABEnAZAq42L5gPjLFA93P3REjFnsqCbizQ4278i6APO8I9XyFknbHcZcaWHSEBEiABEiABEkg6gVQR6BL9d+nSpShRooRJS+VcXXGZ3L9/f9J7kAZXagJ90qwYXPzHgDr976JTEAV6GgwFqyQBEnBSAq42L1gS6K/Xq4uWea7D190ToZYE+p2bCOrfFu658iLrFyuddCTZbBIgARIgARIgAUcSSBWBXqpUKcjRbOLWbpyCg4MhizSxpjtT0gT6/76IwbkLBtTqexedQ58K9KhdmxD25UR412oM3/dGOlPX2FYSIAESSBUCrjYvWBLo9erVQ/M815DZzQNhlXolsKAbHt7Do96t4PZsDmSbtzZVuLMSEiABEiABEiCB9E0gVQT6m2++iXbt2qF9+/YmNJYvX44NGzZgxYoV6ZuSWes0gT79yxicPmdAjd530SX8qUCPOfU3Qsa+z8i8TjWqbCwJkEBqEnC1ecGaQJfPDC/1Rd8h0YiOfhwkToLFGUKC8ahbY7j5Z0O2Rb+kJn7WRQIkQAIkQAIkkE4JpIpAP3jwIHr16oVKlSpBrCYSxV3OUJej3JYtW4ayZcumUzyWm6UJ9FnzY3DitAGv9byLbpEU6E41iGwsCZBAmhJwtXlBj0B/b2g0IiMfH7Mmx60hMgKB79QDMvki4JutaToerJwESIAESIAESCB9ELAp0CMjI3Ht2jWEhIQkaLGcha433bt3Dz/88AMuXbqEmJgYtR9drOrPPfec3iLSTT5NoM/9OgZHThjQukc4mkYtR4XM2XGkVDvQgp5uhooNIQESSAECnBdsQ5UgcZqLu+QWC/qAYdEIDwfmTPZC5kyPywhsV139H7Byr+1CmYMESIAESIAESMDlCVgV6Lt27VIR1qOiopAp05PVhBESsYDoSWfOnEGxYsUSPVddTxn25lmzZg1mzpyp2l6/fn2MHTvW6nFue/bsQbdu3VTAupw5c1qtThPo85bE4NBRA/p280TlmHnqGlmExV65gOChXeFRuBj8pyy1t+nMTwIkQALploAzzwupCdWSQP9geDRCw4BZn3vBz5cCPTXHg3WRAAmQAAmQgLMQsCrQGzdujIEDB6JBgwbJ6o+4tW/btg158+ZNVjl6L758+TI6d+6s9rbnypVLvWQQa78IcEtJvAMkf0REhHK51yvQF34Tiz8Px6HXux542TA/XqDLD7SK6B0t5iMBEnAmAs46L1hifPz4cQwbNgx3795FyZIlMW3aNDVnJJYkn/R/zJgxaNasmdVhsyTQB30SjaBgYMZnXvB/EjM1sFNdICqSFnRn+hKwrSRAAiRAAiSQggSsCvTatWtDrCXJTW3atEHv3r2VJTs10oIFCxAUFIQhQ4ao6sSCP3z4cKxdazlKrnz26quvQq5bvHixboG+eHks9v8Vh+6dPPCqOwV6aowt6yABEkhbAs46L5hTi42NVXOSiO2aNWuql7PiQTV//uNnuaXUp08fhIaGqoCnSRHog0dF41EQMG28F7JlfVzDo66NYQgNRsDSLYCvX9oOLmsnARIgARIgARJIcwJWBXrTpk3x448/Jjgezd5WX7lyRQnk1q1b4+WXX0bmzJlNirBlsba3vhEjRqBy5cqqPkmyX1J+P3HiRIKidu/ejVWrVuGLL75QlpFvvvlGt0BftiIWe/6IQ5cOHqjhRYFu7zgxPwmQgPMRcNZ5wZz0sWPHMGHCBPX8lxQXF6eO/RRvL39//wQDIy94Dx06pLZ7iUdWUgT60DHRePAQ+N9YLzwT8ESg92wOw6OH8GnREZnbdAUymc6PzneHsMUkQAIkQAIkQALJIWBVoG/duhXfffcd+vbti4IFC8LbW8LOPk16hfVLL72kLNqJpQsXLiSnDwmuHTRokArO06RJk/jPZN/4+fPn4ebmFv83OYf97bffxtKlS/Hss89aFOhifTdPLVq0gLT5u5Wx2LUvDu+080DtTBToDh1EFkYCJJAuCTjrvGAOc926dcpiPnny5PiPxNtr9OjRKFeunEn2O3fuoGfPnpCjQadOnape+BoL9Fu3biWY4+bMmYOGDRuqc9AlSXySYWOjce8BMOlTL+R49nEVQf3eRNy92+rnbPN+htuz1mOgpMubgo0iARIgARIgARJwGAGrAl0WKeEScjaRpFdYi0ugteTn51i3vpEjR6J8+fIqSrwk2WNerVo1nDx50qQZH3/8McRdUyznkixZ0AcMGJCg6b/++qsS6D+sicX23+PQ8U0P1PUzFeghY/oj5vRRZPl0NjxLV3LYgLEgEiABEkhLAs46L5gzE+8wOe5TAohqqVOnTujfv7+aL4yTbNHq2rWr+ru4xJsLdNkaJdZ14yQBSlu1amUi0EdMiMadu8DEUV7IleNx7sjNqxGxcpFyc886ZyXcn0udWC1peQ+xbhIgARIgARIggcQJWBXoyRXWX3/9NWTBo0WAv3jxIgoVKpTi0dxlsXT79m3lVi9JAgGJaN+wYYMJidKlS5t4BUh/5WWBLNjESp5Y0qK4r1wbi60749C+lQcaZKVA5xeNBEjA9Qk467xgPjLr16+HbHGSwHBaatmyJcaNG6de8GpJTgSRl7uffvqp+pMlgW5p1C0Fifvks2jcugNMGOmF3Eax6IIGvo24/64i6/Tv4J6/sOvfROwhCZAACZAACZBAogRsnoOeHHYiZP/880/lPi6pYsWKSiTnz58/OcXavPb69evo2LGjOnddi+JevHhxZRmRBdmNGzfQoUOHBOXYuwd9zYZYbN4WhzYtPNA4gALd5sAwAwmQQIYnkFbzgjn4U6dOqRe3WvDQmJgYVK1aFTt27EBAwJMN4oCynB89ejT+colp4uHhoWKcGFvfzcvXBHrbvDcQYYhVLu6jJ8Xgxk0Dxg33RN7cRtuthnZVx3P6T1kCj8IvZPh7hABIgARIgARIICMTsCnQZWEi0c3FpdtgMKjzzLt3744qVarY5JaWC7GNGzeqvYVydFqtWrUwceJEZS1fuHAhzp07p/YRmid7BfraTbHYuCUOrZp6oHl2CnSbNwQzkAAJuAQBZ50XjOFLULhGjRph1KhRqFGjhoriLgHivv32WxUwTsS3bHHKkeOJL/qTi+21oLfLewPhTwT6mMkxuH7DgDEfeyJ/XiOBPrI3Yi+cgv9n8+HxQmmXuEfYCRIgARIgARIggaQRsCrQN23apBYvcka4uINLgDVx9ZNI5+LuZ80NXJqTlgI9aTj0XaW5uG/YEod1m2LRorEHWuY0FejhS2chctMqZH73ffg0fbwXnokESIAEnJ2AK80LZ8+exdChQ5VXVdGiRdWL2wIFCqiTPyTQqGyXkue9cbJXoLfPdxNhcTEIq9gTU6cDV68ZMPojTxTM/1Sgx8csGfMFPEtVcPZbhO0nARIgARIgARJIBgGrAr1BgwbKBVAs0MZJzkYXi7RE87WWZGGzZ88ePPPMMyqbBNiR/Xz58uUzuczHxycZXUj9SzWBvum3OPy0MRZNG7ijde4FqiHixihJgv5ErF6CTG26IlO77qnfSNZIAiRAAilAgPOCPqiai3uHfDcREheD0Io9MWMGcPlfA0YO9kSRgkYCfcJAxBw/iCwjp8OzfFV9FTAXCZAACZAACZCASxKwKtBffPFFFZnWPMq6REWXvXoSAdeWQNdDTW80eD1lpUYeTaBv2RGHVeti0aiuO9rmo0BPDfasgwRIIG0JcF7Qx18T6B3z3UJwXDSCK/bAnNluuHTZgBEDPfF84acCPXTKMEQf2gu/oZPgVbm6vgqYiwRIgARIgARIwCUJWBXodevWxWeffZbgyJm9e/di/Pjx2LJli1UoEqxNT0rpoHF62mBPHk2gb9sdhxU/xaJ+bXe8VZAC3R6GzEsCJOCcBDgv6Bs3TaB3yn8bj2KjEFSxB76c44YL/xjw8QeeeOF5I4E+fRSiD+yE36Dx8KpWR18FzEUCJEACJEACJOCSBKwK9BUrVmDGjBkqKFypUqVUkDixmi9atEi5vsuRNBkxaQJ95944LF8Vi9druOPtIqYCPfKXlQhfNhvetRrD972RGRET+0wCJOCCBDgv6BtUTaC/k/82AmOj8KhCd8z/yh3nLhjw0QBPlCj2VKCHzRmHqD1b4TtgNLxrNNBXAXORAAmQAAmQAAm4JAGbUdx37typBPmlS5cgx9CUKFFCCfY6dTLuW35NoO/5Iw7LVsSi1qvumFZ2DY6F38flsp1Q2NsfMaf+RsjY91XAnyxjvnDJm4edIgESyJgEOC/YHndNoHfOfwcPYyPxsEI3LJrngTPnDRj8nideLG4k0OdNQtSOjfDtMwzerzezXThzkAAJkAAJkAAJuCwBmwLdZXuejI5pAn3/X3FYvDwW1V92x9KXNmJ3yA3sLN4Stf3zUqAngy8vJQESIAFnJ6AJ9C757+B+bCQeVOiGZQs9cPKMAQP7eqJ0yacCPXzRdERu+QmZewyGT4M3nL3rbD8JkAAJkAAJkEAyCFgU6Hfv3kW2bNnw6NEjq0XnzJkzGVU776WaQP/zcBwWfhOLV6q449sqFOjOO6JsOQmQgC0CnBdsETL9XBPoXQvcxb2YCNwr3xXfLfLEidMGfNDbE2VLGQn0b+YgcuOPPJbTPsTMTQIkQAIkQAIuScCiQH/11VfRqVMntf/cWtIbfX3y5Mn4+OOPLRYVFRWFzZs3IzQ0FNWrV0fBggXTPWhNoB86Eod5S2NRpZI7fqhmWaB7FC4G/ylL032f2EASIAESsEaA84J994cm0LsXuIc7MeG4W74rfljiiWMnDRjQ0xPlyzwV6BHfz0fE2m+RqWNvZGr1jn0VMTcJkAAJkAAJkIBLEbAo0OUYNV9fX4SHh1vtrPnxa4llFkE7duxYHD9+HB4eHqhXr178Hvb33nsPly9fRpEiRXDw4EEsXLgQ5cuXT9eQNYF+5LgBcxfFoFJ5N6x87RcTF3fpQGC7x8flBKzcm677w8aRAAmQgC0CnBdsETL9XBPoPQrcw+2YcNwu3wWrl3nh7+MG9OvuiUrljAT66iWIWLkImdp2U/+YSIAESIAESIAEMi4Bq3vQt27digYNEkaUjYyMxLZt29C0aVNd5ETQFi9eHI0aNVL5N23ahM6dO6NNmzYoU6YMdu/ejdy5c2PDhg3YuHEj5s+fr6vctMqkCfTjpwyYvSBGWULW1KRAT6vxYL0kQAKpR4Dzgj7WmkDvVfA+bkaH4Vb5Lvj5Wy8cOmpAn66eqFzhqUCPXPsdwr+fp6znYkVnIgESIAESIAESyLgErAr0KlWqKKu2eZJo7hUqVMDJkyd1kStbtiz++OMPZMmSReV/+PAhunTpgqVLl6Jq1ao4f/483NzcVJR4iQ6/Z88eXeWmVSZNoJ86a8CMr2JQ5kU3rK1DgZ5W48F6SYAEUo8A5wV9rDWB3rvgfdyIDsPNcu9i/fc++OvvOPR+10NtjdKSdiynT7P2yNx5gL4KmIsESIAESIAESMAlCVgU6CKYJb311luQM2+NU2xsLHbt2oWVK1dCjtrRk+rWrQuxuoh7uyTZdy5u7j/99BNeeeWVeIEun8nvIubTc9IE+tkLBkz9IkYdl7OhHgV6eh4zto0ESCB5BDgv2MdPE+h9Cj7Af9Gh+K9cZ2xakQkHDsWhxzseqFb5qUCP2roWYV9PhU/D1sjcfZB9FTE3CZAACZAACZCASxGwKNCHDRuGffv24datW/D29jbpsLu7O/Lnz4+RI0eqoG560tChQxEREaFc2sVS/sMPP+D06dNq37mI8bVr16JkyZK4du0aunbtqtzn03PSBPqFfwyYPCsGxYu6YVPDhAI9+KMuiL16EVk+nQ3P0pXSc5fYNhIgARKwSoDzgn03iCbQ+xV8iGvRIbherjO2rMwEOZ6z29seeLWqkUDf+QvCvvpcnYEuZ6EzkQAJkAAJkAAJZFwCibq4i5VbBPX69euTTUeCC82dO1eJfhHqEg140KBBygKfK1cuyMKvYsWKOHz4MHr27Kn2p6fnpAn0f64YMHFGDIoWccOWxgkFesiY/og5fZQCPT0PJttGAiSgmwDnBd2ooAn09wo9xL9RIfi37DvYviYz9h6IQ5cOHqhezUig792KsNnj4F2zIXz7j9JfCXOSAAmQAAmQAAm4HAGre9Dv37+P7NmzJ+i0RHcXV3dtT3lyqVy6dAm///47RPjqtcont87kXK8J9KvXDBg/NQaFC7phWzMK9OQw5bUkQALOQYDzgr5x0gT6gEKBuBIVjKtl38HunzNj9/44dG7vgZqvPhXo0X/uRui0kfCqVgd+g8brq4C5SIAESIAESIAEXJKAVYEuUdo/+eQTtS/cOB04cACTJk1Srul6k0R+Fxd2saabJwk450xJE+jXbxgwZnIMCuRzw86WFOjONIZsKwmQQNIIcF7Qx00T6O8XCsTlqGBcKdsJe9f5YufeOLzd1gN1qhsJ9L/3I3TSUHhVrg6/oZP0VcBcJEACJEACJEACLknAqkAvXbq0smybW9EDAwPx2muv4dSpU7qgSFC5wYMHq+BwmTJlSnCNpUjxugpOo0yaQL95Gxg1MRpZ/IBtzX/BKe+bWODZEj3L51UtC5v7GaJ2b0bmd9+HT9N2adRaVksCJEACjiPAeUEfS02gf1DoEf6JCsI/Zd/GgQ1+2P57HDq+6YHXaz4V6DHHDyJkwkB4lq+KLCOn66uAuUiABEiABEiABFySgFWB/vLLL2PRokXqrHLjdO7cObzzzjv466+/dEFp3LgxBg4caPFMdV0FpLNMmkC/cxcYMSFate6XBr/gVu6beO9sM3zxdgH1t4iVixCxegkytemKTO26p7NesDkkQAIkYD8Bzgv6mGkCfWDhR7gYGYRLZd7GwU1++G1XHNq/4YH6tY0E+pljCPn0PXiWqogsY+boq4C5SIAESIAESIAEXJKAVYE+btw4HDp0CGPHjoVYTSRJ9HX5vVy5cup/Pal27drqaDZXSZpADwsHftsVq7o13H8DzmS+iXcPN8PSXhTorjLW7AcJkIApAc4L+u4ITaAPKhyEC5GPcKFMRxz5NQu27IhD25YeaPj6U4Eee/EMgkf0hEfx0vCfMF9fBcxFAiRAAiRAAiTgkgSsCnTZNz5t2jQsX75cuadL8vT0RPv27fHxxx8jc+bMuqDInsUff/zRYUHldFWagpk0gW5cxYirB/H5vUOoefwV7O76eE89LegpOAgsmgRIIE0IcF7Qh10T6EMKB+NcZCDOl+mI41uzYPO2OLzZ3AON6xkJ9KsXIcdyehQpDv/Ji/VVwFwkQAIkQAIkQAIuScCqQNd6LOL8v//+Q1xcnDoD3cfHxy4YW7duxXfffYe+ffuiYMGCCc5Wz5kzp13lpXVmSwJ9zI2DGHvzECoeq4i/u1VTTYz8ZSXCl82Gd63G8H1vZFo3m/WTAAmQgMMIcF6wjlIT6B8VCcbZiECcK9MBp7f5Y+PWOLzR1ANNGzwV6HE3/kXQhx3hnr8wsk7/zmFjxIJIgARIgARIgAScj4AugZ7cbok7vBzNlli6cOFCcqtI1ettCfQtLashZ3Yg5tTfCBn7PjxLVUCWMV+kahtZGQmQAAmkZwKuNi+Ys9YE+tAiwTgTEYgzpTvg3E5/bPg1Di0be6B5IyOBfvcWgt5rA/fn8iLrnJXpedjYNhIgARIgARIggRQmYFWgX7lyBbLfUKK1WzoeTW8U99DQUKvd8PPzS+FuOrZ4WwJ9Ra2XUbyoGwW6Y7GzNBIggXRAgPOCvkHQBPqwIiE4FfEQp0u/hYu7s2Hdplg0b+iOlk084gsyBN7Ho14t4fZsTmSb97O+CpiLBEiABEiABEjAJQlYFeidOnVCyZIl0bx5c4v7zYsXL+6SUGx1ypZAn1ehKqpWcqdAtwWSn5MACTgdAc4L+oZME+jDi4TiZMQDnCzdHlf3BOCnjbFoUt8drZsZCfSQYDzq1hhuWQOQ7euN+ipgLhIgARIgARIgAZckYFWg16xZU52DntQ0ceJE1KhRA7IH3VoaP358UqtIk+tsCfTPC1dVEXo1F3ePwsXgP2VpmrSVlZIACZCAIwlwXtBHUxPoI58Pw/Hw+zhRqj2u7w/A6vWxaFTXHW1aPBXoiIxA4Dv1gMy+CFhmfb7UVztzkQAJkAAJkAAJOCsBqwK9Xr16Sly7uz/dK2dPR+fMmQM5M3f79u1WLxs+fLg9xaZ5XlsC/eNnqqhzbiUFtquu/g9YuTfN280GkAAJkEByCXBe0EdQE+ifPB+GY+H3cbxUO9w88AxWro1FgzruaNfKSKBzrtAHlblIgARIgARIIAMQsCrQ586dq/aef/DBB8iUKVMGwKGvi7YEei/3KujThQJdH03mIgEScCYCnBf0jZYm0Ec9H4aj4fdxtFQ73P3rGaz4KRb1arnjrdYU6PpIMhcJkAAJkAAJZCwCVgV69+7dlYu7l5cXcuXKleB4NFuu6xrKf/75B/ny5Ys/nu3mzZtYt26d+luzZs3g5ubmVNRtCfR2QZUx7ENP1Sda0J1qaNlYEiABGwQ4L+i7RTSB/mnRcPwddg9HSrXFg0PP4vvVsXi9hjs6tjET6OLiHhlBbyt9eJmLBEiABEiABFyWgFWBvmPHDqsdf/3113WBadeuHXr16gVxjYyIiEDjxo0hAeauX7+Ohg0b4v3339dVTnrJZEug17/2EiZ/6kWBnl4GjO0gARJwGAHOC/pQagJ9TNEIHA67i8MvtkHQkez4bmUsar/mjk7tTAX6o25NYAgJQraFG+CW7Rl9lTAXCZAACZAACZCAyxFIlXPQK1SogN27dyNbtmz4/vvvsXnzZnz77bdKoHfs2DFZgejSYkRsCfRKx17C17MeC/Tgj7og9upFZPl0NjxLV0qL5rJOEiABEkh3BFxtXjAHrAn0cUUjcDDsLg692AZhx7Jj2YpY1HjFHe++ZSrQ5Rz0uLu3kPWLlXDPlTfdjRcbRAIkQAIkQAIkkDoErAr0lStXWm2FWMb1pIoVK2Lfvn3qqLYmTZpgxIgRKrp7dHQ0ZJGm9zx1PXWlRh5rAv3l0xVR5tBLmPGZF/yzACFj+iPm9FEK9NQYGNZBAiSQ4gQ4L+hDrAn08UUj8VfYHfz14puIPJEDS7+PRfWX3dGlo6lADx7aBbFXLsJ/8mJ4FMmYR5jqI8tcJEACJEACJODaBKwK9Lffftuk95GRkcrqff/+fbRs2RJTp07VRad3797Inz8/DAYD/vrrL2zYsEHtO7906RK6dOmCPXv26ConvWSyJtBrXaqEYvsqYfRQTxTM50aBnl4Gje0gARJwCAHOC/owagL9s2JROBB6G3+WfBOxp3Ng0XexeKWKO7p3MhXoIWMGIOb0EWQZPRueZehtpY8yc5EACZAACZCA6xGw28U9Li4OS5Yswe3bt5UlXE+SvJ9//jnk2o8++ggFChRQl23atAlXrlxBv3799BRjV541a9Zg5syZiIqKQv369TF27Fh4eJguiO7du4fJkyerFwQSCE/O9x0zZoz62VqyJtAb/lcJ+bdXwvu9PFGuNAW6XYPGzCRAAk5JwFnmBXO4x48fx7Bhw3D37l2ULFkS06ZNUwFRjZN4en311VdYvXo1YmNjVfyUiRMnIk+ePFbHShPoE4tF4Y/Q2zhQsjVwNicWfhOLl19yR8/OpvNR6P+GI/rgHvgN+QxeVWs55X3ARpMACZAACZAACSSfgN0CXauybt26Ns83T37zklbC5cuX0blzZ6xYsUIttgYPHqxc6bt162ZS4JEjRyB5W7RooV4e9OnTB9IvcwuReSssCfSZd45j4LV9aHmvEnJsqoR32nug1qvuCJv7GaJ2b0bmd9+HT1N9WwKS1mteRQIkQAJpSyA9zwvmZERsy8tbeSkrL2eXLVuG/fv3Y/78+SZZAwMDVewUmVOyZMmCOXPm4MKFC5g9e7Yugf55sWjsD72F/SXfgOf5XJi/NBZVKrmj97umAl2bK3z7jYB37SZpO5CsnQRIgARIgARIIM0IJEmgy8Kmdu3aul3T5Ti2EiVKoFChQqqjYrFevHixOmZNLOoSPM6RacGCBQgKCsKQIUNUsWfOnMHw4cOxdu1aq9WIZ4C48I8aNcpqPksCfVfwDdQ5vw6lo/Kg2oqmaN7QHS2beCDyl5UIXzYbnqUqIsuYOY7sJssiARIggXRDIL3PC+agjh07hgkTJmDVqlXqI3lJ+8orr2Dbtm3w9/dPlOvp06cxdOhQbNy4UZdAn/xCNPaG3MK+km/A5+Jz+GpxDF4q74a+3R4fxaml8KWzELlpFV/mpps7mg0hARIgARIggbQhYFWgS2A38yTHpMnCJDg4GF9//bWuVsuxarIQeumll3Dnzh11tNqAAQMgCx3Zly5uhY5M4npfuXJltG7dWhUre+fl9xMnTlitRo57EwuQ7K+3lqwJ9PKxeVB5eVNUr8A8EUgAACAASURBVOaOLh08YAgNxqP32gBhoQwU58hBZlkkQAJpQsBZ5wVzWOvWrVMWc9nmpKU2bdpg9OjRKFeuXKJsly9frgKbipu7taS5uE95IQZ7Qm5iT4lW8LucG3O/jkHFcm54r7upQI9YuQgRq5cgU5uuyNSue5qMLSslARIgARIgARJIewJWBXqtWgn3wfn5+aFMmTLKbfy5557T1YPSpUvj0KFDKor79OnTIXu/ZXHz6NEj5WIogeMcmQYNGqTOXJeI8VoSUX3+/HkVnM5S2rt3L2bMmIEff/wRnp5PF06TJk1KkH3RokXKxdE4aRb0l9zyosKyJijzohs+7PO4HG3hRSu6I0eZZZEACaQFAWedF8xZybNeXhJLfBItderUCf3790e1atUsor116xbeeecdLF26VHmAaUkCn549e9bkmosXL6J58+aY+kIsdofcwO8lWiHr1dyYsyAG5Uu7YUAvU4EeufFHhH8zBz5N2iJzlw/SYmhZJwmQAAmQAAmQQDogkCQXd3vbLYsdsbr7+vqiTp066gx0CbQj1nixbJ88edLeIq3mHzlyJMqXLw/tGLiQkBC14EqsHgkUJC6L4uJuHvhH3B3NU9++fRMV6Pnd/ZHrSHGIh+Ta1uUR4OFDK7pDR5eFkQAJuAKB1J4XzJmtX78eu3fvNvHgEu+pcePGqfnDPD18+BDvvvuu2pYlx4QaJ5lDbt68afI3KV+8x6YVj4W8wN1doiWevZYHM+fFoGwpN3zQ21SgR+38BWFffQ7v2o3h22+kKwwx+0ACJEACJEACJJAEAhYFes+ePZU1WQLiSBJLQ9OmTeN/t7ee8ePHK/dy2eOXN2/e+OA6EqRNIuhu2bLF3iKt5pf97RI5XvadS5LFk4h2sXKYJ7F6DBw4EF988QWKFi2qqx3WXNyNC2gVUAQ/F22k/mRsRc/UzjRYnbVKxerORAIkQAJpTcDZ5wVzfuKmLvOCFpskJiYGVatWxY4dOxAQEGCSXbZ0de3aFd27d1eiW0/SXNynF4/FzuAb2Fm8JXLdyIPpX8agVAk3DOpnKtCj/9qN0Kkj4VWlBvw++lxPFcxDAiRAAiRAAiTgggQsCnQRoH/++SeeffZZ1eWKFSsqcStnmSclycJHAvGIQJc9fj4+PqoYcW0X6/brr7+elGITvUYCvXXs2BE//PBDfBR3sdiL66JYTG7cuIEOHTqoc9hl3/msWbNQrFgx3W2wJNCvRAVj6b3HLo7rf43FqRdPIco7CjMKvIYPc5UzsaLrrgiAm28WeFWtAa8qNeHm9/iFifzNo/AL9hTDvCRAAiSQLALOPi+Yd17mo0aNGqmgoGIRlyju4jElHl7ymbi+S6wU2ZrVo0cP5dpuvG3KFkxNoM8sHoftwf9hR/EWyH0zL6bNjcGLxd0w+D1TgR5z8m+EjHufAUVtgeXnJEACJEACJODiBFJFoKcFQ3Gpl+A/4kYveyZlz7u3tzcWLlyIc+fOYerUqcpyLvnc3d3jmygvD8Tibi1ZEujG+YeOicYR/6vYVvs3BHh440ipdijs7a8iukcf/F03DkNoCGKvXrSY36NwMfg0aQ+vKtXh5pd4xGHdlTEjCZAACVgh4GiBnh5giweVbG+Sl7biQSXzQoECBVRgUYljIt5Yhw8fViLeeJ6QtotnmRzfmVjSBPqs4gZsC76ObcWbo8CdfJgyOwbFi7ph6PumAj32n3MIHtYd8mz3n7I0PeBhG0iABEiABEiABNKAQIoKdBHFYpmQY9asJXGBd6ZkS6BPnBGDf64Y8KDH7/g56jwqZM6OmQWrW+xiIW9/Jd4TS3F3biJq1ybEnD4SnyXmygUVFd48uefMDfeceUz+LFZ3S9Z2z9IJXefdc+SGey7T651pXNhWEiCBlCPgKIHuqvOCOXlNoM8pYcDWoOv47YXmKHwvHybNikGx590w7ANTgR53+waCBrRTz+CsXzw++o2JBEiABEiABEgg4xFIVKCL27e2B11cw8eMGYMcOXKYEKpZs6ZVYnPmzMHLL7+M7du3W82n7RV3Fvy2BPqXi2Pw9zEDOnSOQXfv1bgaFZLsrtX2z2tSRlzgfRgCHyDrgwcoeycQZW8/QLbIqPg8BR6FoeCj5NeriX4R+SL2RdhTyCd7OFkACTgdAXnucV7QP2yaQP+iBLAl6Bq2vtAcRR/mw8TpMXi+kBtGDDIV6IaQIDzq1kR5RGVbsll/RcxJAiRAAiRAAiTgUgQsCnRLx+hY6rXs586IyZZA/35NLHb8Hoe2LT3gU+UWxtw4mCimK1FBDhHw5hUUcvPBIZ8yyBYagVixuJslY4u89lFilvnEGi+umG6+/o9Fe848dLfPiF8G9jnDEOC8YN9QawJ9bgng16Br+PWFZigRmB8TpsWgcEE3fDLYVKBL6YHtHntaBazca19lzE0CJEACJEACJOAyBFL0mDUJDqcnGZ87rid/WuexJdA3b4vDmg2xqpkVyrqhaiV3ZPNPeP66HLdetIjlc9nN+yjH9FhKgbGROBp2Tx3joyVN9H+apzLG5K2SLFziYh939yZiTh2BISxEiX31t3u3E5Qrwet8mrZT5/hyX3yysPNiEnBZAq46L5gPmCbQvyrphk2P/sXmF5qiVHABjJsSg4L53DB6qAWB3rkBEBGGgGVbgcy+LnsPsGMkQAIkQAIkQAKJE0hRgS5CVk+6cCGhhVfPdWmVx5ZAv3zVgO9WxeLqNYPNJk4d54WAbDaz2ZVBxHqd8+tUgLrLZTups9hTIsWc+hsqkN2VC2qPfMzpo6oaCvWUoM0yScA1CLjqvJCYQJ9X0h2/PLqKX4o1QbnQghgzOQb587phzMcJBfqjXi3U1qVsCzfALdszrjHg7AUJkAAJkAAJkIBdBFJUoL/22mvw9/dH8+bNUbduXXVcjaVUqFAhuxqd1pltCXStfXfuAn8ejsPZi3EwxJm2+u59Ax4GAh3e9EDdmk+jyDuqb7XPrcPukBtwhBVdb5tEsEesWmwi1L1ry57Kx8fD0Q1eL0nmIwHXJeCq80JiAn1BSXdseHQVE/O9jBJRubFoeSzKeGTH5KEJLeRB/dsqD6Wsc1dD4n8wkQAJkAAJkAAJZDwCKSrQY2Nj1bnjcga6nHnesGFDtG3bVp2r7sxJr0C31sfDxwz4arHlaL6OYJNaVnRLbTUX6sZ5tHPdRbhriUHnHDHiLIMEnIOAq84LiQn0hSU9sP7RFZOPO//ZHMv65U8wYEGDOiHu+hVknbEc7vmc68W1c9x9bCUJkAAJkAAJpH8CCQS6iOkmTZrAz8/Poa2/d+8efv75Z6xevRpubm5KqL/xxht49tlnHVpPahTmCIEeFQ18MDwa0dHAtPFeyJbV8S1vdWkz1gVeUce4FfZJ/Cg3cYFfUriOw13hRajL3nUtGbvBm/fWs1RFiGjnue6Ovw9YIgkklwDnBfsJanvQD1TMib0ht1QBx8LuIzAuEh3+bIrv+xVMUKicgy7noftPWWLxeEz7W8ErSIAESIAESIAEnI1AAoEu1u19+/bB19cXb731FlasWOHwPh0+fFhZ1X/99VeIu+PcuXMdXkdKFugIgS7tEwu6WNJTys39SlQwipz4ThcKOat9Z4mWDhfp5pWL+2bkppUmkeWNo8drFnavKjXhVaWGrrYzEwmQQMoS4LxgP19NoDdr1iz+4oanN2Fr+FW0+ashVvV9PqFAH90PsWePw3/CPHgUL2N/pbyCBEiABEiABEjA6QkkEOg1atTAjBkzULlyZVSpUgUHDyZ+RFhSeh8eHo7NmzcrS/rx48fRoEEDTJ8+PSlFpdk1jhLoB/+Ow/xlsXjheTd8/EHCgEGO6ODR8HsIjHl6PrqlMj+8thfHwu8jtUS6eRsMocGIPrgHUbs2xe9f1/Jo57Brv8t+dt9+Ixgl3hE3B8sgAZ0EOC/oBGWUzZJAb3luC9aH/IOWB+thbZ+EQVRDJgxEzPGDyDJ6FjzLvGR/pbyCBEiABEiABEjA6QkkEOhr1qzB6NGj4ePjg+DgYAQEBCTaSXvE+9GjR5XV/JdffkGRIkXQpk0btGjRQgWRc7bkKIEubu79hkSr7qeUm7setnJUW4XTK9V57K0CiuDnoo30XJYiecTCLkJdBHvs1YsW65Dz17N8OociPUVGgIWSQEICnBfsvyssCfT257djZfB5NDlUB7/0Lpmg0NDJHyP68D5kGfY/eFZ6xf5KeQUJkAAJkAAJkIDTE7AYJC4oKAjXrl3DgAEDrFq3K1SoYBXA/fv3sXbtWmUtl59btmyp9p4XL17cqcE5SqALhLlfx+DIiZRzc9cLWiztEvn9UWwUPshVFjMLVNd7aYrm085h1yoJXzpbCXeK9BTFzsJJIAEBzgv23RSWBHqXi7uw7NEZ1D9cE1t7lU4o0GeMRvQfO+A3aAK8qtW2r0LmJgESIAESIAEScAkCVqO4b9q0SQWMS2p68cUXUbBgQVVGrVq14OHhYbGosmXLJrWKNLnOkQL9wKE4fP1tyrq564UkIr3i6VUqu1jRxZqe3pK4w4eMGaBEuri/S2A571qN4Z4rT3prKttDAi5JgPOCvmG1JND7XNqD+YEnUfvIq9jZo3yCgsLmfoao3Zvh238UvGs21FcRc5EACZAACZAACbgUAV3HrJ09exYXLlyAwWBAsWLFUKpUKV0QRJTrSXIUmzMlRwr0iEig/9Bo+PkCo4Z4IUf2tCUx885xDLy2DwEe3jhSqp2KAJ/ekrFI19omUeC1JMHlfJq2S2/NZntIwKUIcF6wPpyWBPqHV/7ArPtHUf1oNezpnvC40bCFUxH121r49v4Y3nWbu9T9ws6QAAmQAAmQAAnoI2BVoD98+BCDBw+GRF0vVKiQOh7typUrKF++PGbOnOmUR6Tpw2I9lyMFutS0bEUs9vwRh/p13NG+lWUvA0e0W28Z2vFsEjTuw+fKo2VA4RSP7q63bcb55Bi3qF2blcXJPPGYoqQQ5TUkYJsA5wXbjCSHJYE+4tpf+PzOYbx8vDIOdK2SoKDwZbMR+ctKZO76IXwat9FXEXORAAmQAAmQAAm4FAGrAn3gwIFKlI8bNw5ZsmRRHQ8JCcGoUaMQFxeHWbNmuRQMvZ1xtEC/dQf45LNo+PgAMyZ4wdtbb0tSJp9x0DitBnF3r+2fF7X886JC5hwpU3ESSzXepy7B5SI3rVLu7yLS3fzSnwdAErvJy0ggXRDgvKBvGCwJ9Im3/sbI//5EpZMVcPjdhEHgIn6Yj4ifv0Xmt/vCp+Xb+ipiLhIgARIgARIgAZciYFWgSxC4LVu24LnnnjPp9O3bt9GoUSMcOXLEpWDo7YyjBbrUO3NeDE6eSftgcRoDEelrAy+rf+sCrySKRkT7ksKvpytX+OCPuqg96j5N2iJzlw/0DivzkQAJ6CDAeUEHpEQs6NNvH8Pg6/tR9lRZHO+cMBBnxOqliFj5NTK17ab+MZEACZAACZAACWQ8AlYFerly5bBz505kz266Mfru3bvq/HIKdMfdMKfPGTD9yxi1B33SaC/HFeyAkjSxviv4BnYF/6eOYzNPXbKXQGGfrCZ/ln3sFXytW9trZcnrgBaaFhF75QKCh3ZVf/QbMhFeVWs6vA4WSAIZlQDnBX0jb8mC/uXdk3jv3z0odeZFnOqUMEp75PrvEf7dl/Bp1QmZO/bRVxFzkQAJkAAJkAAJuBQBqwK9b9++SpyLS7uciy4pIiICY8aMQXh4OF3cHXwrfDopBv/dNKD9Gx4omM9NV+le3sDzhfTl1VWgHZlEuI+5cRCz7pyw46qEWSUQnbjQf/BcOYdZ4iNWLkLE6iWqMp8m7ZCpbVe6uydrlHgxCTwmwHlB351gSaAvvncW3a/uRIkLJXD2rdcTFBT56xqEL55B7x99iJmLBEiABEiABFySgFWBfuvWLfTr1w///vsvnn/+eRXF/dKlS+rnBQsWMEicg2+J/X/FYfHyWLtL/aC3J8qWShuRLo29EhWMpffOJmi3/P1KZLDV/uwOuWHyuVjixWXeEclYpMuedPecT49ic/PLAo/CL1itRj6XfO45cvMYN0cMCMtwCQKcF/QNoyWB/v2DC3j78jYU+6cYLrStn6CgqB0bETZvErzrtYBvr6H6KmIuEiABEiABEiABlyJg85g1EeUHDx5UwjwmJgYlSpRA5cqV4e7u7lIg7OlMSuxB1+oXN/eYGH2tkXz/XDUgix8wYaSX+t8Zk5y/PvP2cbXf/VFsFBwp0sXdPXzpLMScPposNHJ0m5y5Lv8zkUBGJ8B5wfYdYEmg/xT4D968tAWFrxbGueaN4W22myl6728InT0W3jUbwbf/J7YrYQ4SIAESIAESIAGXI2BToLtcjx3QoZQU6PY2b86CGBw7ZUCpEm4Y1M/T3svTVX4R6rXPrYsX6V1ylEy0ffbuXZcj2YyTITQEIt6tJfncEBZiUdxr5657lq6orOziRs9EAiRAAhoBSwJ906OraHpxEwpcL4ALjZqpkzuMU/RfvyN06gh4VasDv0HjCZMESIAESIAESCADEqBAT8KgpyeBHhoGjJoYjaBgoFVTD7xQ5LGre/bsbsjxbBI6l8aXGIt0W02RIHRj8lbBB7nK2cqarM8NocGPz1vftUlFh7eUPAoXg2+/kTbd5pPVEF5MAiTgNAQsCfQdwf+h7vn1yHszDy7UbQXfzKbdiTl6ACETh8Cr0qvwGzbFafrKhpIACZAACZAACTiOAAV6ElimJ4EuzT911oAZXyX0iy9UwA2VK7ibBJF7LpcbArIlodOpeImI9A//3ZdojRKc7lj4/fjPJcicsbW9ZUDhFD2rXQS7sq4/scKLcI+7dxtuvlmQqV03WtNT8V5hVSSQXglYEuh/hN7Cq2d/xnO3n8PFWq0TbEuKOX0EIWMGwLNsZWQZNTO9do3tIgESIAESIAESSEECFOhJgJveBLp0YcOvcThzPk71Ji4OuHjZYLFnL7/kjp6dPZLQ6/R3iRz71uXK9gTHvollfUaB19Ale+Iu8o7sjQj28KWzEbV7sypW3N8larxn6UqOrIZlkQAJOBEBSwL9SNg9VDqzCjnu58ClV9oiq79ph2IvnkbwiF7wKFEW/uO/cqLesqkkQAIkQAIkQAKOImBToEdGRuLo0aOQyL0tW7ZU9UZFRan/vb29HdUOpyonPQp0c4DhEcDRE3H4+1gcxA1e0vlLBnh6ArMmeiXY++hUA2DW2KX3z8ZHixfr+7rAKyrHksJ1Uk2kS32yf1QC0ok1XZK4vbv5mq3AAbjnyo1MbboxMrwz33QZvO2cF2zfAJYE+pmIhyh1agWeeRiAf6p0SODNFPvvJQQPeRceRYrDf/Ji25UwBwmQAAmQAAmQgMsRsCrQL168iB49eiAsLAxBQUE4e/bxUVorVqzAnj17MHfuXJcDoqdDziDQLfXjs2kxuPyvAe+090CtV103Cr+czT725qE0EelSqTrebdNKICzU6u3kXbuxOvpNO85NifpCxXheu54vIfOkGQHOC/rQWxLol6OC8PyJ5cga7I9/yndC9mdMy4q7dR1B778F93yFkHXGcn0VMRcJkAAJkAAJkIBLEbAq0Dt16oRatWqhZ8+eKF26NE6dOqU6L+eit23bFn/++adLwdDbGWcV6Dv3xmH5qlg8X9gNIwY6d8R3W2MlVvWuV3ammUjX9qlbaqcKOPfEHd5aP8QCLwI+U9tuDD5na8D5eaoR4LygD7UlgX4zOgx5jy+Db5gvrpZ6Fzmym5ZleHAXj/q8obxrsn6xSl9FzEUCJEACJEACJOBSBKwK9HLlyuHAgQPw9fU1EegPHjxA9erVcfr0aZeCobczzirQw8KB94dFq25OGu2VYHGot//Oks9YpB8p1TZFA8fZy0SLDB8fcC4sRBURI0e/WbC8i7VdzmG3liRInVjjmUggJQlwXtBH15JAfxgbiWePLoZPhA+uFu+G53KaCfTgR3jUvSncAp5FtgXr9VXEXCRAAiRAAiRAAi5FwKpAr1mzJubNm4dSpUqZCPS1a9eqv//6668uBUNvZ5xVoEv/5i2NxaEjcWhS3x2tm7lGsDhr49blyg4su38OEjiugm8Oq0NcIXMOFVwuvSSJFC/72iNWL9HdJPecueFVpSa8qtZQweqYSMDRBDgv6CNqSaCHx8XA98hCeMZ44t/CPZHnObOyIiMQ+E49wNcPAUu36KuIuUiABEiABEiABFyKgFWB/v3332Px4sUYMGAAhg8fji+//BKHDh3CsmXLMGHChPigcS5FREdnnFmgnzhtwKz5MciWFZg23ktHb50/S6tLm+MDx9nqTZfsJbCk8Ou2sqXq53F3bqrgc4YnVvbEKpd8WoA6ySMWdRHqItjd/LJYbbN7jtwMWpeqo+q8lXFe0Dd2lgS6+l4efhyd/XrePsiXxy1BYYHtqqu/Bazcq68i5iIBEiABEiABEnApAjajuO/evVuJdAkMFBsbi2LFiqF3796oUaOGS4GwpzPOLNCln4M+iUZQMFDrNXd1zI+nhxtqV3eHn689FJwnr5ybfjTs6bnpllouecTa/ig2CiLSxZIe4OHjPJ180lKxusu57GJ5NxbrejoiFndxo5e973SV10Ms4+bhvGB77G0J9H9z90GBfBTotkkyBwmQAAmQAAlkLAI2BXrGwqGvt84u0Fevj8Wv2x+fma4l/yxAhzc9ULWS60Z3tzW6ckRb7XPrlEi3lGr757VVhMnnhb39Uds/H8r7Zk+T/e8i1mNOHUH0wd9ttjuxve+WLjQ/Ps6zdMX4SPS0xNtEzQwZhEBiAj3zn4sQ4RmFU7m6o1SBhEeVBr3fHnG3/kPW6d/BPX/hDEKL3SQBEiABEiABEtAIWBXoVatWxbp165AnTx6XJbZmzRrMnDlTne1ev359jB07Fh4e1vdmO7tAv/cA2PdnbPyY/nvdgGMnDer3gvndkMmC4Vj+3qqph8XPXOnmsCXSHd3XVgFF1HntaW2tl2B10Qf3KOu7ITQEsVcvOqyrls6DNz5aTiqSaPVyPrxxoth32BA4tKCMMC+YAzt+/DiGDRuGu3fvomTJkpg2bRpy5cpllWtiAj3rgaUI9grHfv938UrxhG5LodM/QfSBXfB9fzS8qzdw6NixMBIgARIgARIggfRPwKpAr127NmbPng2J2uuK6fLly+jcubM6110WW4MHD0aFChXQrVs3q911doFuqXNHjhuwbEUMQqwc3f1MNuDdDp4o82JCt0xXvD/M+7Qr+IZd3RSxvyv4PxwNu4erUY+jtFtKEsBuZoHqKOzjrz4u5O0Psb6n1ySWeRH0kpSYF0v96SPqd3ss8Xr6J0HvxEIvAl6SJSFvqRwGyNNDN2l5XH1eMKciW7vk5e2YMWMgAfIkBsv+/fsxf/58qwATE+jP/fUt7niEYP7tjujVJFuCMiJ++gYRKxbAp9lbyNy5f9IGiVeRAAmQAAmQAAk4LQGrAn3Hjh1qETJ58mQULux6rnYLFixAUFAQhgwZogbwzJkzKhieRKm3llxRoEt/5Ri2a9cfW9KNU1CwAWs3xeL23cd/fb6QGzyNjlHPlAnwzewGX1/ALzPg6+sG3yf/i6gvXDBjCnpbT4UrUcHocnkHdofYJ/ylXBHwmqC3VI9Y5M2j1tvroq+VWz5z9mRZ+I0FvVZm7JWL8SJf/hZ39xbi7t406YqjxL4lC761sTG37tsax8Q+lxcLyU3p0YvA1ecF8zE7duyYCoq6atXjc8nj4uLwyiuvYNu2bfD3T/xFWmIC/fm/f8BlQyA++rs9pvR8NsEtEnPkAEI+HwLPMpWQZfTs5N5CvJ4ESIAESIAESMDJCFgV6P369VOi9fr168idOzcyZ85s0r2tW7c6WXdNmztixAhUrlwZrVu3Vh9ERkaq30+cOBGfMTQ0oUlZrOwXLlxw6r4npfG/7YzDhi2xSsjbk3y8geLF3FCogBvczLR6QDY31Ho14+57F45rAy9j5u3j8UivRAVZtbjbwz4t8+o52i6x9smRdwGePjAEPlDC3RD1OC5AgYeP0PHUFZvdijl91GYeV87gaA8C2X6geTF8+N0anL15G/89fITcObIjs39Wl5oXzO8L2eYlFnN5Ua2lNm3aYPTo0fHeZdHR0SqIqnESl/h69eqhWbNmJn8vf2oljkfcR+kLL6JMnsdz6pSK5VEwayb1syHwPh71apmyt6fXk73vJs/jJ79oD2mTh7X2mVGznnzuBrPrJEt8uUYVWCz3SXlW6zQuQ6vfUp2P/2baJQv54ttrVrfx1cZ9N5+0LH5moY3mfFTjLHC0yE8rL3HuJj1NUK517k+Hx0K+FB9PvfeQhRf7Ce6TxLk/rkXHvWlhPOPvaeMbKj6fJbbGX1dr3yML95yOck3bY+me1vM9Ssjd8j2kh7tcaXZvWnxePG1rpnbdU/aZxtJJwMUI2LSgW+vv66+nr+Oo7B2bQYMGqQVUkyZN4i8V6/j58+fh9uRh06pVqwTFnjp1KkMKdA1EaBgQHg6EhhkQHiH/A2FhBiXcw8MNj39/8vmt2wbInvfEUpGCbhg52Mgcb+8gZtD8Yn2/EvnYzdxSehy5/l78R3oi2SdWlrjqJxY4L7Xx18qSF7tK2CdeYk79bVczza37dl1slFlz+0/q9XKd+dF5ySnLUdfuCYyIL8qrRgN4v1bPpGhnnxfMOf344484ffq0ik+ipU6dOqF///6oVq2a+tOUKVOwZ88ek0tz5sypXv6aC/RqZ9fgz9A7JnmPFOyECjmfWuMfdWsCQ0iQo4aM5ZAACZBAmhLgsZFpip+VOyGBDB3FfeTIkShfvjzatWunhi4kJEQtuE6ePGl1KF3VxT2l7t/7D4HTZ+PwIDCh+/yzAW6o8UrGtqCnFPe0Lje5LwUCYyITdEHc+rtkL5nWXUv39dv7UsJWh9QWhDumWxDkGs8yL8GzVAVblzv15+vXr4ccKyeB4bTU4+1+6AAAIABJREFUsmVLjBs3Ts0fiaXEXNwPh93FsdshuBYYhcDoKDyKjsKUSuWQI7OXYzk98ToBjJ67hic/a/+bfPak+vjP5Eqz/CaPcPOyxPyf8Bkf/zeLdWplGHfdvM6nZcb/ZFyPrr5YY2BUdwI+8pmFNj7JF89HZTPPZ6tOs/wm7Cyx1dqZeLmmw2OhjOSOp93cLd1DVu4RY45WuFu+p/XeQ4mP59OxNmZsm7vJF9fqPZSw3ATfMRMGdt6bNu8hM/YWxtP0njZ/Jli696xw1/ri5oZMba3HdnLsw4+lkYDzE7Ap0MXdWyzK4v5tnjp27OjUBOR899u3b6t955IkUq+I9g0bNljtFwW6Uw87G08CJJBMAq48L5ijEY8pmRe02CQxMTGQSPayFz8gICBRkokJ9GSi5+UkQAIkQAIkQAIuTsCqQJ87dy4WLlyorAQSKKdMmTK4evWqsjSLOP/oo4+cGo/srZd+/PDDD/FR3IsXL65cF60lCnSnHnY2ngRIIBkEXH1eMEcjQeEaNWqEUaNGoUaNGiqKuwSI+/bbb61SpEBPxk3GS0mABEiABEggAxOwKtBfffVViJVZzn1t3ry5sizLYmXSpEl45pln0LdvX6dHt3HjRhX8JyIiArVq1cLEiRPh7f0kgE4ivaNAd/phZwdIgASSSCAjzAvmaM6ePYuhQ4fixo0bKFq0KKZOnYoCBQpQoCfxHuJlJEACJEACJEACiROwKtDLli2Lw4cPK8EqgW5EzEp69OgRGjZsiAMHDmRIthToGXLY2WkSIAEAnBf03Qa0oOvjxFwkQAIkQAIkQAKmBKwK9BYtWuDzzz9H6dKl8e677yoLgvx89+5d1K9fH0ePZsyjjCjQ+TUiARLIqAQ4L+gbeQp0fZyYiwRIgARIgARIwA6BLtFr8+TJgypVqmDTpk3qmBlxA5f96C+++CJmzpyZIXlSoGfIYWenSYAEAHBe0HcbUKDr48RcJEACJEACJEACdgh0c1jbt29Xbu358+fHW2+9BR8fnwzJkwI9Qw47O00CJGCBAOcFy7cFBTq/LiRAAiRAAiRAAkkhYPOYtaQU6urXUKC7+gizfyRAAiSQPAIU6Mnjx6tJgARIgARIIKMSsCrQw8PD8c033+DkyZMIDQ1NwEgivGfERIGeEUedfSYBEhACnBf03QcU6Po4MRcJkAAJkAAJkIApAasCfciQITh16hRatmwJPz+/BOzeeeedDMmTAj1DDjs7TQIkAIDzgr7bgAJdHyfmIgESIAESIAESsEOgV65cWZ19LoHimJ4SEIHORAIkQAIZkYDBYFDddnNzUy9v5UxwpoQERKD/8ssvREMCJEACGZ7AhQsXMjwDAiABewhYtaBXrFgR+/btg6+vrz1lunzeb7/9FrJI7dy5s8v3lR10LAE5qlACLFaqVMmxBbM0lyfQsGFDdZqGh4dHmvaV84I+/NeuXcPo0aOxZMkSfRcwV4oQ2Lx5M06fPo3BgwenSPksVB+B6dOno2TJkmjSpIm+C5grRQh069YNY8aMQcGCBVOkfBZKAiTgGAJWBfqwYcNQrlw5dOzY0TG1uUgpFOguMpBp0A0K9DSA7iJVpheBznlB3w1Fga6PU0rnokBPacL6yqdA18cppXNRoKc0YZZPAo4hkECgjxo1Kr7k2NhYrFu3Tp15XqRIEWTKlMmk1vHjxzumFU5WCgW6kw1YOmouBXo6Ggwna0paCnTOC/bfLBTo9jNLiSso0FOCqv1lUqDbzywlrqBATwmqLJMEHE8ggUD//PPPddcyfPhw3XldKSMFuiuNZur2hQI9dXm7Um1pKdA5L9h/J1Gg288sJa6gQE8JqvaXSYFuP7OUuIICPSWoskwScDwBnoOeBKYU6EmAxksUAQp03ghJJZCWAj2pbc7I11Ggp4/Rp0BPH+NAgZ4+xoECPX2MA1tBArYIWBTo9+7dQ0BAADw9PeOvj4uLg0x0N2/eRPXq1VWwDyYSIAESIIGMQYDzQsYYZ/aSBEiABEiABEggbQlYFOjvvfceJFJvjx494lsnexB37NiBEiVK4PDhw5g3bx5eeeWVtG09aycBEiABEkgVApwXUgUzKyEBEiABEiABEsjgBCwK9FdffVUJcIngLuny5cvo0KEDtmzZgmzZsmHFihXqfPTly5dncHzsPgmQAAlkDAKcFzLGOLOXJEACJEACJEACaUvAokAvXbo0fvvtN+TNm1e1buLEiciSJQvef/999bu4uTdr1kxZ0plIgARIgARcnwDnBdcfY/aQBEiABEiABEgg7QlYFOh169bFp59+ipo1ayIwMBANGjRQx63lyZMnXqDXr18fJ0+eTPsesAUkQAIkQAIpToDzQoojZgUkQAIkQAIkQAIkAIsCfcGCBVi8eDEkavCBAwdUUDjjc3APHjyoolHv3LkzQyGUQHmfffYZNm7cCC8vL/Tt2xdvv/12hmLAzuon0LlzZxw5cgRubm7qok6dOqnvjaQ1a9Zg5syZiIqKgrzsGjt2LDw8PPQXzpwuR+DKlSvo3bs33nrrLXTt2jW+f8ePH8ewYcNw9+5dFZxz2rRpyJUrl/rc2meOBsR5QT/R1BwX/a1yzZwGgwFz587FkiVLEnj1Jfac5Vzu2HtBjDVTpkzBuXPn4Ovri+7du6v5TpI11g8ePMBHH32knmPPPvus8tZ86aWXHNu4DFTa3r17MXv2bFy9ehWZM2dGx44d0atXL0XAGms+rzLQTcKuOg2BRI9ZW716NY4dOwZxa2zbtq2JeJBJ78aNGxgwYIDTdNQRDV21apXaey8L1bCwMLWQlqNDypQp44jiWYaLEWjatCnkSD5ZeBgniekg4l1iOYjQGjx4MCpUqAA5/oQpYxKQF6HykuaFF15QATo1gR4bG6te4IwZM0Z5NC1btgz79+/H/PnzYe2zlKLIecE22bQYF9utcs0c0dHRGDhwoHqOytwsxgMtWXvOci537P0ga8IiRYqgUqVKuHPnDlq3bq1emMjzzBrrIUOGIF++fPjggw+USJf/JdZRpkyZHNvADFKaeLqWKlVKcX/48CHatGmjXujK+iIx1mJsSmyOySDY2E0SSJcEeA66HcMib4W7dOmCGjVqqKuWLl2q9uMPHz7cjlKYNaMQkPvk999/j7ega/2WFzxBQUFqwpR05swZdQ+tXbs2o6BhP80IXLhwAf7+/uqljQTi1AS6vCSdMGGCWuRKEmuUnJ6xbds2/PPPP4l+JmUxpQ0Ba2PGcXH8mMgzVrz8xPIqHkt6nrOcyx0/DsYl9unTR4l02R6ZGOuPP/4YlStXxr59+5S1V5J4JYpB6PXXX0/ZBmaQ0sWI1qhRIzRu3DhR1tmzZ+c8kkHuB3bTuQhQoNsxXrIH85tvvlFvfCXJwkB+//rrr+0ohVkzCgGxhObOnVt5W4gniojwAgUKYMSIEWqylAWMpMjISPX7iRMnMgoa9jMRAuKR88wzz8QLdLGIiMV88uTJ8VeIVWT06NHqdI3EPtNO4CDo1Cdgbcw4LikzHjExMahSpYqJQLf2nOVcnjLjIKVq27Z++OEHFWg4Mdby4lG8EHft2hXfmP/9738ICAhAz549U66BGaBkeZErLz7E80pe7sqYJMZavE84j2SAm4JddDoCFOh2DNlrr72G9evXQ944Svrrr7/UPuLvv//ejlKYNaMQCAkJgZ+fH2TxKK7uP/30k4pfMGjQINSrVw9NmjSJRyEuaefPn09gbc8orNjPxwTMBfqPP/6I06dPK/d3Lcnezv79+6t9hol9Vq1aNSJNIwLWxozjkjKDYkmgW3vOisWdc3nKjMWMGTMQGhqKTz75RFWQ2LpJ9puLpf3XX3+Nb8icOXOUl5C4ujMljYCIctly4OnpqQR6y5YtIfFNEmMtRgTOI0ljzatIICUJUKDbQVdE1aJFi1CoUCF11fbt25U4l78xkYAtAnKOtIh0WYSUL18e7dq1U5eIkJeFO09FsEXQ9T83F+giInbv3q32EWpJFlzjxo1TAj2xz+T+YkobAtbGjOOSMmNiSaCPHDky0ecs5/KUGQdZD23dulXF6fH29laVJMZaBPqbb74JCWymJflbjhw54gObpUwrM0ap//77rwpKK+sMeUmSGGsR6JxHMsY9wV46FwEKdDvGSyIst2/fPn5/1MKFC3H79u34N8V2FMWsGZDAyy+/rBYv8nZb7hstdoEEx5HFpAQ5YsrYBMwF+qlTp9S9ocUnECFStWpV7NixA//991+in4mbKFPaELA2ZhyXlBkTSwJdTqJJ7DnLudzx4/Dzzz9j5cqVasufeI5pKTHW8lyTbQnyLMuaNavK3qNHD7XGkqBlTMknIN48EhNDTh9KjLVsQ0hsjuHzKvljwBJIIKkEKNDtICd7C0VcaVHc5c3k559/rh58TCRgTEAWhhLNtmzZspBjgGTRIm+pv/vuO1y/fl0dfyJ79LQo7sWLF1duy0wZm4C5QBd3TwnyI8dcStBBieIuAeJky4S1zzI2xbTtPccl9flbEujWnrOcyx07Rps3b1bxeMRokSVLFpPCrbGWOAFiMf/www9VFHdxw5bnm3kZjm2t65Ym2y4lWKIc2SpR3CVIXIsWLZQVPTHWcixeYnOM65Jiz0gg/ROgQLdzjOSsTxHpcra1RCdlMBM7AWaQ7GLdlH10165dg4+Pjzo6S95Sa+dXy150CfwVERGBWrVqqfNfNZfADIKI3bRAwFygS5azZ88qV0U52rJo0aKYOnWqCjZo6zMCTjsC1sYs7VrlujVbEujSW2vPWc7ljrsfZPvWvXv3TGKoyAtFLYBuYqzlNBN5th0+fFhZ0WXPtHZKjuNal3FKkpNhJOCbCHQ5qu6NN95QkfFlvWqNNZ9XGeceYU+dhwAFuvOMFVtKAiRAAiRAAiRAAiRAAiRAAiTgwgQo0F14cNk1EiABEiABEiABEiABEiABEiAB5yFAge48Y8WWkgAJkAAJkAAJkAAJkAAJkAAJuDABCnQXHlx2jQRIgARIgARIgARIgARIgARIwHkIUKA7z1ixpSRAAiRAAiRAAiRAAiRAAiRAAi5MgALdhQeXXSMBEiABEiABEiABEiABEiABEnAeAhTozjNWbCkJkAAJkAAJkAAJkAAJkAAJkIALE6BAd+HBZddIgARIgARIgARIgARIgARIgASchwAFuvOMFVtKAiRAAiRAAiRAAiRAAiRAAiTgwgQo0F14cNk1EiABEiABEiABEiABEiABEiAB5yFAge48Y8WWkgAJkAAJkAAJkAAJkAAJkAAJuDABCnQXHlx2jQRIgARIgARIgARIgARIgARIwHkIUKA7z1ixpSRAAiRAAiRAAiRAAiRAAiRAAi5MgALdhQeXXSMBEiABEiABEiABEiABEiABEnAeAhTozjNWbCkJkAAJkAAJkAAJkAAJkAAJkIALE6BAd+HBZddIgARIgARIgARIgARIgARIgASchwAFuvOMFVtKAiRAAiRAAiRAAiRAAiRAAiTgwgQo0F14cNk1EiABEiABEiABEiABEiABEiAB5yFAge48Y5XhWrpjxw5MmjQJW7duTfO+P3jwAB999BEOHTqE/PnzY/369fDw8EjzdrliA1q1aoUePXqgWbNmrtg99okESMDBBNLTM+Onn37CjBkzEBoaiuHDh6Nt27YO7i2LEwLpaX3AESEBEiABRxOgQHc0URcq7/r166hTpw7ef/99DBgwwKRn33//PX7//XfMmzcvxXqcnibg//3vf7hw4QJmz56tFl7Zs2c36feaNWswbNiwBCxksVa2bNkUYyQF37hxA59//jnmzJkTX4/8LO201CZHNEa7N8zL+vjjj5W4Tk5y9GL7559/RkhICN555534ZnXu3Bnvvvsu6tatm5ym8loSIAEAtWrVQoECBfDdd9+Z8Lh06RLatGmDI0eOpCgnRz8zktrYoKAgvPLKK1i2bBlKlSoFg8EAPz+/+OJS8rmpp80yH3Tr1g3FixdX2ffv34/p06dj9erVei5PUh65N2SOMk61a9fGwoULk1SedpGj1wdpMY8mCwAvJgEScGkCFOguPbzJ65wsJpo2baoWGevWrUORIkXiC0wtgT5lyhT8+uuvyeuIA67u3bu3Wnh16dLFYmki0L/99lssXrzY5POsWbPC09PTAS1IvAgZC1loffHFF/GZ/vrrL0RGRqJGjRopUre20NyzZw+8vb3j6/D19UWmTJmSVaejF9sffPABKleubCLQZUFatWpVFCxYMFlt5cUkQAKPBXpwcDBGjRqFN954Ix5Jagr0Xr16oUmTJmk6HKdOnVLPmb///ttiO1LyuWmr41FRUeqF5KJFi+IF+q1bt5QlumPHjrYuT/Lncm/Ii9tq1arFlyFzRpYsWZJcplzoaIGeFvNosgDwYhIgAZcmQIHu0sObvM7JYkIm7hYtWuDYsWNKgGrJXKDLJDxx4kS89tpr8XnefvtttGzZEu3a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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.convergence_plot(\n", - " problems=problems,\n", - " results=results,\n", - " n_cols=2,\n", - " problem_subset=[\"rosenbrock_good_start\", \"box_3d\"],\n", - ")\n", - "\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "11d035a2", - "metadata": {}, - "source": [ - "The further to the left and the lower the curve of an algorithm, the better that algorithm performed.\n", - "\n", - "Often we are more interested in how close each algorithm got to the true solution in parameter space, not in criterion space as above. For this. we simply set the **`distance_measure`** to `parameter_space`. " - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "db2c868c", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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CZCAQxOgQHdo96ZucPIw8corr6iHjMDAQBQtWjSmw/QS6LNmzcKePXtSNxAbtB44cKB68PL390+wNxHoq1atwtKlS2P9PVu2bHB3d7eBBYl3Ib6QB62F/9fenYdaN71xAF+UMTJkVsgQIvOU6Q+ZC3kV74t/JDKVMX+Y51IUZYiIlEz/KFNCCJki85SMyRxSZvr1Wb/Wad1t37v3Oec9l/t6Vum87tl77bW+a+31PN9nOtdcM7johRdeSL/++mvabbfdJvLsomg+9dRTackllxw8Y9lll01LL730WM9c2Mr2ySefnLbbbrspBJ1CusMOO6R11llnrLHGzYFAIPB/gv7jjz+mc889Nx188MEDSGaToB977LFp//33/0eX480338znzMsvv9w6jkmem10T/+2337JB8uabbx4Q9C+++CJ7og8//PCu20f+3t5guN1pp50GfZAZyy233Mh9unFhE/R/Qo6OBUDcHAgEAos0AkHQF+nlHW9ylAmC+8ADD0yvvvpqJqClNQk6IXzZZZelXXbZZXDNEUcckQ466KB06KGHZmHqnu233z7dc889WZlDkM4444wcxv7OO++kP//8Mx111FH5vyKAr7766qx03XrrrfmenXfeOV166aVp1VVXHTznzjvvzJ58YehbbLFFuvDCC9MGG2yQv0f2Lrjggjz2hx9+OCsKtSe1dEKh4oV+66230gorrJDHLHLgjz/+SCeeeGJ65plnMtFeaqml8nibnlcE/Y477mj1RPju7rvvTnfddddgzM8//3w6/fTT09NPPz0YJ68ujzvcF1tssQS/2hv9+eefp4suuiiT8cUXXzzxQiDg5vv7779nT816662X8TWXn376KV188cVKeq7CAAAOxElEQVS5f4qYf3teuff8889PK664Yv7e9Yj1Z599lpVL86ZQeV4b4S6K5htvvJExqZvxWKsrrrhi8GfXwwyhh6O98txzzyUeJ54m/7/++usPsCgh7n2ws+7T9XfOOeckfSyxxBJ5nPPmzcthp00jwHTrD6uyj2Zany+//DLB07oyaG288cYZ0zKn8d7EuDsQ+Hcj4PxHkEUYOWfLudIk6GeeeWZaY4010mmnnTaYkHs+/vjjdOWVVw7etWOOOSaf2byazgueX2cFcikyiLee8Xbttdce3HPAAQekxx57LMsqEU6ivurw8pdeeimfZ++/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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.convergence_plot(\n", - " problems=problems,\n", - " results=results,\n", - " n_cols=2,\n", - " problem_subset=[\"rosenbrock_good_start\", \"box_3d\"],\n", - " distance_measure=\"parameter_distance\",\n", - " stopping_criterion=\"x\",\n", - ")\n", - "\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "a4aa5184", - "metadata": {}, - "source": [ - "## 5a. Convergence report\n", - "\n", - "The **Convergence Report** shows for each problem and optimizer which problems the optimizer solved successfully, failed to do so, or where it stopped with an error. The respective strings are \"success\", \"failed\", or \"error\".\n", - "Moreover, the last column of the ```pd.DataFrame``` displays the number of dimensions of the benchmark problem." - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "16f0493e", - "metadata": {}, - "outputs": [], - "source": [ - "df = em.convergence_report(\n", - " problems=problems,\n", - " results=results,\n", - " stopping_criterion=\"y\",\n", - " x_precision=1e-4,\n", - " y_precision=1e-4,\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "3a8e42bc", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
nag_dfolsscipy_neldermeadscipy_truncated_newtondimensionality
problem
bard_good_startsuccesssuccesssuccess3
bdqrtic_8successsuccesssuccess8
box_3dsuccesssuccesssuccess3
brown_dennis_good_startsuccesssuccesssuccess4
chebyquad_6successsuccesssuccess6
freudenstein_roth_good_startsuccesssuccesssuccess2
helical_valley_good_startsuccesssuccesssuccess3
mancino_5_good_startsuccesssuccesssuccess5
powell_singular_good_startsuccesssuccesssuccess4
rosenbrock_good_startsuccesssuccesssuccess2
\n", - "
" - ], - "text/plain": [ - " nag_dfols scipy_neldermead \n", - "problem \n", - "bard_good_start success success \\\n", - "bdqrtic_8 success success \n", - "box_3d success success \n", - "brown_dennis_good_start success success \n", - "chebyquad_6 success success \n", - "freudenstein_roth_good_start success success \n", - "helical_valley_good_start success success \n", - "mancino_5_good_start success success \n", - "powell_singular_good_start success success \n", - "rosenbrock_good_start success success \n", - "\n", - " scipy_truncated_newton dimensionality \n", - "problem \n", - "bard_good_start success 3 \n", - "bdqrtic_8 success 8 \n", - "box_3d success 3 \n", - "brown_dennis_good_start success 4 \n", - "chebyquad_6 success 6 \n", - "freudenstein_roth_good_start success 2 \n", - "helical_valley_good_start success 3 \n", - "mancino_5_good_start success 5 \n", - "powell_singular_good_start success 4 \n", - "rosenbrock_good_start success 2 " - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "df" - ] - }, - { - "cell_type": "markdown", - "id": "b5215dc3", - "metadata": {}, - "source": [ - "## 5b. Rank report¶\n", - "\n", - "The **Rank Report** shows the ranks of the algorithms for each problem; where 0 means the algorithm was the fastest on a given benchmark problem, 1 means it was the second fastest and so on. If an algorithm did not converge on a problem, the value is \"failed\". If an algorithm did encounter an error during optimization, the value is \"error\"." - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "f9671d82", - "metadata": {}, - "outputs": [], - "source": [ - "df = em.rank_report(\n", - " problems=problems,\n", - " results=results,\n", - " runtime_measure=\"n_evaluations\",\n", - " stopping_criterion=\"y\",\n", - " x_precision=1e-4,\n", - " y_precision=1e-4,\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "id": "4e29d9dd", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
algorithmnag_dfolsscipy_neldermeadscipy_truncated_newton
problem
bard_good_start021
bdqrtic_8120
box_3d010
brown_dennis_good_start120
chebyquad_6021
freudenstein_roth_good_start120
helical_valley_good_start021
mancino_5_good_start120
powell_singular_good_start021
rosenbrock_good_start021
\n", - "
" - ], - "text/plain": [ - "algorithm nag_dfols scipy_neldermead scipy_truncated_newton\n", - "problem \n", - "bard_good_start 0 2 1\n", - "bdqrtic_8 1 2 0\n", - "box_3d 0 1 0\n", - "brown_dennis_good_start 1 2 0\n", - "chebyquad_6 0 2 1\n", - "freudenstein_roth_good_start 1 2 0\n", - "helical_valley_good_start 0 2 1\n", - "mancino_5_good_start 1 2 0\n", - "powell_singular_good_start 0 2 1\n", - "rosenbrock_good_start 0 2 1" - ] - }, - "execution_count": 12, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "df" - ] - }, - { - "cell_type": "markdown", - "id": "56e83beb", - "metadata": {}, - "source": [ - "## 5b. Traceback report¶\n", - "\n", - "The **Traceback Report** shows the tracebacks returned by the optimizers if they encountered an error during optimization. The resulting ```pd.DataFrame``` is empty if none of the optimizers terminated with an error, as in the example below." - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "id": "96614437", - "metadata": {}, - "outputs": [], - "source": [ - "df = em.traceback_report(results=results)" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "id": "f9d63ee9", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
scipy_neldermeadscipy_truncated_newtonnag_dfols
\n", - "
" - ], - "text/plain": [ - "Empty DataFrame\n", - "Columns: [scipy_neldermead, scipy_truncated_newton, nag_dfols]\n", - "Index: []" - ] - }, - "execution_count": 14, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "df" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "4d5e24af", - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.10" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/source/how_to_guides/optimization/how_to_do_multistart_optimizations.ipynb b/docs/source/how_to_guides/optimization/how_to_do_multistart_optimizations.ipynb deleted file mode 100644 index 38badfc3a..000000000 --- a/docs/source/how_to_guides/optimization/how_to_do_multistart_optimizations.ipynb +++ /dev/null @@ -1,549 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "fb754139", - "metadata": {}, - "source": [ - "# How to do multistart optimizations\n", - "\n", - "## How to turn on multistart\n", - "\n", - "Turning on multistart literally just means adding `multistart=True` when you call `maximize` or `minimize` and adding sampling bounds to the params DataFrame. Of course, you can configure every aspect of the multistart optimization if you want. But if you don't, we pick good defaults for you. \n", - "\n", - "Let's look at the well known \"sphere\" example again:" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "4a0bf5b4", - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import pandas as pd" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "d799cf14", - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(params):\n", - " return params[\"value\"] @ params[\"value\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "0f3f99dc", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
valuesoft_lower_boundsoft_upper_bound
01-510
12-510
23-510
\n", - "
" - ], - "text/plain": [ - " value soft_lower_bound soft_upper_bound\n", - "0 1 -5 10\n", - "1 2 -5 10\n", - "2 3 -5 10" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "params = pd.DataFrame()\n", - "params[\"value\"] = [1, 2, 3]\n", - "params[\"soft_lower_bound\"] = -5\n", - "params[\"soft_upper_bound\"] = 10\n", - "params" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "d77fee91", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
valuesoft_lower_boundsoft_upper_bound
0-0.0-510
1-0.0-510
20.0-510
\n", - "
" - ], - "text/plain": [ - " value soft_lower_bound soft_upper_bound\n", - "0 -0.0 -5 10\n", - "1 -0.0 -5 10\n", - "2 0.0 -5 10" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=params,\n", - " algorithm=\"scipy_lbfgsb\",\n", - " multistart=True,\n", - ")\n", - "res.params.round(5)" - ] - }, - { - "cell_type": "markdown", - "id": "d88e0ea5", - "metadata": {}, - "source": [ - "## Understanding multistart results\n", - "\n", - "The ``OptimizeResult`` result object of a multistart optimization has exactly the same structure as ``OptimizeResult`` from a standard optimization but with additional information.\n", - "\n", - "- `res.multistart_info[\"local_optima\"]` is a list with the results from all optimizations that were performed\n", - "- `res.multistart_info[\"start_parameters\"]` is a list with the start parameters from those optimizations \n", - "- `res.multistart_info[\"exploration_sample\"]` is a list with parameter vectors at which the criterion function was evaluated in an initial exploration phase. \n", - "- `res.multistart_info[\"exploration_results\"]` are the corresponding criterion values. " - ] - }, - { - "cell_type": "markdown", - "id": "e88747a1", - "metadata": {}, - "source": [ - "## What does multistart mean in estimagic?\n", - "\n", - "The way we do multistart optimizations is inspired by the [TikTak algorithm](https://github.com/serdarozkan/TikTak). Our multistart optimizations consist of the following steps:\n", - "\n", - "1. Draw a large sample of parameter vectors, randomly or using a low-discrepancy sequence. The size, sampling method, distribution, and more things can be configured. \n", - "2. Evaluate the criterion function in parallel on all parameter vectors.\n", - "4. Sort the parameter vectors from best to worst. \n", - "5. Run local optimizations. The first local optimization is started from the best parameter vector in the sample. All subsequent ones are started from a convex combination of the currently best known parameter vector and the next sample point. " - ] - }, - { - "cell_type": "markdown", - "id": "0ee8d218", - "metadata": {}, - "source": [ - "## How to configure mutlistart?\n", - "\n", - "As you can imagine from the above description, there are many details that can be configured. This can be done by adding a dictionary with `multistart_options` when calling `minimize` or `maximize`. Let's look at an extreme example where we manually set everything to it's default value:" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "3d76e35c", - "metadata": {}, - "outputs": [], - "source": [ - "options = {\n", - " # Set the number of points at which criterion is evaluated\n", - " # in the exploration phase\n", - " \"n_samples\": 10 * len(params),\n", - " # Pass in a DataFrame or array with a custom sample\n", - " # for the exploration phase.\n", - " \"sample\": None,\n", - " # Determine number of optimizations, relative to n_samples\n", - " \"share_optimizations\": 0.1,\n", - " # Determine distribution from which sample is drawn\n", - " \"sampling_distribution\": \"uniform\",\n", - " # Determine sampling method. Allowed: [\"sobol\", \"random\",\n", - " # \"halton\", \"hammersley\", \"korobov\", \"latin_hypercube\"]\n", - " \"sampling_method\": \"sobol\",\n", - " # Determine how start parameters for local optimizations are\n", - " # calculated. Allowed: [\"tiktak\", \"linear\"] or a custom\n", - " # function with arguments iteration, n_iterations, min_weight,\n", - " # and max_weight\n", - " \"mixing_weight_method\": \"tiktak\",\n", - " # Determine bounds on mixing weights.\n", - " \"mixing_weight_bounds\": (0.1, 0.995),\n", - " # Determine after how many re-discoveries of the currently best\n", - " # local optimum the multistart optimization converges.\n", - " \"convergence.max_discoveries\": 2,\n", - " # Determine the maximum relative distance two parameter vectors\n", - " # can have to be considered equal for convergence purposes:\n", - " \"convergence.relative_params_tolerance\": 0.01,\n", - " # Determine how many cores are used\n", - " \"n_cores\": 1,\n", - " # Determine which batch_evaluator is used:\n", - " \"batch_evaluator\": \"joblib\",\n", - " # Determine the batch size. It must be larger than n_cores.\n", - " # Setting the batch size larger than n_cores allows to reproduce\n", - " # the exact results of a highly parallel optimization on a smaller\n", - " # machine.\n", - " \"batch_size\": 1,\n", - " # Set the random seed:\n", - " \"seed\": None,\n", - " # Set how errors are handled during the exploration phase:\n", - " \"exploration_error_handling\": \"continue\",\n", - " # Set how errors are handled during the optimization phase:\n", - " \"optimization_error_handling\": \"continue\",\n", - "}" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "0664686d", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "Minimize with 3 free parameters terminated successfully after 6 criterion evaluations, 6 derivative evaluations and 4 iterations.\n", - "\n", - "The value of criterion improved from 14.0 to 6.38558109434918e-18.\n", - "\n", - "The multistart_scipy_lbfgsb algorithm reported: CONVERGENCE: NORM_OF_PROJECTED_GRADIENT_<=_PGTOL\n", - "\n", - "Independent of the convergence criteria used by multistart_scipy_lbfgsb, the strength of convergence can be assessed by the following criteria:\n", - "\n", - " one_step five_steps \n", - "relative_criterion_change 3.06e-14*** 3.06e-14***\n", - "relative_params_change 5.482e-07* 5.482e-07* \n", - "absolute_criterion_change 3.06e-15*** 3.06e-15***\n", - "absolute_params_change 5.482e-08* 5.482e-08* \n", - "\n", - "(***: change <= 1e-10, **: change <= 1e-8, *: change <= 1e-5. Change refers to a change between accepted steps. The first column only considers the last step. The second column considers the last five steps.)" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=params,\n", - " algorithm=\"scipy_lbfgsb\",\n", - " multistart=True,\n", - " multistart_options=options,\n", - ")\n", - "\n", - "res" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "0160ee53", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
valuesoft_lower_boundsoft_upper_bound
0-0.0-510
1-0.0-510
20.0-510
\n", - "
" - ], - "text/plain": [ - " value soft_lower_bound soft_upper_bound\n", - "0 -0.0 -5 10\n", - "1 -0.0 -5 10\n", - "2 0.0 -5 10" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res.params.round(5)" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "fe8ea8e0", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[Minimize with 3 free parameters terminated successfully after 3 criterion evaluations, 3 derivative evaluations and 2 iterations.\n", - " \n", - " The scipy_lbfgsb algorithm reported: CONVERGENCE: NORM_OF_PROJECTED_GRADIENT_<=_PGTOL\n", - " \n", - " Independent of the convergence criteria used by scipy_lbfgsb, the strength of convergence can be assessed by the following criteria:\n", - " \n", - " one_step five_steps\n", - " relative_criterion_change 15.17 49.8 \n", - " relative_params_change 12.32 22.32 \n", - " absolute_criterion_change 1.517 4.98 \n", - " absolute_params_change 1.232 2.232 \n", - " \n", - " (***: change <= 1e-10, **: change <= 1e-8, *: change <= 1e-5. Change refers to a change between accepted steps. The first column only considers the last step. The second column considers the last five steps.),\n", - " Minimize with 3 free parameters terminated successfully after 3 criterion evaluations, 3 derivative evaluations and 2 iterations.\n", - " \n", - " The scipy_lbfgsb algorithm reported: CONVERGENCE: NORM_OF_PROJECTED_GRADIENT_<=_PGTOL\n", - " \n", - " Independent of the convergence criteria used by scipy_lbfgsb, the strength of convergence can be assessed by the following criteria:\n", - " \n", - " one_step five_steps\n", - " relative_criterion_change 0.4662 14.78 \n", - " relative_params_change 2.159 12.16 \n", - " absolute_criterion_change 0.04662 1.478 \n", - " absolute_params_change 0.2159 1.216 \n", - " \n", - " (***: change <= 1e-10, **: change <= 1e-8, *: change <= 1e-5. Change refers to a change between accepted steps. The first column only considers the last step. The second column considers the last five steps.)]" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res.multistart_info[\"local_optima\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "43d2f994", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[ value soft_lower_bound soft_upper_bound\n", - " 0 -0.3125 -5 10\n", - " 1 -2.1875 -5 10\n", - " 2 -0.3125 -5 10,\n", - " value soft_lower_bound soft_upper_bound\n", - " 0 -0.330195 -5 10\n", - " 1 -0.330195 -5 10\n", - " 2 -1.122663 -5 10]" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res.multistart_info[\"start_parameters\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "fef26723", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[ value soft_lower_bound soft_upper_bound\n", - " 0 -0.3125 -5 10\n", - " 1 -2.1875 -5 10\n", - " 2 -0.3125 -5 10,\n", - " value soft_lower_bound soft_upper_bound\n", - " 0 -0.330195 -5 10\n", - " 1 -0.330195 -5 10\n", - " 2 -1.122663 -5 10]" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res.multistart_info[\"start_parameters\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "45ae8c65", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 4.98046875, 8.27636719, 14. , 18.75 ,\n", - " 19.04296875, 19.921875 , 21.16699219, 22.92480469,\n", - " 29.296875 , 30.76171875, 42.1875 , 48.70605469,\n", - " 64.52636719, 66.87011719, 67.45605469, 74.48730469,\n", - " 75.65917969, 75.65917969, 79.6875 , 82.32421875,\n", - " 87.01171875, 94.921875 , 106.12792969, 110.44921875,\n", - " 113.74511719, 120.19042969, 126.85546875, 131.54296875,\n", - " 141.796875 , 196.94824219])" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res.multistart_info[\"exploration_results\"]" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/source/how_to_guides/optimization/how_to_handle_errors_during_optimization.ipynb b/docs/source/how_to_guides/optimization/how_to_handle_errors_during_optimization.ipynb deleted file mode 100644 index 98ff12731..000000000 --- a/docs/source/how_to_guides/optimization/how_to_handle_errors_during_optimization.ipynb +++ /dev/null @@ -1,291 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "a096f8df", - "metadata": {}, - "source": [ - "# How to handle errors during optimization\n", - "\n", - "## Try to avoid errors\n", - "\n", - "Often, optimizers try quite extreme parameter vectors, which then can raise errors in your criterion function or derivative. Often, there are simple tricks to make your code more robust. Avoiding errors is always better than dealing with errors after they occur. \n", - "\n", - "- Avoid to take ``np.exp`` without further safeguards. With 64 bit floating point numbers, the exponential function is only well defined roughly between -700 and 700. Below it is 0, above it is inf. Sometimes you can use ``scipy.special.logsumexp`` to avoid unsafe evaluations of the exponential. Read [this](https://en.wikipedia.org/wiki/LogSumExp) for background information on the logsumexp trick.\n", - "- Set bounds for your parameters that prevent extreme parameter constellations.\n", - "- Use the ``bounds_distance`` option with a not too small value for ``covariance`` and ``sdcorr`` constraints.\n", - "- Use `estimagic.utilities.robust_cholesky` instead of normal\n", - " cholesky decompositions or try to avoid cholesky decompositions.\n", - "- Use a less aggressive optimizer. Trust region optimizers like `fides` usually choose less extreme steps in the beginnig than line search optimizers like `scipy_bfgs` and `scip_lbfgsb`. \n", - "\n", - "## Do not use clipping\n", - "\n", - "A commonly chosen solution to numerical problems is clipping of extreme values. Naive clipping leads to flat areas in your criterion function and can cause spurious convergence. Only use clipping if you know that your optimizer can deal with flat parts. " - ] - }, - { - "cell_type": "markdown", - "id": "4c551530", - "metadata": {}, - "source": [ - "## Let estimagic do its magic\n", - "\n", - "Instead of avoiding errors in your criterion function, you can raise them and let estimagic deal with them. If you are using numerical derivatives, errors will automatically be raised if any entry in the derivative is not finite. \n", - "\n", - "### An example\n", - "\n", - "Let's look at a simple example from the Moré-Wild benchmark set that has a numerical instability. " - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "5ec31d93", - "metadata": {}, - "outputs": [], - "source": [ - "import warnings\n", - "\n", - "import estimagic as em\n", - "import numpy as np\n", - "from scipy.optimize import minimize as scipy_minimize\n", - "\n", - "warnings.simplefilter(\"ignore\")" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "fec56a0b", - "metadata": {}, - "outputs": [], - "source": [ - "def jennrich_sampson(x):\n", - " dim_out = 10\n", - " fvec = (\n", - " 2 * (1.0 + np.arange(1, dim_out + 1))\n", - " - np.exp(np.arange(1, dim_out + 1) * x[0])\n", - " - np.exp(np.arange(1, dim_out + 1) * x[1])\n", - " )\n", - " return fvec @ fvec\n", - "\n", - "\n", - "correct_params = np.array([0.2578252135686162, 0.2578252135686162])\n", - "correct_criterion = 124.3621823556148\n", - "\n", - "start_x = np.array([0.3, 0.4])" - ] - }, - { - "cell_type": "markdown", - "id": "13c144d7", - "metadata": {}, - "source": [ - "### What would scipy do?" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "21383146", - "metadata": {}, - "outputs": [], - "source": [ - "scipy_res = scipy_minimize(jennrich_sampson, x0=start_x, method=\"L-BFGS-B\")" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "36d8e926", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "True" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "scipy_res.success" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "40511eb9", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(array([0.2578, 0.2578]), array([0.3384, 0.008 ]))" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "correct_params.round(4), scipy_res.x.round(4)" - ] - }, - { - "cell_type": "markdown", - "id": "ca245e3b", - "metadata": {}, - "source": [ - "So, scipy thinks it solved the problem successfully but the result is far off. (Note that scipy would have given us a warning, but we disabled warnings in order to not clutter the output).\n", - "\n", - "### Estimagic's error handling magic" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "617108b1", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(array([0.25782521, 0.25782521]), array([0.25782521, 0.25782522]))" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion=jennrich_sampson,\n", - " params=start_x,\n", - " algorithm=\"scipy_lbfgsb\",\n", - " error_handling=\"continue\",\n", - ")\n", - "\n", - "correct_params, res.params" - ] - }, - { - "cell_type": "markdown", - "id": "7fba61dd", - "metadata": {}, - "source": [ - "### How does the magic work\n", - "\n", - "When an error occurs and `error_handling` is set to `\"continue\"`, estimagic replaces your criterion with a dummy function (and adjusts the derivative accordingly). \n", - "\n", - "The dummy function has two important properties:\n", - "\n", - "1. Its value is always higher than criterion at start params. \n", - "2. Its slope guides the optimizer back towards the start parameters. I.e., if you are minimizing, the direction of strongest decrease is towards the start parameters; if you are maximizing, the direction of strongest increase is towards the start parameters. \n", - "\n", - "Therefore, when hitting an undefined area, an optimizer can take a few steps back until it is in better territory and then continue its work. \n", - "\n", - "Importantly, the optimizer will not simply go back to a previously evaluated point (which would just lead to cyclical behavior). It will just go back in the direction it originally came from.\n", - "\n", - "In the concrete example, the dummy function would look similar to the following:" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "dbf49b7b", - "metadata": {}, - "outputs": [], - "source": [ - "def dummy(params):\n", - " start_params = np.array([0.3, 0.4])\n", - " # this is close to the actual value used by estimagic\n", - " constant = 8000\n", - " # the actual slope used by estimagic would be even smaller\n", - " slope = 10_000\n", - " diff = params - start_params\n", - " return constant + slope * np.linalg.norm(diff)" - ] - }, - { - "cell_type": "markdown", - "id": "5958751d", - "metadata": {}, - "source": [ - "Now, let's plot the two functions. For better illustration, we assume that the jennrich_sampson function is only defined until it reaches a value of 100_000 and the dummy function takes over from there. " - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "061ba6c5", - "metadata": {}, - "outputs": [], - "source": [ - "from plotly import graph_objects as go\n", - "\n", - "grid = np.linspace(0, 1)\n", - "params = [np.full(2, val) for val in grid]\n", - "values = np.array([jennrich_sampson(p) for p in params])\n", - "values = np.where(values <= 1e5, values, np.nan)\n", - "dummy_values = np.array([dummy(p) for p in params])\n", - "dummy_values = np.where(np.isfinite(values), np.nan, dummy_values)" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "2556c2fb", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = go.Figure()\n", - "fig.add_trace(go.Scatter(x=grid, y=values))\n", - "fig.add_trace(go.Scatter(x=grid, y=dummy_values))\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "21c56b35", - "metadata": {}, - "source": [ - "We can see that the dummy function is lower than the highest achieved value of `jennrich_sampson` but higher than the start values. It is also rather flat. Fortunately, that is all we need. " - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/source/how_to_guides/optimization/how_to_specify_bounds.ipynb b/docs/source/how_to_guides/optimization/how_to_specify_bounds.ipynb deleted file mode 100644 index 079c50cc7..000000000 --- a/docs/source/how_to_guides/optimization/how_to_specify_bounds.ipynb +++ /dev/null @@ -1,414 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "55b3f1ad", - "metadata": {}, - "source": [ - "# How to specify bounds\n", - "\n", - "## Constraints vs bounds \n", - "\n", - "Estimagic distinguishes between bounds and constraints. Bounds are lower and upper bounds for parameters. In the literature, they are sometimes called box constraints. Examples for general constraints are linear constraints, probability constraints, or nonlinear constraints. You can find out more about general constraints in the next section on [How to specify constraints](how_to_specify_constraints.md)." - ] - }, - { - "cell_type": "markdown", - "id": "b3c135aa", - "metadata": {}, - "source": [ - "## Example criterion function\n", - "\n", - "Let’s again look at the sphere function:" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "ec477eb7", - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "b0eb906d", - "metadata": {}, - "outputs": [], - "source": [ - "def criterion(x):\n", - " return x @ x" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "6b43b46e", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([ 0.00000000e+00, -1.33177532e-08, 7.18836657e-09])" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(criterion, params=np.arange(3), algorithm=\"scipy_lbfgsb\")\n", - "res.params" - ] - }, - { - "cell_type": "markdown", - "id": "069788ac", - "metadata": {}, - "source": [ - "## Array params\n", - "\n", - "For params that are a `numpy.ndarray`, one can specify the lower and/or upper-bounds as an array of the same length.\n", - "\n", - "**Lower bounds**" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "0c450bdd", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([1., 1., 1.])" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion, params=np.arange(3), lower_bounds=np.ones(3), algorithm=\"scipy_lbfgsb\"\n", - ")\n", - "res.params" - ] - }, - { - "cell_type": "markdown", - "id": "737501d6", - "metadata": {}, - "source": [ - "**Lower & upper-bounds**" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "26c5c0df", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([-1.00000000e+00, -3.57647466e-08, 1.00000000e+00])" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion,\n", - " params=np.arange(3),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " lower_bounds=np.array([-2, -np.inf, 1]),\n", - " upper_bounds=np.array([-1, np.inf, np.inf]),\n", - ")\n", - "res.params" - ] - }, - { - "cell_type": "markdown", - "id": "95065b2b", - "metadata": {}, - "source": [ - "## Pytree params\n", - "\n", - "Now let's look at a case where params is a more general pytree. We also update the sphere function by adding an intercept. Since the criterion always decreases when decreasing the intercept, there is no unrestricted solution. Lets fix a lower bound only for the intercept." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "9c05eb78", - "metadata": {}, - "outputs": [], - "source": [ - "params = {\"x\": np.arange(3), \"intercept\": 3}\n", - "\n", - "\n", - "def criterion(params):\n", - " return params[\"x\"] @ params[\"x\"] + params[\"intercept\"]" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "ddcc54d4", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'x': array([ 0.00000000e+00, -4.42924006e-09, 2.04860640e-08]),\n", - " 'intercept': -2.0}" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion,\n", - " params=params,\n", - " algorithm=\"scipy_lbfgsb\",\n", - " lower_bounds={\"intercept\": -2},\n", - ")\n", - "res.params" - ] - }, - { - "cell_type": "markdown", - "id": "096d3ba4", - "metadata": {}, - "source": [ - "estimagic tries to match the user provided bounds with the structure of params. This allows you to specify bounds for subtrees of params. In case your subtree specification results in an unidentified matching, estimagic will tell you so with a `InvalidBoundsError`. " - ] - }, - { - "cell_type": "markdown", - "id": "1b7302c1", - "metadata": {}, - "source": [ - "## params data frame\n", - "\n", - "It often makes sense to specify your parameters in a `pandas.DataFrame`, where you can utilize the multiindex for parameter naming. In this case, you can specify bounds as extra columns `lower_bound` and `upper_bound`.\n", - "\n", - "> **Note**\n", - "> The columns are called `*_bound` instead of `*_bounds` like the argument passed to `minimize` or `maximize`. " - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "b4a95453", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
valuelower_bound
x000
111
221
intercept03-2
\n", - "
" - ], - "text/plain": [ - " value lower_bound\n", - "x 0 0 0\n", - " 1 1 1\n", - " 2 2 1\n", - "intercept 0 3 -2" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "import pandas as pd\n", - "\n", - "params = pd.DataFrame(\n", - " {\"value\": [0, 1, 2, 3], \"lower_bound\": [0, 1, 1, -2]},\n", - " index=pd.MultiIndex.from_tuples([(\"x\", k) for k in range(3)] + [(\"intercept\", 0)]),\n", - ")\n", - "params" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "34d59f01", - "metadata": {}, - "outputs": [], - "source": [ - "def criterion(params):\n", - " value = (\n", - " params.loc[\"x\"][\"value\"] @ params.loc[\"x\"][\"value\"]\n", - " + params.loc[\"intercept\"][\"value\"]\n", - " )\n", - " return float(value) # necessary since value is a pd.Series" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "b284ad8a", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
valuelower_bound
x00.00
11.01
21.01
intercept0-2.0-2
\n", - "
" - ], - "text/plain": [ - " value lower_bound\n", - "x 0 0.0 0\n", - " 1 1.0 1\n", - " 2 1.0 1\n", - "intercept 0 -2.0 -2" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "res = em.minimize(\n", - " criterion,\n", - " params=params,\n", - " algorithm=\"scipy_lbfgsb\",\n", - ")\n", - "res.params" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/source/how_to_guides/optimization/how_to_specify_the_criterion_function.md b/docs/source/how_to_guides/optimization/how_to_specify_the_criterion_function.md deleted file mode 100644 index c437a0f33..000000000 --- a/docs/source/how_to_guides/optimization/how_to_specify_the_criterion_function.md +++ /dev/null @@ -1,6 +0,0 @@ -# How to specify the criterion function and its derivatives - -(to be written.) - -In case of an urgent request for this guide, feel free to open an issue -\[here\](). diff --git a/docs/source/how_to_guides/optimization/how_to_use_logging.ipynb b/docs/source/how_to_guides/optimization/how_to_use_logging.ipynb deleted file mode 100644 index 9e2ad0f36..000000000 --- a/docs/source/how_to_guides/optimization/how_to_use_logging.ipynb +++ /dev/null @@ -1,289 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# How to use logging\n", - "\n", - "\n", - "Estimagic can keep a persistent log of the parameter and criterion values tried out by an optimizer in a sqlite database. \n", - "\n", - "The sqlite database is also used to exchange data between the optimization and the dashboard." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Turn logging on or off\n", - "\n", - "To enable logging, it suffices to provide a path to an sqlite database when calling ``maximize`` or ``minimize``. The database does not have to exist, estimagic will generate it for you. " - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(params):\n", - " return params @ params" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " logging=\"my_log.db\",\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Make logging faster\n", - "\n", - "By default, we use a very safe mode of sqlite that makes it almost impossible to corrupt the database. Even if your computer is suddenly shut down or unplugged. \n", - "\n", - "However, this makes writing logs rather slow, which becomes notable when the criterion function is very fast. \n", - "\n", - "In that case, you can enable ``\"fast_logging\"``, which is still quite safe!" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " logging=\"my_log.db\",\n", - " log_options={\"fast_logging\": True},\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Handling existing tables\n", - "\n", - "By default, we only append to databases and do not overwrite data in them. You have a few options to change this:" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "res = em.minimize(\n", - " criterion=sphere,\n", - " params=np.arange(5),\n", - " algorithm=\"scipy_lbfgsb\",\n", - " logging=\"my_log.db\",\n", - " log_options={\n", - " \"if_database_exists\": \"replace\", # one of \"raise\", \"replace\", \"extend\",\n", - " \"if_table_exists\": \"replace\", # one of \"raise\", \"replace\", \"extend\"\n", - " },\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Reading the log" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [], - "source": [ - "reader = em.OptimizeLogReader(\"my_log.db\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Read the start params" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([0, 1, 2, 3, 4])" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "reader.read_start_params()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Read a specific iteration (use -1 for the last)" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'rowid': 3,\n", - " 'params': array([ 0.00000000e+00, -2.19792136e-07, -4.01986529e-08, -1.26862247e-07,\n", - " -2.06263028e-07]),\n", - " 'internal_derivative': array([ 1.49011612e-09, -4.38094157e-07, -7.89071896e-08, -2.52234378e-07,\n", - " -4.11035941e-07]),\n", - " 'timestamp': 21972.838421234,\n", - " 'exceptions': None,\n", - " 'valid': True,\n", - " 'hash': None,\n", - " 'value': 1.08562981500731e-13,\n", - " 'step': 1,\n", - " 'criterion_eval': 1.08562981500731e-13}" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "reader.read_iteration(-1)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Read the full history" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "dict_keys(['params', 'criterion', 'runtime'])" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "reader.read_history().keys()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Plot the history from a log" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAArwAAAH0CAYAAADfWf7fAAAgAElEQVR4XuzdCXhVxf3/8W8WQja2AGEJ+xpA2QRFJGIRWqVWcalWa7Higu3freJSdwSlP/topXZRqVIFF6yiKLi2qCwqChRkCUvAQCASEtYQsi//5zuQNAQIuZl7T+45932e5/dYzJlzZl4z8vswzJwJq6ioqBAuBBBAAAEEEEAAAQQ8KhBG4PVoz9IsBBBAAAEEEEAAASNA4GUgIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgKcFCLye7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAIIeFqAwOvp7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICApwUIvJ7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgh4WoDA6+nupXEIIIAAAggggAACBF7GAAIIIIAAAggggICnBQi8nu5eGocAAggggAACCCBA4GUMIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgKcFCLye7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAIIeFqAwOvp7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICApwUIvJ7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgh4WoDA6+nupXEIIIAAAggggAACBF7GAAIIIIAAAggggICnBQi8nu5eGocAAggggAACCCBA4GUMIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgKcFCLye7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAIIeFqAwOvp7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICApwUIvJ7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgh4WoDA6+nupXEIIIAAAggggAACBF7GAAIIIIAAAggggICnBQi8nu5eGocAAggggAACCCBA4GUMIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgKcFCLye7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAIIeFqAwOvp7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICApwUIvJ7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgh4WoDA6+nupXEIIIAAAggggAACBF7GAAIIIIAAAggggICnBQi8nu5eGocAAggggAACCCBA4GUMIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgKcFCLye7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAIIeFqAwOvp7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICApwUIvJ7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgh4WoDA6+nupXEIIIAAAggggAACBF7GAAIIIIAAAggggICnBQi8nu5eGocAAggggAACCCBA4GUMIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgKcFCLye7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAIIeFqAwOvp7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICApwUIvJ7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgh4WoDA6+nupXEIIIAAAggggAACBF7GAAIIIIAAAggggICnBQi8nu5eGocAAggggAACCCBA4GUMIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgKcFCLye7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAIIeFqAwOvp7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICApwUIvJ7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgh4WoDA6+nupXEIIIAAAggggAACBF7GAAIIIIAAAggggICnBQi8nu5eGocAAggggAACCCBA4GUMIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgKcFCLye7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAIIeFqAwOvp7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICApwUIvJ7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgh4WoDA6+nupXEIIIAAAggggAACBF7GAAIIIIAAAggggICnBQi8nu5eGocAAggggAACCCBA4GUMIIAAAggggAACCHhagMDr6e6lcQgggAACCCCAAAIEXosx0LNnT0lLS7N4AkURQAAB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fPiw/P73vzfP0X/qs3v16uXX51o9zOHC/g687777ruTl5cmvfvWrqpaMHz9errvuOjn//PMdbh2vQwCBUBcg8Ib6CKD9CJxEQAPvoUOH5OGHH5ZLL7206q6GCLwDBw6UN954Q/r06eOX/vr222+lqKhIUlJSpLi42ASwl156yTrwVn+uXyrq4EP8HXjvuOMOGTJkyDGB9+2335YzzzxTOnXq5GDLeBUCCCAgQuBlFCCAwAkFNPDefPPN8uyzz8onn3xSNat6osD71ltvyfPPPy+7du0ys8IadsaOHVsnWQ2cTz31lLz//vsmYPfv318eeeQRE27T0tLk/vvvl++++06aNGkiERER8u9///u4GV59xh//+EeZP3++mVXs3r27zJ49W1auXClz586Vn//85zJlyhQzq/vNN99IZbh79NFH5bLLLpMNGzZUPV+XS/z4xz+WrKws0Z9/+eWX0rJlS/nFL34ht9xyi4SFhclnn31W63MrlwXoM/R/L126VMLDw+W8884zz6ycodZ6REdHS2Zmpvz3v/+V0tJSGTZsmKmr/vsTXdom/fmWLVukc+fOMmnSJBPYP/74Y5k2bZosWrTI1LHy0nfed999cuGFF8qf/vQn+eijj0w/tW/f3vz7ytnW6oF3586d8qMf/ci4REZGVj2rZ8+e8p///Me8d9++feZ9y5Ytk9zcXOnbt6/5dbdu3eShhx4yPo0aNZLGjRsbY+3HcePGyY033igXXXSReaa2Wd+bmpoqzZo1kyuvvFJuv/12Y6WX3q+zwu+8845onbRdv/zlL80z9FKv//u//5MPPvjA1EGD9F133SVjxoyp09jjJgQQCB0BAm/o9DUtRcAnAQ28L774osyYMcOEHg0metUMvBqw7r33XnnmmWdkwIABsnz5chPCdMZUZ2ZPdWlQ1RCq/2zdurUJShqeFy5cKPHx8aZ4v379RP+K/GRLDjT0fPXVV/L444+bILd582YZPny4CaYaOFu1amXWALdp00batWtXFXgrg+mJnq8h+dxzz5Xrr79esrOz5Te/+Y353xp86/pcXYqhddYQVlZWZsLZwYMHZebMmaZdavrPf/5TnnvuORM8CwoKTMDTwKZ/2Kh5acjU4KrBUtungfH//b//J/oHDg2hZ511lnEfPHiwKbp69Wr59a9/bUKpBmj9g4v+QUINFixYYIKz9ldl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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.criterion_plot(\"my_log.db\")\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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Sy+1KVOm2IUXXpiQ+Vq+fLllZmZajRo1bM+ePS6AjR49OnDgzdpvQgaaxE4SHXg7d+5sl19++QGB97XXXrMqVarYWWedlcQz460QQAABMwIvqwABBHIUUOC955577LnnnrN58+ZFdlVzCrzTp0+3YcOG2caNG92usMJOgwYNYpJV4Bw0aJDNnj3bBezy5cvbE0884cLtmjVrrFu3bvbFF19YsWLF7Oijj7Z33nnnoB1e9TFw4ECbM2eO21U899xzbeLEifbJJ5/YjBkz7Pbbb7fevXu7Xd2PPvrIvHD35JNPWqNGjezrr7+O9K9yiXr16tmmTZtMf7548WIrUaKENW3a1Dp06GD58uWz9957L9d+vbIA9aGff/jhh3bUUUfZ1Vdf7fr0dqg1jmOPPdY2bNhgn376qf3zzz9WtWpVN1b9fk6Hzkl//u2331qpUqWsa9euLrC//fbb1q9fP1u4cKEbo3foPR999FG77rrrbPDgwTZ37lw3TyVLlnS/7+22Zg2869evt2uuuca5HHPMMZG+ypQpY++++657323btrn3W7ZsmW3fvt0uuugi9+tzzjnHevTo4Xzy589vBQsWdMaax4YNG9rdd99tN9xwg+tT56z3/eqrr+y4446zxo0b2/333++sdOj12hV+/fXXTWPSebVo0cL1oUNezzzzjL355ptuDArSXbp0sbp168a09ngRAgjkHQECb96Za84UAV8CCryjRo2yESNGuNCjYKIje+BVwHrkkUdsyJAhVqFCBfv4449dCNOOqXZmox0Kqgqh+vGkk05yQUnhecGCBVa0aFHX/OKLLzZ9RX6okgOFniVLltjTTz/tgtzq1autWrVqLpgqcJ544omuBviUU06x0047LRJ4vWCaU/8KyVdddZXdddddtmXLFuvYsaP7uYJvrP2qFENjVgjbu3evC2d//PGHjRkzxp2XTMeOHWsvv/yyC55//fWXC3gKbLrYyH4oZCq4Kljq/BQY7733XtMFh0LoFVdc4dwrVarkmn7++efWunVrF0oVoHXhogsJGaSlpbngrPny5ter4Y0l8P7999/21ltvuV3ywoULO/vNmzfbyJEj3XurREShOWtJQ9bA++uvv7oyFa0d1WUr9Gvd6Oft27ePBN6tW7e6i5fSpUu70Ks/HzdunFtr2vVXGH7xxRfdWlFw1hqSBQcCCCCQVYDAy3pAAIEcBRR4FSTOOOMMF7K001u5cuWDAq8CjUJP1oD27LPP2qpVq+yll17KVVc7sxUrVrTJkye7AOMdzZs3t/r167t6z2iB1+tDtcbqK+uhYKrwpF3hs88+O/JH2b++zx54tYuqIKbQ7R3qX7ujkyZNcoE3Wr8KktoRVhDXLqcO7T5Xr17dXn31Vbvgggtc4NUNeQpu3qELjIyMDOed/ZCnQp8Cr3fcd999pp1X7YxqF1XhU2UoOvQ6BewBAwYc1Nf+/fvdhcT8+fPdHPvd4c3eocwU7HUBpCNa4H3hhRdcHbgCuncomCvAqy8dCsjaoX7ggQcir2nbtq3VqlXL7fRqLt544w2bMGGCFSpUiL/JCCCAwCEFCLwsDgQQyFFAgVeh5JJLLnFflyvEquzgxx9/POCmNe00anf2yiuvjPSjoKjdTAXN3I7vv//elQ98+eWXVqBAgchLFdS026hdQx257fAeqg+1UzBVCcEHH3xwwDCiBV4FUoVGfSXvHQqI2j3WV/qx9Dt16lS3+zht2rQD3vvmm292X8lrp1Lj+P333w8IpNrNfP/99yO7wFkbK1BqV1WlHd6xb98+V2Mts6VLl7pdUpVQ6Ot/7VBrHhSytSOrnWWNXzvJ+vNvvvnGza1KQPwGXu3mDh8+3IVW9b17924X6BVaYwm8Dz74oAvaGq93qL0uWlRGcvLJJ0dKGlQS4R2dOnVya1IXHKrDfvjhh021002aNLGWLVu6HV4OBBBAILsAgZc1gQACUQOvXqCgoeCpnddbb7018pQG3Zg0dOjQAwKvQpV2FaMFXu0Cq54ze+BVHa1CWSyBVyUW11577UF9eIFXgU+7mFmPaIFXO866wUqBNadDgTdav9p1VNlA9sB70003Wbt27SKBN/ujwHILvKqN9mpvcxqXwq9Crmp1Vaag3VKFXwVkBWLtJmuuTj31VFOAP//8892udSyBV+GyXLlykRpeBXeVTjz00ENWpEgRFzq1yxxr4NXYVO8bLfBmrfn11qEXeD0DrSOVhqhkQxdpCvgcCCCAQFYBAi/rAQEEYgq8qqXUV8zazVVY8R5Lpl01lTR4dZfqTLvBuuFJtbi5HdoVVJmEQl7Wel+VNKiOVTWzOnLb4VUQ857ikL1mOJZgqv4VoBRMvadAKLwpaGlnWDdTZT9i6Vd9qO43p5IGlTDoJq+cnoyQW+DV49QWLVrkanYPdahP3czl7QI//vjj7qUK2ioR0cWKjh9++MEZ57TD+9tvv7mnKWiOvTpq3UCoGxF1MXPCCSe4sKudaO3S6tCuuOq4vcArP+36q4bYO7LW8Opc1L9Xz6zXqK3MVJusHejsN7kdKvB6/as8QgFf4ZcDAQQQIPCyBhBAIKpA1pIG78W6cWz8+PHuP4DwAq/KFxSqvJvWVqxY4Wo5FXYVZlVDqhu9tFt72WWXHfS+CmhqoyCtr7G1s6paVfVbvHjxqIFXL+jVq5d7koN2XbV7qa/q9bQHfcUfbSdW7VWjrECoOmSFRdXc6okBCrt6Rq8CnnaSFdAV4mIJvNpt1U1rqtX1blrTrrcuHLT7q8Nv4NVNa7q5TXXTuijQ0wy0a6sburRLq0M3bmk3XoFRFx7aldWhIKkb1/Sev/zyizNTwFSZSvYdXr1eO8Vq06xZM1c6oJ1chWMFXj0NQXOrHV3NrXbotQYUlL3Aq/51I5p2XGWhGtusAVZPsFCAVr+y925a01zogkpHtMCriwrNlYxVy62bEFWGwn9MEvWvNy9AIM8JsMOb56acE0YgNoGcAq9a6mYkhd2s//HErFmzXEj96aef3I6fApdCjA7VeqrGVIFYTxHIfihgKpgp6OrRUtpt1WOtvKCm10d7SoPKHxRsVd+qEgHdxKWbzBSIYgm82snVe+rJAQql119/vQuFCk66CUthSo9b081TKp+IJfBq3AqoTz31lNuV9UKkaooVoOMJvGqjYK8x6keVLagsQeUK5513XoRWoVGuWUtKVOusG/EUiHVRoICqixL55BR4ddOdAqQuWBQqVYahmxh1waOnIMjAezKDdqt1nnqN6m91KMAqEOviQ/W1etRc9gC7cuVKZ6wfdXGj3WfV9nq709ECr8YgC93Ip5v1VMqgoB30PyaJ7W8Ir0IAgTAJEHjDNFuMFQEEEEAAAQQQQMC3AIHXNxkNEEAAAQQQQAABBMIkQOAN02wxVgQQQAABBBBAAAHfAgRe32Q0QAABBBBAAAEEEAiTAIE3TLPFWBFAAAEEEEAAAQR8CxB4fZPRAAEEEEAAAQQQQCBMAgTeMM0WY0UAAQQQQAABBBDwLUDg9U1GAwQQQAABBBBAAIEwCRB4wzRbjBUBBBBAAAEEEEDAtwCB1zcZDRBAAAEEEEAAAQTCJEDgDdNsMVYEEEAAAQQQQAAB3wIEXt9kNEAAAQQQQAABBBAIkwCBN0yzxVgRQAABBBBAAAEEfAsQeH2T0QABBBBAAAEEEEAgTAIE3jDNFmNFAAEEEEAAAQQQ8C1A4PVNRgMEEEAAAQQQQACBMAkQeMM0W4wVAQQQQAABBBBAwLcAgdc3GQ0QQAABBBBAAAEEwiRA4A3TbDFWBBBAAAEEEEAAAd8CBF7fZDRAAAEEEEAAAQQQCJMAgTdMs8VYEUAAAQQQQAABBHwLEHh9k9EAAQQQQAABBBBAIEwCBN4wzRZjRQABBBBAAAEEEPAtQOD1TUYDBBBAAAEEEEAAgTAJEHjDNFuMFQEEEEAAAQQQQMC3AIHXNxkNEEAAAQQQQAABBMIkQOAN02wxVgQQQAABBBBAAAHfAgRe32Q0QAABBBBAAAEEEAiTAIE3TLPFWBFAAAEEEEAAAQR8CxB4fZPRAAEEEEAAAQQQQCBMAgTeMM0WY0UAAQQQQAABBBDwLfBfv4k4qsqdiisAAAAASUVORK5CYII=" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.params_plot(\"my_log.db\", selector=lambda x: x[1:3])\n", - "fig.show(renderer=\"png\")" - ] - } - ], - "metadata": { - "interpreter": { - "hash": "5cdb9867252288f10687117449de6ad870b49795ca695c868016dc0022895cce" - }, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/source/how_to_guides/optimization/how_to_use_the_dashboard.md b/docs/source/how_to_guides/optimization/how_to_use_the_dashboard.md deleted file mode 100644 index d283ce5af..000000000 --- a/docs/source/how_to_guides/optimization/how_to_use_the_dashboard.md +++ /dev/null @@ -1,115 +0,0 @@ -(dashboard)= - -# How to use the dashboard - -## Overview - -Estimagic provides a dashboard that allows to inspect an optimization. The dashboard -visualizes the database created and updated by an optimization. You can start a -dashboard by typing the following in your command-line interface: - -```bash -$ estimagic dashboard db1.db -``` - -You can configure the behavior of the dashboard with additional command line arguments. - -To get a list of all supported arguments type `estimagic dashboard --help` : - -``` -Usage: estimagic dashboard [OPTIONS] DATABASE_PATH - -Start the dashboard to visualize optimizations. - -Options: --p, --port INTEGER The port the dashboard server will listen on. ---no-browser Don't open the dashboard in a browser after - startup. - ---jump Jump to start the dashboard at the last rollover - iterations. - ---rollover INTEGER After how many iterations convergence plots get - truncated from the left. [default: 10000] - ---update-frequency FLOAT Number of seconds to wait between checking for new - entries in the database. [default: 1] - ---update-chunk INTEGER Upper limit how many new values are updated from - the database at one update. [default: 20] - ---stride INTEGER Plot every stride_th database row in the - dashboard. Note that some database rows only - contain gradient evaluations, thus for some values - of stride the convergence plot of the criterion - function can be empty. [default: 1] -``` - -When started, the dashboard will open a page monitoring the evolution of the criterion -value and parameters. - -```{image} ../../_static/images/dashboard.gif -``` - -## Grouping Parameters into Plots - -For optimization problems with many parameters, you should group parameters such that: - -- Not too many parameters are displayed in a single plot -- All parameters in one plot have a similar order of magnitude - -To do so, you can add a `"group"` column to your params DataFrame. Parameters that -belong to the same group, are displayed in the same plot. Null values like `None`, -`np.nan` and `False` in the group column mean that the parameter is not displayed in the -dashboard. - -(remote-server)= - -## On a remote server - -Since `estimagic` is designed for long running optimizations, it is often run on large -remote servers. Normally, these servers do not offer a GUI or browser. - -Nevertheless, you can display the dashboard in your local browser. To do so, you have to -create an ssh tunnel. All the steps are identical to tunneling a jupyter notebook via -ssh. - -For the following we assume that you have already started an optimization on the server -(which can be terminated or still running) and the log was saved in `your.db`. - -1. Open Bash, Powershell, CMD or Terminal. - -1. Listen to a port on which the dashboard will send its data, e.g. 10101 - - ```bash - ssh -N -f -L localhost:10101:localhost:10101 username@server-address - ``` - - `-N` prevents to commands on the remote, `-f` hides the connection in the background, - so the console windows is not blocked, `-L` is used to bind your local port to a - remote port. At last, type your server user name and the server address separated - with an `@`. You are asked to enter your password to establish the connection. - -1. Now, log into the remote server with - - ```bash - ssh username@server-address - ``` - - and enter your password. - -1. One the remote, launch the dashboard on the correct port and with the `--no-browser` - option - - ```bash - estimagic dashboard your.db --no-browser --port=10101 - ``` - - Use a leading `&` in a Bash or Powershell v6 Terminal to hide the task in the - background. If your terminal is blocked, open another one. - -1. On your local machine, open a web browser and enter the address `localhost:10101`. - -1. That's it. For more information on `ssh` and how to configure your remote machine, - check out - [Working remotely in shell environments](https://github.com/OpenSourceEconomics/ose-meetup/blob/master/material/2019_08_20/17_shell_remote.pdf). diff --git a/docs/source/how_to_guides/optimization/how_to_visualize_an_optimization_problem.ipynb b/docs/source/how_to_guides/optimization/how_to_visualize_an_optimization_problem.ipynb deleted file mode 100644 index bf15c0422..000000000 --- a/docs/source/how_to_guides/optimization/how_to_visualize_an_optimization_problem.ipynb +++ /dev/null @@ -1,165 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# How to visualize an optimization problem\n", - "\n", - "Plotting the criterion function of an optimization problem can answer important questions\n", - "- Is the function smooth?\n", - "- Is the function flat in some directions?\n", - "- Should the optimization problem be scaled?\n", - "- Is a candidate optimum a global one?\n", - "\n", - "Below we show how to make a slice plot of the criterion function." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## The simple sphere function (again)\n", - "\n", - "Let's look at the simple sphere function again. This time, we specify params as dictionary, but of course, any other params format (recall [pytrees](https://jax.readthedocs.io/en/latest/pytrees.html)) would work just as well. " - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(params):\n", - " x = np.array(list(params.values()))\n", - " return x @ x" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [], - "source": [ - "params = {\"alpha\": 0, \"beta\": 0, \"gamma\": 0, \"delta\": 0}\n", - "lower_bounds = {name: -5 for name in params}\n", - "upper_bounds = {name: i + 2 for i, name in enumerate(params)}" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Creating a simple slice plot" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAAyAAAAJYCAYAAACadoJwAAAgAElEQVR4XuzdB3gVxd7H8R8BAiShN+kdpRcB6b1IURQVG4ooqNgV9AqCylWxvFzBiiIgKiAoKAg2lF6kWOgtFOm9BhISSt5nFhMpITknu2dzynef5z5cye6Uzywz+e/uzGRKTExMFAcCCCCAAAIIIIAAAggg4IJAJgIQF5TJAgEEEEAAAQQQQAABBCwBAhBuBAQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAABBBBAAAECEO4BBBBAAAEEEEAAAQQQcE2AAMQ1ajJCAAEEEEAAAQQQQAABAhDuAQQQQAABBBBAAAEEEHBNgADENWoyQgABBBBAAAEEEEAAAQIQ7gEEEEAAAQQQQAABBBBwTYAAxDVqMkIAAQQQQAAB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QAABBBBwQIAAxAFEkkAAAQQQQAABBBBAAAHPBAhAPHPiLAQQQAABBBBAAAEEEHBAgADEAUSSQAABBBBAAAEEEEAAAc8ECEA8c+IsBBBAAAEEEEAAAQQQcECAAMQBRJJAAAEEEEAAAQQQQAABzwQIQDxz4iwEEEAAAQQQQAABBBBwQIAAxAFEkkAAAQQQQAABBBBAAAHPBAhAPHPiLAQQQAABBBBAAAEEEHBAgADEAUSSQAABBBBAAAEEEEAAAc8ECEA8c+IsBBBAAAEEEEAAAQQQcECAAMQBRJJAAAEEEEAAAQQQQAABzwQIQDxz4iwEEEAAAQQQQAABBBBwQIAAxAFEkkAAAQQQQAABBBBAAAHPBAhAPHPiLAQQQAABBBBAAAEEEHBAgADEAUSSQAABBBBAAAEEEEAAAc8ECEA8c+IsBBBAAAEEEEAAAQQQcECAAMQBRJJAAAEEEEAAAQQQQAABzwQIQDxz4iwEEEAAAQQQQAABBBBwQIAAxAFEkkAAAQQQQAABBBBAAAHPBAhAPHPiLAQQQAABBBBAAAEEEHBAgADEAUSSQAABBBBAAAEEEEAAAc8ECEA8c+IsBBBAAAEEEEAAAQQQcECAAMQBRJJAAAEEEEAAAQQQQAABzwQIQDxz4iwEEEAAAQQQQAABBBBwQIAAxAFEkkAAAQQQQAABBBBAAAHPBAhAPHPiLAQQQAABBBBAAAEEEHBAgADEAUSSQAABBBBAAAEEEEAAAc8ECEA8c+IsBBBAAAEEEEAAAQQQcECAAMQBRJJAAAEEEEAAAQQQQAABzwQIQDxz4iwEEEAAAQQQQAABBBBwQIAAxAFEkkAAAQQQQAABBBBAAAHPBAhAPHPiLAQQQAABBBBAAAEEEHBAgADEAUSSQAABBBBAAAEEEEAAAc8ECEA8c+IsBBBAAAEEEEAAAQQQcECAAMQBRJJAAAEEEEAAAQQQQAABzwQIQDxz4iwEEEAAAQQQQAABBBBwQIAAxAFEkkAAAQQQQAABBBBAAAHPBAhAPHPiLAQQQAABBBBAAAEEEHBAgADEAUSSQAABBBBAAAEEEEAAAc8ECEA8c+IsBBBAAAEEEEAAAQQQcECAAMQBRJJAAAEEEEAAAQQQQAABzwQIQDxz4iwEEEAAAQQQQAABBBBwQIAAxAFEkkAAAQQQQAABBBBAAAHPBAhAPHPiLAQQQAAB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qlULvXv3pgBxgzHKJpIACbyagNzvEBPaXbt2xZi8nj59Ws3p0SZYslkjd/XkuVel2AJEhMYHH3ygzLiik5QlZlzR5q5igtugQQOegHBQkoCVBChArATGx81NYOXKlZA/48aNg4eHB1KlShVzsVAWMll05MKi7HiJza/c45AjfS0FyLx581QdFixYoOycp06dit9//12d1NAEy9zjk60jARJ4PQFxuStmtPJHnH48ePBAecQSQRItQESkiMdA2UySu35yH082gN5++201n8YWIGLiWrVqVTXXyimKrAn9+/dH0qRJlXfDmzdvQk7N9+3bh1WrVvEEhIOTBKwgQAFiBSw+an4CspDIjpecakiSBUe8qsh9DblELh/78+fPVx6wxCxLTLLk6F1LASLvlvsechIjC+H777+v6iPuIClAzD9G2UISIIHXEzh16pQykxU3vGIKK2Ljl19+USIi+pK43BMRN7xyFy9lypQoV66c8ooVV4DIW2bMmKHMXcXUSjan5A6IzL/yHjHBEnNYKUvMumiCxZFJApYToACxnBWfNDkBcWfbvXt3tVgVKVJEtVbufXTr1g29evV6wWuKyVGweSRAAiRAAiRAAiTgNAIUIE5Dy4KNRmDu3Lk4duyYulwYO8kOmphZ8XTBaD3K+pIACZAACZAACeiRAAWIHnuFdXIJAbENluN0ceWYK1cuiD2xmFfJPY/ly5cjd+7cLqkXX0oCJEACJEACJEACZiJAAWKm3mRb7CYgpyBiKyyuGyWqrZhiyQmIeE1hIgESIAESIAESIAESsJ8ABYj9DFkCCZAACZAACZAACZAACZCAhQQoQCwExcdIgARIgARIgARIgARIgATsJ0ABYj9DlkACJEACJEACJEACJEACJGAhAQoQC0HxMRIgARIgARIgARIgARIgAfsJUIDYz5AlkAAJkAAJkAAJkAAJkAAJWEiAAsRCUHyMBEiABEiABEiABEiABEjAfgIUIPYzZAkkQAIkQAIkQAIkQAIkQAIWEqAAsRAUHyMBEiABEiABEiABEiABErCfAAWI/QxZAgmQAAmQAAmQAAmQAAmQgIUEKEAsBMXHSIAESIAESIAESIAESIAE7CdAAWI/Q5ZAAiRAAiRAAiRAAiRAAiRgIQEKEAtB8TESIAESIAESIAESIAESIAH7CVCA2M+QJZAACZAACZAACZAACZAACVhIgALEQlB8jARIgARIgARIgARIgARIwH4CFCD2M2QJJEACJEACJEACJEACJEACFhKgALEQFB8jARIgARIgARIgARIgARKwnwAFiP0MWQIJkAAJkAAJkAAJkAAJkICFBChALATFx0iABEiABEiABEiABEiABOwnQAFiP0OWQAIkQAIkQAIkQAIkQAIkYCEBChALQfExEiABEiABEiABEiABEiAB+wlQgNjPkCWQAAmQAAmQAAmQAAmQAAlYSIACxEJQfIwESIAESIAESIAESIAESMB+AhQg9jNkCSRAAiRAAiRAAiRAAiRAAhYSoACxEBQfIwESIAESIAESIAESIAESsJ8ABYj9DFkCCZAACZAACZAACZAACZCAhQQoQCwExcdIgARIgARIgARIgARIgATsJ0ABYj9DlkACJEACJEACJEACJEACJGAhgf8DKjGkyK7DXqoAAAAASUVORK5CYII=" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.slice_plot(\n", - " func=sphere,\n", - " params=params,\n", - " lower_bounds=lower_bounds,\n", - " upper_bounds=upper_bounds,\n", - ")\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Interpreting the plot\n", - "\n", - "The plot gives us the following insights:\n", - " \n", - "- There is no sign of local optima. \n", - "- There is no sign of noise or non-differentiablities (careful, grid might not be fine enough).\n", - "- The problem seems to be convex.\n", - "\n", - "-> We would expect almost any derivative based optimizer to work well here (which we know to be correct in that case)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Using advanced options" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.slice_plot(\n", - " func=sphere,\n", - " params=params,\n", - " lower_bounds=lower_bounds,\n", - " upper_bounds=upper_bounds,\n", - " # selecting a subset of params\n", - " selector=lambda x: [x[\"alpha\"], x[\"beta\"]],\n", - " # evaluate func in parallel\n", - " n_cores=4,\n", - " # rename the parameters\n", - " param_names={\"alpha\": \"Alpha\", \"beta\": \"Beta\"},\n", - " title=\"Amazing Plot\",\n", - " # number of gridpoints in each dimension\n", - " n_gridpoints=50,\n", - ")\n", - "fig.show(renderer=\"png\")" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/source/how_to_guides/optimization/how_to_visualize_histories.ipynb b/docs/source/how_to_guides/optimization/how_to_visualize_histories.ipynb deleted file mode 100644 index 8de31a420..000000000 --- a/docs/source/how_to_guides/optimization/how_to_visualize_histories.ipynb +++ /dev/null @@ -1,279 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "26bb6b59", - "metadata": {}, - "source": [ - "# How to visualize optimizer histories\n", - "\n", - "Estimagic's `criterion_plot` can visualize the history of function values for one or multiple optimizations. \n", - "Estimagic's `params_plot` can visualize the history of parameter values for one optimization. \n", - "\n", - "This can help you to understand whether your optimization actually converged and if not, which parameters are problematic. \n", - "\n", - "It can also help you to find the fastest optimizer for a given optimization problem. " - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "8675ff3f", - "metadata": {}, - "outputs": [], - "source": [ - "import estimagic as em\n", - "import numpy as np" - ] - }, - { - "cell_type": "markdown", - "id": "bb392c18", - "metadata": {}, - "source": [ - "## Run two optimization to get example results" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "5efb43c8", - "metadata": {}, - "outputs": [], - "source": [ - "def sphere(x):\n", - " return x @ x\n", - "\n", - "\n", - "results = {}\n", - "for algo in [\"scipy_lbfgsb\", \"scipy_neldermead\"]:\n", - " results[algo] = em.minimize(sphere, params=np.arange(5), algorithm=algo)" - ] - }, - { - "cell_type": "markdown", - "id": "a6472dcc", - "metadata": {}, - "source": [ - "## Make a single criterion plot" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "32cf04a2", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAArwAAAH0CAYAAADfWf7fAAAgAElEQVR4Xu3dC5zN1f7/8Y9IMTqKmjlyKzJTynCQUCiXc+IQqTg5RUWpfpLQBSkk5+gnqc5JnPJTcgsdMqGOUSG6ihn3iTk0lanjMppxl//js07f/R9jbnvW3t/Z3+9+fR+PHsJe3+9az7XGfu+113d9y5w6deqUcCCAAAIIIIAAAggg4FOBMgRen/YszUIAAQQQQAABBBAwAgReBgICCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgj4WoDA6+vupXEIIIAAAggggAACBF7GAAIIIIAAAggggICvBQi8vu5eGocAAggggAACCCBA4GUMIIAAAggggAACCPhagMDr6+6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgK8FCLy+7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAII+FqAwOvr7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgj4WoDA6+vupXEIIIAAAggggAACBF7GAAIIIIAAAggggICvBQi8vu5eGocAAggggAACCCBA4GUMIIAAAggggAACCPhagMDr6+6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgK8FCLy+7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAII+FqAwOvr7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgj4WoDA6+vupXEIIIAAAggggAACBF7GAAIIIIAAAggggICvBQi8vu5eGocAAggggAACCCBA4GUMIIAAAggggAACCPhagMDr6+6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgK8FCLy+7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAII+FqAwOvr7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgj4WoDA6+vupXEIIIAAAggggAACBF7GAAIIIIAAAggggICvBQi8vu5eGocAAggggAACCCBA4GUMIIAAAggggAACCPhagMDr6+6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgK8FCLy+7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAII+FqAwOvr7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgj4WoDA6+vupXEIIIAAAggggAACBF7GAAIIIIAAAggggICvBQi8vu5eGocAAggggAACCCBA4GUMIIAAAggggAACCPhagMDr6+6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgK8FCLy+7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAII+FqAwOvr7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgj4WoDA6+vupXEIIIAAAggggAACBF7GAAIIIIAAAggggICvBQi8vu5eGocAAggggAACCCBA4GUMIIAAAggggAACCPhagMDr6+6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgK8FCLy+7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAII+FqAwOvr7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgj4WoDA6+vupXEIIIAAAggggAACBF7GAAIIIIAAAggggICvBQi8vu5eGocAAggggAACCCBA4GUMIIAAAggggAACCPhagMDr6+6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgK8FCLy+7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAII+FqAwOvr7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOBlDCCAAAIIIIAAAgj4WoDA6+vupXEIIIAAAggggAACBF7GAAIIIIAAAggggICvBQi8vu5eGocAAggggAACCCBA4GUMIIAAAggggAACCPhagMDr6+6lcQgggAACCCCAAAIEXsYAAggggAACCCCAgK8FCLy+7l4ahwACCCCAAAIIIEDgZQwggAACCCCAAAII+FqAwOvr7qVxCCCAAAIIIIAAAgRexgACCCCAAAIIIICArwUIvL7uXhqHAAIIIIAAAgggQOC1GAP16tWTtLQ0izNQFAEE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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.criterion_plot(results[\"scipy_neldermead\"])\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "4a2050c4", - "metadata": {}, - "source": [ - "## Compare two optimizations in a criterion plot" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "d641708a", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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00+b9mg/GjVqZD4A1KlTR9atWyd33nmnjBkzhsCbHT8cYX5NAq8FaPLA69u5SZJmPRs4Y1y3USKFLrB4BaoigAACCDghkDi6qxMvk+I1UpsY2bx5szzwwANmRrNWrVqBOv/5z39M6B00aNBZ50keeHfv3m1miLX4fD6pXr26maX97rvvZMaMGfL666+Lhj4Ncxr4/DOiyRun4VGDrP+GLQ2uOsOss6jaPq2vAVHLSy+9ZEKoBtrgGd5u3bqZkN64cWNz3JdffmlmVzVgan9+++03GThwoPk7ncnVcKkhWfv0008/mRllf9HzakDWm8i09O3bV6655hoT3LVoOL744ovNbHN67Qvup4bca6+9VnTWV2d3tS36YcFf7rrrLhOkuWktW348wvqiBF4LTn/gfeb626Vw7nMleeD1tujOjWsWvlRFAAEEnBKIphle7fP3338v48ePN8H0kUceMV/l60ykzujed9996QbeI0eOSO/evQPHaCjVAKkzmvXr15d58+aZUKdrfx977LE0iTVg6mv5Z4A1pC5atMjMsOrSBJ1hzpMnj6mvM8xNmjQx5wsOvDoLO3ToUKlcubI5TsO8zirrubQ/uiSicOHC5u90aYQue9DlC/5lCnpscOANbo/OCOtSBP+MtS6NuOCCC+See+5Jt31fffWV6I1+OsurRT8IaNjVDwXTpk0zs9b+ojtKsKTBqZ/CyL4OgdfC1x94R17XUormyR84UxL78VqoUhUBBBBAwC+wfv166dq1q3z00Udmva7O3uoa0+CSfIZX1+/q8gItOoOpM7y6dleDpX5dr8sGNGjqbObVV1+dbuDV5QW6tlZLcODVGVSdWdXlA8lL8hne9u3bm7XAWr755hsz++yf4d23b59ZypC8BPcpOPAGtye9wJtW+w4cOGBmpWfOnCmXX3656IeDmjVrmsCr/+l6Xl1O4i8dOnSQu+++mxleF/xIEngtBjGtwOvbulqS5o0TblyzwKUqAgggkEMFdG3rueeeK+eff74JZDrD+N5770lCQoIJX1OnTpXLLrvMhN+LLrooxRpeXdOqs6RlypQxs5V6w5guE9Dy448/yrBhw8yNbYsXL05XOPluC8GBV9fw6myozkLrrKzeAKbLJ3QGOrieHqNrkvUGN1060a9fP3OjnJ5LlzNoaNb26vupzhLv3bvXrFe2DbxptU89dSmG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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.criterion_plot(results)\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "2b875eed", - "metadata": {}, - "source": [ - "## Use some advanced options of criterion_plot" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "72b6938c", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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IFBEAgReH9AEXh94dEUAAQQQQAABBIpIgMDrA5rA6wOPrggggAACCCCAQBEJEHh9QBN4feDRFQEEEEAAAQQQKCIBAq8PaAVeGgIIIBCLQGZmps2fPz+WLrwWAQQQsKysLBR8CBB4feBNmDDBcnJyrEOHDj5GoSsCewsMHDjQzj77bDvrrLPgQaBQBTp16mR9+vSxY445plDHZTAEmjZtau+88w4QCCSkAIHXx7IQeH3g0TVfAQIvJ0i8BAi88ZJlXAIv50AiCxB4fawOgdcHHl0JvJwDxSJA4C0W9pR4UwJvSixz0h4kgdfH0hF4feDRlcDLOVAsAgTeYmFPiTcl8KbEMiftQRJ4fSwdgdcHHl0JvJwDxSJA4C0W9pR4UwJvSixz0h4kgTdpl46JI4AAAggggAACCEQjQOCNRonXIIAAAggggAACCCStAIE3aZeOiSOAAALUhcG4AAATZUlEQVQIIIAAAghEI0DgjUaJ1yCAAAIIIIAAAggkrQCBN2mXjokjgAACCCCAAAIIRCNA4I1GKeQ1e/bssfvuu89mzZplJUqUsJtvvtmuuuqqAoxEFwTM/aS+RYsWWVpamuO4+uqrrVevXu7306ZNs5EjR9rOnTtNd0APGDDA0tPTYUMgT4E///zTevTo4b4+evTowOs2b95sd955py1evNjKly9vQ4YMsTp16riv6+/uuusu27Rpk1WvXt0efPBBq1SpEsoI5BL4/vvvrXPnztauXTu7/vrrA1/L73sY5xYnUaIIEHgLsBJTp061mTNn2tixY2379u3uH/9DDz1kp5xySgFGo0uqC7Ro0cL0iDuFkOC2evVqF4YnT57swodCTK1ataxjx46pTsbx5yGwfv1669Kli9WuXdt+/vnnXIG3Z8+edsQRR1i3bt1cwNWvb731lrto18XUvffe636U9fPPP2/z5s2zMWPG4IxAQGD+/Pnugvv4449351dw4M3re9ju3bs5tziHEkaAwFuApbjhhhvsuuuus0aNGrnezz33nOk/mt69exdgNLqkuoDOo48//jiww+t56IJq69atpqCitnz5cneOTZ8+PdXJOP48BLZt22YrV650nwgouHo7vPpUqm7dujZ37lwrVaqU661Ppq644gqrUKGCDR482HQhr6bXnnHGGfbuu+9amTJlsEbACWRlZbnzQRfg5cqVyxV48/oe9vXXX3Nucf4kjACBtwBLcd5559n48ePdbomawor+/PTTTxdgNLqkuoB2Sw499FD3acHJJ5/sQm3lypWtT58+LqS0bNnSEWVnZ7s/L1myJNXJOP4IAgq2+tTAC7za7dUnUR9++GGg5wMPPGAHHnig+/RAO7rDhg0LfK1169Z2991326mnnoo1ArkE9GnmQQcdlCvw5vU9bMaMGZxbnD8JI0DgLcBSNGzY0F577TW3M6K2YMECV2c5ceLEAoxGl1QX0K7c/vvvb7t27XIh5ZVXXnH14d27d7cmTZpY8+bNA0T6OHHVqlV77QanuiHHn1sgNPCq9lKlDrNnzw68cNSoUW43Vxdby5Ytcx9Xe0115F27drXMzExoEYgYePP6HjZlyhTOLc6fhBEg8BZgKRRCxo0bZ1WqVHG933vvPRd29Xc0BPwKNGjQwIVeBZKaNWtamzZt3JD6T0UBZOnSpX7fgv7/coHQwLthwwZr1aqVzZkzJ3DkummtYsWKLvB+9NFH7kY1r1166aU2cOBAd/7REAgWCLfDGyrkfQ/TZhDnFudPoggQeAuwErpLtW3btnbuuee63k899ZTpP5R+/foVYDS6IJBboH79+vb222+7JzTovPJqw3WjUd++fd0NkzQE8hMIDbw5OTl2+umn2/vvv29ly5Z1XW+88Ub3fezwww9355VXG65PGurVq+deq5IHGgKxBl7ve9jatWs5tzh9EkaAwFuApVBdksKI95QG7cANHTrU/YdCQyAWAQXajRs3Wo0aNUyhRHXg2hF54YUXTP9ZtG/f3iZNmhR4SkO1atXcR800BGIJvHqtasK1o3v77be7pzSoxEE3ppUuXdqaNWtm/fv3dzfi6mY3/b3Ka2gIhAqE7vDm9z1MJTOcW5xDiSJA4C3gSgwfPtyFXj07VU9t6NSpUwFHolsqC6xbt849HmrNmjVWsmRJ97gf7bZ5z0BVLa9uJtqxY4c1btzYPTs1IyMjlck49igEQnd41UVP/NDznRcuXOh2efUYMu9JMytWrHBf++mnn6xq1ao2YsQId+MkDYFIgTfS9zDOLc6hRBEg8CbKSjAPBBBAAAEEEEAAgbgIEHjjwsqgCCCAAAIIIIAAAokiQOBNlJVgHggggAACCCCAAAJxESDwxoWVQRFAAAEEEEAAAQQSRYDAmygrwTwQQAABBBBAAAEE4iJA4I0LK4MigAACCCCAAAIIJIoAgTdRVoJ5IIAAAggggAACCMRFgMAbF1YGRQABBBBAAAEEEEgUAQJvoqwE80AAAQQQQAABBBCIiwCBNy6sDIoAAggggAACCCCQKAIE3kRZCeaBAAIIIIAAAgggEBcBAm9cWBkUAQQQQAABBBBAIFEECLyJshLMAwEEEEAAAQQQQCAuAgTeuLAyKAIIIIAAAggggECiCBB4E2UlmAcCCCCAAAIIIIBAXAQIvHFhZVAEEEAAAQQQQACBRBEg8CbKSjAPBBBAAAEEEEAAgbgIEHjjwsqgCCCAAAIIIIAAAokiQOBNlJVgHgggkKfA4sWLrW/fvvbDDz/YxRdfbPfddx9ahSwwdOhQ2759uw0aNKiQR2Y4BBBAoPgFCLzFvwbMAIGEFGjcuLFVrlzZXnjhhVzz++6776x169a2aNGiIpu33q9JkybWsWNHF8oOPPBAX+89atQo+/PPP+2uu+5y4+hXjV2tWrVCHdfXYEXcubAD76uvvmrbtm2za665JnAkHTp0sGuvvdbOO++8Ij463g4BBFJdgMCb6mcAx49AHgIKvH/88Yf179/fLr/88sCriiPw1qpVyyZNmmQnnnhioazXggULLDs72xo1amQ7d+50AWzcuHG+A2/wuIUy0SIcpLADb7du3axu3bq5Au/LL79s9erVs6OOOqoIj4y3QgABBMwIvJwFCCAQVkCB96abbrJHH33U3nrrrcCuarjAO3XqVBs9erStX7/e7Qor7DRv3jwqWQXOESNG2GuvveYC9qmnnmp33323C7dZWVnWu3dv+/rrr61MmTKWnp5u77zzzl47vBpj+PDhNnPmTLerWLVqVZswYYItXLjQpk2bZldccYUNHDjQ7ep+9tln5oW7e+65x1q2bGnLly8PjK9yifPPP99+/vln09fnzp1rFSpUsHbt2lmXLl0sLS3N3n///XzH9coCNIZ+P2fOHNtnn33s7LPPdmN6O9Sax3777Wfr1q2zL7/80nbt2mWZmZlurvr7cE3HpK9/++23VqVKFevRo4cL7LNnz7YhQ4bYRx995OboNb3nf/7zH7vwwgvtoYcesjfffNOt0+GHH+7+3tttDQ68a9eutXPOOce57LvvvoGxjj/+eHv33Xfd+27evNm93/z5823r1q120kknuT8fe+yx1q9fP+dTokQJK1mypDPWOl522WV244032kUXXeTG1DHrfZctW2blypWzNm3a2G233eas1PR67Qq/8sorpjnpuK666io3hpq87r//fnv99dfdHBSku3fvbk2bNo3q3ONFCCCQOgIE3tRZa44UgZgEFHiffvppGzt2rAs9CiZqoYFXAatXr1728MMPW82aNe3zzz93IUw7ptqZjdQUVBVC9evBBx/sgpLC83vvvWcHHHCA637yySebPiLPq+RAoWfevHk2ePBgF+RWrVplDRo0cMFUgbNixYquBviQQw6xww47LBB4vWAabnyF5LPOOsuuv/5627hxo918883u9wq+0Y6rUgzNWSFs9+7dLpxt2bLFnnnmGXdcMn322WftySefdMHzr7/+cgFPgU0XG6FNIVPBVcFSx6fAeMstt5guOBRC69ev79xPO+001/Wrr76y6667zoVSBWhduOhCQgazZs1ywVnr5a2vV8MbTeD9+++/7Y033nC75KVLl3b2GzZssKeeesq9t0pEFJqDSxqCA++vv/7qylR07qguW6Ff541+37lz50Dg/eWXX9zFyzHHHONCr77+3HPPuXNNu/4Kw48//rg7VxScdQ7JgoYAAggECxB4OR8QQCCsgAKvgsSRRx7pQpZ2ek8//fS9Aq8CjUJPcEB75JFHbOXKlfbEE0/kq6ud2dq1a9vEiRNdgPFa+/bt7YILLnD1npECrzeGao01VnBTMFV40q7w0UcfHfhS6Mf3oYFXu6gKYgrdXtP42h198cUXXeCNNK6CpHaEFcS1y6mm3eeGDRvalClTrHr16i7w6oY8BTev6QJj6dKlzju0yVOhT4HXa7feeqtp51U7o9pFVfhUGYqaXqeAPWzYsL3GysnJcRcSb7/9tlvjWHd4QweUmYK9LoDUIgXexx57zNWBK6B7TcFcAV5jqSkga4f69ttvD7zmhhtusHPPPdft9Gotpk+fbuPHj7dSpUrxLxkBBBDIU4DAy8mBAAJhBRR4FUpq1KjhPi5XiFXZwY8//pjrpjXtNGp39swzzwyMo6Co3UwFzfza6tWrXfnAN998YxkZGYGXKqhpt1G7hmr57fDmNYb6KZiqhOCTTz7JNY1IgVeBVKFRH8l7TQFRu8f6SD+acSdPnux2H1966aVc733ppZe6j+S1U6l5/P7777kCqXYzP/jgg8AucHBnBUrtqqq0w2t79uxxNdYy+/TTT90uqUoo9PG/dqi1DgrZ2pHVzrLmr51kfX3FihVubVUCEmvg1W7umDFjXGjV2Dt27HCBXqE1msB7xx13uKCt+XpN/XXRojKSSpUqBUoaVBLhta5du7pzUhccqsO+8847TbXTbdu2tauvvtrt8NIQQACBUAECL+cEAghEDLx6gYKGgqd2Xlu1ahV4SoNuTBo5cmSuwKtQpV3FSIFXu8Cq5wwNvKqjVSiLJvCqxKJZs2Z7jeEFXgU+7WIGt0iBVzvOusFKgTVcU+CNNK52HVU2EBp4L7nkEuvUqVMg8IY+Ciy/wKvaaK/2Nty8FH4VclWrqzIF7ZYq/CogKxBrN1lrdeihh5oC/AknnOB2raMJvAqXp5xySqCGV8FdpRM9e/a0/fff34VO7TJHG3g1N9X7Rgq8wTW/3nnoBV7PQOeRSkNUsqGLNAV8GgIIIBAsQODlfEAAgagCr2op9RGzdnMVVrzHkmlXTSUNXt2lBtNusG54Ui1ufk27giqTUMgLrvdVSYPqWFUzq5bfDq+CmPcUh9Ca4WiCqcZXgFIw9Z4CofCmoKWdYd1MFdqiGVdjqO43XEmDShh0k1e4JyPkF3j1OLWPP/7Y1ezm1TSmbubydoH79OnjXqqgrRIRXayoff/998443A7vb7/95p6moDX26qh1A6FuRNTFTPny5V3Y1U60dmnVtCuuOm4v8MpPu/6qIfZacA2vjkXje/XMeo36yky1ydqBDr3JLa/A642v8ggFfIVfGgIIIEDg5RxAAIGIAsElDd6LdePY888/734AhBd4Vb6gUOXdtPbFF1+4Wk6FXYVZ1ZDqRi/t1tapU2ev91VAUx8FaX2MrZ1V1apq3LJly0YMvHrBvffe657koF1X7V7qo3o97UEf8UfaiVV/1SgrEKoOWWFRNbd6YoDCrp7Rq4CnnWQFdIW4aAKvdlt105pqdb2b1rTrrQsH7f6qxRp4ddOabm5T3bQuCvQ0A+3a6oYu7dKq6cYt7cYrMOrCQ7uyagqSunFN77lp0yZnpoCpMpXQHV69XjvF6nPllVe60gHt5CocK/DqaQhaW+3oam21Q69zQEHZC7waXzeiacdVFqqxDQ6weoKFArTGlb1305rWQhdUapECry4qtFYyVi23bkJUGQo/mCTiP29egEDKCbDDm3JLzgEjEJ1AuMCrnroZSWE3+AdPzJgxw4XUNWvWuB0/BS6FGDXVeqrGVIFYTxEIbQqYCmYKunq0lHZb9VgrL6jp9ZGe0qDyBwVb1beqREA3cekmMwWiaAKvdnL1nnpygEJpixYtXChUcNJNWApTetyabp5S+UQ0gVfzVkAdMGCA25X1QqRqihWgCxJ41UfBXnPUrypbUFmCyhWOO+64AK1Co1yDS0pU66wb8RSIdVGggKqLEvmEC7y66U4BUhcsCpUqw9BNjLrg0VMQZOA9mUG71TpOvUb1t2oKsArEuvhQfa0eNRcaYJcsWeKM9asubrT7rNpeb3c6UuDVHGShG/l0s55KGRS0/f5gkuj+hfAqBBBIJgECbzKtFnNFAAEEEEAAAQQQiFmAwBszGR0QQAABBBBAAAEEkkmAwJtMq8VcEUAAAQQQQAABBGIWIPDGTEYHBBBAAAEEEEAAgWQSIPAm02oxVwQQQAABBBBAAIGYBQi8MZPRAQEEEEAAAQQQQCCZBAi8ybRazBUBBBBAAAEEEEAgZgECb8xkdEAAAQQQQAABBBBIJgECbzKtFnNFAAEEEEAAAQQQiFmAwBszGR0QQAABBBBAAAEEkkmAwJtMq8VcEUAAAQQQQAABBGIWIPDGTEYHBBBAAAEEEEAAgWQSIPAm02oxVwQQQAABBBBAAIGYBQi8MZPRAQEEEEAAAQQQQCCZBAi8ybRazBUBBBBAAAEEEEAgZgECb8xkdEAAAQQQQAABBBBIJgECbzKtFnNFAAEEEEAAAQQQiFmAwBszGR0QQAABBBBAAAEEkkmAwJtMq8VcEUAAAQQQQAABBGIWIPDGTEYHBBBAAAEEEEAAgWQSIPAm02oxVwQQQAABBBBAAIGYBQi8MZPRAQEEEEAAAQQQQCCZBAi8ybRazBUBBBBAAAEEEEAgZgECb8xkdEAAAQQQQAABBBBIJgECbzKtFnNFAAEEEEAAAQQQiFmAwBszGR0QQAABBBBAAAEEkkmAwJtMq8VcEUAAAQQQQAABBGIWIPDGTEYHBBBAAAEEEEAAgWQSIPAm02oxVwQQQAABBBBAAIGYBQi8MZPRAQEEEEAAAQQQQCCZBAi8ybRazBUBBBBAAAEEEEAgZoH/Aj0+18iH9wxwAAAAAElFTkSuQmCC" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.criterion_plot(\n", - " results,\n", - " # cut off after 180 evaluations\n", - " max_evaluations=180,\n", - " # show only the current best function value\n", - " monotone=True,\n", - ")\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "ef9e2e0b", - "metadata": {}, - "source": [ - "## Make a params plot" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "45e853a5", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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WZs7d6498sgjpl9kF110kd1333127LHHFmNtdAmTwPbt2+2pp55yXyddpUoVe/DBB933mz/wwAMuAOskpq+Obd++vT3xxBO2bNkye/jhhy0vL8/1eeaZZ1wAvummm9wvNr2mihYtgSlTptjixYvd1wcHgffmm2+2I444wm644QYXevXnq6++6i6YCztmoqVSuvemd+/e1qRJE/vTn/7kxjxoic4lnGeifcxo8uTkk0+2mTNnWr169Wz58uV2++2328svv8y55AANPYG3GLBXXXWVXX755dauXTvXW+9Q3Lhxow0ePLgYa6NLmAU+/PBDGzhwoJvtX7VqlY0cOdJ0olLTDM2JJ57oZnWefvpp++abb0zBR23NmjXueJk9e3aYd59tzyegCxuNsX5H6ASmwKvjoGXLlvbGG29YpUqVXA/dFbrgggusZs2ahR4zVatWxTcCAmvXrrVbbrnF3eHJ3xKdSzjPRGDwE+zCt99+6y52ly5d6u706S5Qt27dbMmSJZxLDtDQE3iLAdupUyebOnWqm7FRe/31193/T548uRhro0uYBaZPn24ffPCBu0U9Z84cN6M7ZsyY2C6df/75Nnz4cDezq9Bz7rnnup/98MMP7v/fe++9MO8+2x4noGB76aWXunDz6aefumNBgXfTpk3uLtA//vGP2NK6vV29enU321/YMdO0aVN8IyCgc4MujBVw1q1bZ0cddZS7dV27dm1LdC7hPBOBwS9iF3Te+OKLL9zvjYkTJ9p5551nZ555JueSAzT0BN5iwLZt29ZefPFFNzujtmLFClebqVvdtNIjoCCjX1Sa4dfFz4wZM9yJTbW5QbvkkkusT58+7rZV586drUuXLrGfqcZT36RTpkyZ0oMW4T3VBa9KnPr27etuSwaBV9+8p1var7zySmzvVQqjgKzQU9gx06ZNmwhrlZ5d08XN/PnzXe2/6vqffPJJW7hwoan0JdG5hPNM9I+R//znP+5ukOq669SpY+PGjXM1/pxLDszYE3iL4arg8uijj7q6G7XXXnvNhV39Ha10CGzbts0uu+wy9yBSUNqiiyDVbupBtaDpFpXqshR4mzVrZt27d3c/0myPAs37779fOsAivpeaudPDivo9oBrN+MC7efNmN3OjW5dB08xOrVq1XOAt7JjR8UILv4Ce71Cg6devn9sZ1frr7s7KlSvdLe3CziWcZ8I/9on24KuvvnLnA10I6eHnWbNm2aRJk9zsri6OOZekf/wJvMUwveaaa+zCCy+0jh07ut46SHVS05O3tOgL7Nixw6644gp3ZX766afHdlilDbqdHdTl/vTTT9a6dWs3m6NfZjpGgjpvPbikZfXwIy38AuPHj3cPJyrYqGnsFWzq16/v6rtbtWrljgM9ia129dVXu98hmtUp7JhRyQMt/AKq6Q/q+7U3ekuLavvffvttS3Qu4TwT/rFPtAf63a963bvvvju2mOr6dYdw7969nEsOwPATeIuBqiswPYAQvKVBV2mjR492JzVatAW+++47F1ZUyhBfnqC91i3q0047zYYNG+ZmffWWBj2wNm3aNNuwYYN7VZUeXgve0qCrepU70KInED/Dq70bMmSIm9HVLJ8udlTioGOjcuXKhR4z0VMpnXv09ddfuzHWTO4xxxzjLox0caw3uyQ6l3Ceifbxort7/fv3d3f/dHG7fv16d47Q745DDjmEc8kBGH4CbzFRdVWm0Kv6S8309erVq5hroluYBPTwmQJtMJMXbLtqrvSaMT2Rrbc26EGEBg0auHcs1q1b1y2mmT490KZ3Lnbo0ME96FahQoUw7T7bmqRA/sCrN3TouNCsnmZ59eq6oBQm0TGT5MexWJYL6MFmvcFFF8x6faXe464LILVE5xLOM1k+sJ6bp8kQPfisGd2KFSu6AKxzgxrnEk/cAroTeNNvyhoRQAABBBBAAAEEskiAwJtFg8GmIIAAAggggAACCKRfgMCbflPWiAACCCCAAAIIIJBFAgTeLBoMNgUBBBBAAAEEEEAg/QIE3vSbskYEEEAAAQQQQACBLBIg8GbRYLApCCCAAAIIIIAAAukXIPCm35Q1IoAAAggggAACCGSRAIE3iwaDTUEAAQQQQAABBBBIvwCBN/2mrBEBBBBAAAEEEEAgiwQIvFk0GGwKAggggAACCCCAQPoFCLzpN2WNCCCAAAIIIIAAAlkkQODNosFgUxBAAAEEEEAAAQTSL0DgTb8pa0QAAQQQQAABBBDIIgECbxYNBpuCAAIIIIAAAgggkH4BAm/6TVkjAggggAACCCCAQBYJEHizaDDYFAQQQAABBBBAAIH0CxB402/KGhFAAAEEEEAAAQSySIDAm0WDwaYggAACCCCAAAIIpF+AwJt+U9aIAAJpFli9erXdcsst9umnn1rXrl3tzjvvTPMnsLrRo0fb999/b3fccQcYCCCAQOQECLyRG1J2CIH0CHTo0MHq1q1rTz755D4rXLdunZ1//vn2zjvvpOeDkliLPq9z58525ZVXulBWvXr1JHoVvsiDDz5o3333nQ0aNMgtpD+17kaNGqV1vV4ry3DndAfeF154wb799lu79NJLY3vSs2dPu+yyy6xTp04Z3js+DgEESrsAgbe0HwHsPwKFCCjw7tixw4YNG2bnnHNObKmSCLzNmze3p59+2po0aZKW8VqxYoX98MMP1q5dO9u1a5cLYI8++qh34I1fb1o2NIMrSXfgveGGG6xly5b7BN7nnnvOWrdubUceeWQG94yPQgABBMwIvBwFCCBQoIAC7x//+Ed74IEH7NVXX43NqhYUeJ999lmbOHGibdy40c0KK+x06dIlKVkFznvuucdefPFFF7CbNm1qw4cPd+E2NzfXBg8ebKtWrbKqVatauXLl7O9///t+M7xax913321z5851s4oNGjSwadOm2dtvv23PP/+8XXDBBXb77be7Wd1//vOfFoS7W2+91c4991xbs2ZNbP0ql/jd735nmzZtMv38jTfesJo1a9pFF11kvXv3tjJlytjChQsTrjcoC9A69N9Lly61smXL2m9/+1u3zmCGWttRsWJF+/zzz23lypX2008/WZs2bdy26u8Laton/fzjjz+2evXq2U033eQC+yuvvGKjRo2yxYsXu20Mmj7zz3/+s51++ul233332csvv+zGqU6dOu7vg9nW+MC7YcMGO+WUU5zLQQcdFFvX0UcfbQsWLHCfu3XrVvd5b775pn3zzTd2zDHHuP//5S9/aUOHDnU+5cuXt4MPPtgZaxzPPvtsu/rqq+3MM89069Q+63M//PBDO/TQQ6179+7Wt29fZ6Wm5TUrPGvWLNM2ab969Ojh1qEmr7vuusteeukltw0K0v3797dTTz01qWOPhRBAoPQIEHhLz1izpwikJKDAO3nyZHvkkUdc6FEwUcsfeBWwBg4caPfff781a9bM3nrrLRfCNGOqmdmimoKqQqj+/PnPf+6CksLza6+9ZlWqVHHdf/3rX5tukRdWcqDQs2zZMhs5cqQLch999JGddNJJLpgqcNaqVcvVAB9++OGWk5MTC7xBMC1o/QrJ7du3tyuuuML++9//2rXXXuv+W8E32fWqFEPbrBC2e/du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" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.params_plot(results[\"scipy_neldermead\"])\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "61df05f0", - "metadata": {}, - "source": [ - "## Use advanced options of params plot" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "c09ded87", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAArwAAAH0CAYAAADfWf7fAAAgAElEQVR4Xuy9B3iUZdb//6X3EOMqoQqIEDpKDQEVUDqIL+ASWdTgSvvvQsRCXJcFFktwRcqroOy7BEUEFvhJF1BASgApSg1NerdQQugi/+vck3t4MpnJPJNnZjJ58n2uy0tI7vo5d8L3OXPuc/LduXPnDviQAAmQAAmQAAmQAAmQgE0J5KPgtalluS0SIAESIAESIAESIAFFgIKXB4EESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICCl2eABEiABEiABEiABEjA1gQoeG1tXm6OBEiABEiABEiABEiAgpdngARIgARIgARIgARIwNYEKHhtbV5ujgRIgARIgARIgARIgIKXZ4AESIAESIAESIAESMDWBCh4bW1ebo4ESIAESIAESIAESICC18IZeOihh3Dw4EELI7ArCZAACZAACZAACZBAoAlQ8FogTMFrAR67kgAJkAAJkAAJkECQCFDwWgBNwWsBHruSAAmQAAmQAAmQQJAIUPBaAE3BawEeu5IACZAACZAACZBAkAhQ8FoATcFrAR67kgAJkAAJkAAJkECQCFDwWgBNwWsBHruSAAmQAAmQAAmQQJAIUPBaAE3BawEeu5IACZAACZAACZBAkAhQ8FoATcFrAR67kgAJkAAJkAAJkECQCFDwWgBNwWsBHruSAAmQAAmQAAmQQJAIUPBaAE3BawEeu5IACZAACZAACZBAkAhQ8FoATcFrAR67kgAJkAAJkAAJkECQCFDwWgBNwWsBHruSAAmQAAmQAAmQQJAIUPBaAE3BawEeu5IACZAACZAACZBAkAhQ8FoATcFrAR67kgAJkAAJkAAJkECQCFDwWgBNwWsBHruSAAmQAAmQAAmQQJAIUPBaAG1F8G49t1XN3KhMIwsrYFcSIAESIAESIAESIAFvBCh4vRHK4vvZFbyn0k6h/bz2auQ5XeYgKiLKwirYlQRIgARIgARIgARIICsCFLwWzkd2Be/0lOl4b8t7aubxrcajTaU2FlbBriRAAiRAAiRAAiRAAhS8AToD2RW8PRb1wP7z+9WqBtYfiEENBgVohRyWBEiABEiABEiABEiAHl4LZyA7gtcYziBTt6rYChNbT7SwCnYlARIgARIgARIgARKgh9eHM7Bu3Tr07dsXGzZswH333Zdlz+wI3sTNiZixdwaq31MdBy4cQI2IGpjbZa4PK2RTEiABEiABEiABEiABXwjQw2uglZaWhueeew7Xr1/Hp59+GhDB225eO5xOO61id+NXx6vZdz2/yxebsS0JkAAJkAAJkAAJkIAPBCh4DbDeeOMNNG/eHFOmTMHUqVP9Lnj3nd+H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SgIkQAIkQAIkQAIkkF0IUPBml5XgPEiABEiABEiABEiABOJCgII3Llg5KAmQAAmQAAmQAAmQQHYhQMGbXVaC8yABEiABEiABEiABEogLAQreuGDloCRAAiRAAiRAAiRAAtmFAAVvdlkJzoMESIAESIAESIAESCAuBCh444KVg5IACZAACZAACZAACWQXAhS82WUlOA8SIIGgBNasWSODBw+Wbdu2Sfv27WXYsGGkFWMCw4cPl6NHj8rzzz8f45E5HAmQAAmceQIUvGd+DTgDEsiWBK688kqpUqWKfPjhhwHz++OPP6RTp06ycuXKLJs3znfNNddIjx49lCgrWbKkp3O//vrrcuTIERk0aJAaB//H2LVq1YrpuJ4Gy+LOsRa8X3zxhaSkpEi3bt38V3LXXXfJ3XffLa1atcriq+PpSIAEcjsBCt7cfgfw+kkgCAEI3sOHD8uQIUPk5ptv9h91JgRvw4YNZcqUKVKnTp2YrNeyZcvkxIkT0qJFCzl58qQSYO+++65nwWuOG5OJZuEgsRa8/fr1k0aNGgUI3s8++0wuu+wyqVq1ahZeGU9FAiRAAiIUvLwLSIAEHAlA8N5///0yZswYmTNnjj+q6iR4p06dKm+++abs2bNHRYUhdtq0aeOKLATnyy+/LDNmzFAC+6KLLpKnn35aidvNmzfLE088IatXr5bixYtLvnz55Ntvv80U4cUYL730ksycOVNFFWvUqCGTJk2SX375RaZNmya33nqrPPfccyqq+/PPP4sWd88884zccsstsn79ev/4sEtcd911snfvXsHnS5YskTJlykjnzp2lV69ekidPHpk/f37IcbUtAGPg34sXL5a8efPKVVddpcbUEWrMo1ChQrJr1y7573//K6mpqdKkSRM1V3zfqeGa8Pnvv/8u1apVk0ceeUQJ9tmzZ8uLL74oP/zwg5qjbjjn448/LjfccIO8+uqr8s0336h1qlixovq+jraagnfnzp1y9dVXKy758+f3j1WzZk357rvv1HkPHjyozrd06VJJTk6WunXrqq/PO+88eeqppxSfAgUKSEJCgmKMdbzpppvkvvvuk3bt2qkxcc0477p166REiRJy2223Sd++fRUrNByPqPDnn38umBOuq2vXrmoMNPAaMWKEfPXVV2oOENIPP/ywXHvtta7uPR5EAiSQewhQ8OaeteaVkkBEBCB4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IIjxUACBiocS8HESvNh0BwGJBxaIStgwsIkRDzzIggAGOjMDotW4ThwD/y0aBCwEMR4+4K9Fqjm7gF27dq1ijP/j4QbRZ3h7dXQ6nODFHMACG/mwWQ9WBghtr4VJ3P2E8CgSIIGcRICCNyetFudKAiRAAiRAAiRAAiQQMQEK3oiRsQMJkAAJkAAJkAAJkEBOIkDBm5NWi3MlARIgARIgARIgARKImAAFb8TI2IEESIAESIAESIAESCAnEaDgzUmrxbmSAAmQAAmQAAmQAAlETICCN2Jk7EACJEACJEACJEACJJCTCFDw5qTV4lxJgARIgARIgARIgAQiJkDBGzEydiABEiABEiABEiABEshJBCh4c9Jqca4kQAIkQAIkQAIkQAIRE6DgjRgZO5AACZAACZAACZAACeQkAhS8OWm1OFcSIAESIAESIAESIIGICVDwRoyMHUiABEiABEiABEiABHISAQrenLRanCsJkAAJkAAJkAAJkEDEBCh4I0bGDiRAAiRAAiRAAiRAAjmJAAVvTlotzpUESIAESIAESIAESCBiAhS8ESNjBxIgARIgARIgARIggZxEgII3J60W50oCJEACJEACJEACJBAxAQreiJGxAwmQAAmQAAmQAAmQQE4iQMGbk1aLcyUBEiABEiABEiABEoiYAAVvxMjYgQRIgARIgARIgARIICcRoODNSavFuZIACZAACZAACZAACURMgII3YmTsQAIkQAIkQAIkQAIkkJMIUPDmpNXiXEmABEiABEiABEiABCImQMEbMTJ2IAESIAESIAESIAESyEkEKHhz0mpxriRAAiRAAiRAAiRAAhEToOCNGBk7kAAJkAAJkAAJkAAJ5CQCFLw5abXqT6U2AAAAaklEQVQ4VxIgARIgARIgARIggYgJUPBGjIwdSIAESIAESIAESIAEchIBCt6ctFqcKwmQAAmQAAmQAAmQQMQEKHgjRsYOJEACJEACJEACJEACOYkABW9OWi3OlQRIgARIgARIgARIIGIC/w/HE88ua0co3AAAAABJRU5ErkJggg==" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.params_plot(\n", - " results[\"scipy_neldermead\"],\n", - " # cut off after 180 evaluations\n", - " max_evaluations=180,\n", - " # select only the last three parameters\n", - " selector=lambda x: x[2:],\n", - ")\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "markdown", - "id": "7b663015", - "metadata": {}, - "source": [ - "## criterion_plot with multistart optimization" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "70099614", - "metadata": {}, - "outputs": [], - "source": [ - "def alpine(x):\n", - " return np.sum(np.abs(x * np.sin(x) + 0.1 * x))\n", - "\n", - "\n", - "res = em.minimize(\n", - " sphere,\n", - " params=np.arange(10),\n", - " soft_lower_bounds=np.full(10, -3),\n", - " soft_upper_bounds=np.full(10, 10),\n", - " algorithm=\"scipy_neldermead\",\n", - " multistart=True,\n", - " multistart_options={\"n_samples\": 1000, \"convergence.max_discoveries\": 10},\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "e21dcd65", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAArwAAAH0CAYAAADfWf7fAAAgAElEQVR4XuzdC3xU1b33/98kkzsh4ZIAQQKCEu6gRkEE44X0HNCK1VZbHquv2lZ7+vL0otY+qP1bTlufempbTttTTz2tTy/e+lR6QBQtqBBE0JLKLRC5iYQ74ZaQ+23+r9+a7GHPZHLdk8nM5LNfrxaTzNp77ffa6JfF2r/l8ng8HuFAAAEEEEAAAQQQQCBGBVwE3hgdWW4LAQQQQAABBBBAwAgQeHkQEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJagMAb08PLzSGAAAIIIIAAAggQeHkGEEAAAQQQQAABBGJa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4D+NYoITzd2rW7K9pXCDFb34MLV8p444eyYBErASoOD1th4oeEVk6tSpsn37dvXbRVm6dKmK4Llz58akS5cGb4uPrUmABEiABEiABEigJghQ8IrIli1bZOjQoTJjxoxwloZOnTrJ8OHDKXhrYhXyHiRAAiRAAiRAAiSQQgIUvJVw582bJxMnTpSSkhLp27evTJgwQXLjBADQwpvClcmuSYAESIAESIAESCBJBCh4PYCk4PUAj01JgARIgARIgARIoIYIUPB6AE3B6wEem5IACZAACZAACZBADRGg4PUAmoLXAzw2JQESIAESIAESIIEaIkDB6wE0Ba8HeGxKAiRAAiRAAiRAAjVEgILXA2gKXg/w2JQESIAESIAESIAEaogABa8H0BS8HuCxKQmQAAmQAAmQAAnUEAEKXg+gKXg9wGNTEiABEiABEiABEqghAhS8HkBT8HqAx6YkQAIkQAIkQAIkUEMEKHg9gKbg9QCPTUmABEiABEiABEighghQ8HoATcHrAR6bkgAJkAAJkAAJkEANEaDg9QCagtcDPDYlARIgARIgARIggRoiQMHrATQFrwd4bEoCJEACJEACJEACNUSAgtcDaAheFhIgARJwQ6B3796ycOFCN01YlwRIgARk7dq1pOCBAAWvB3jTp0+XYDAow4YN89ALm8Yj8OKLL0pZWZlcffXV8aryugcCr7zyiuzevVtuuOEGD72waTwCc+bMkc2bN8uIESPiVeV1DwRef/11WblypYwcOdJDL2waj8C7774rixYtktGjR8eryuskcEgJUPB6wE/B6wGei6YUvC5geahKwesBnoumFLwuYHmoSsHrAZ6LphS8LmCx6iElQMHrAT8Frwd4LppS8LqA5aEqBa8HeC6aUvC6gOWhKgWvB3gumlLwuoDFqoeUAAWvB/wUvB7guWhKwesCloeqFLwe4LloSsHrApaHqhS8HuC5aErB6wIWqx5SAhS8HvBT8HqA56IpBa8LWB6qUvB6gOeiKQWvC1geqlLweoDnoikFrwtYrHpICVDwHlL8vDkJkAAJkAAJkAAJkECqCVDwppow+ycBEiABEiABEiABEjikBCh4Dyl+3pwESIAESIAESIAESCDVBCh4U02Y/ZMACZAACZAACZAACRxSAhS8hxQ/b04CJEACJEACJEACJJBqAhS8CRAOBALy0EMPybx58yQn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AiRAAiSQ0QQoeDN6evlwJEACJEACJEACJEACFLxcAyRAAiRAAiRAAiRAAhlNgII3o6eXD0cCJEACJEACJEACJEDByzVAAiRw2BNYunSpjB07VjZt2iQ/+9nP5KGHHjrsx5xuA3z44YeluLhYHnjggXQbOsdLAiRAAnEJUPDGRcQKJFA7CfTt21eOPvpo+fvf/14FwPr16+Xiiy+WL774osbA4H79+/eXa665RkVZkyZNPN37iSeekKKiIrn77ru1H/xE3506dUpqv546q+HGyRa8r776qhQWFsovf/nL8JMMGzZMfvWrX8k555xTw0/H25EACdR2AhS8tX0F8PlJIAoBCN79+/fLvffeK7/4xS/CtQ6F4D355JNlxowZcsIJJyRlvhYtWiSlpaXSp08fKSsrUwH27LPPeha81n6TMtAa7CTZgveWW26RHj16VBG8//znP6VXr17Stm3bGnwy3ooESIAERCh4uQpIgARsCUDw/vrXv5Y///nP8uabb4atqnaC95VXXpG//e1vsm3bNrUKQ+wMGjTIEVkIzkcffVRee+01Fdhdu3aV++67T8Xt2rVrZfTo0bJkyRJp2LChZGdny9tvv13Nwos+HnnkEZk7d65aFTt06CDTp0+XxYsXy6xZs+SSSy6R8ePHq1X3f//7nxhx97vf/U4GDx4sq1atCvcPd4lzzz1XvvvuO8H1jz76SJo3by6XXXaZ3HjjjeLz+eS9996L2a9xC0Af+POCBQskKytL+vXrp30aCzXGUa9ePdm6dat8/vnnUlFRIb1799ax4vd2Bc+E6+vWrZN27drJyJEjVbC/8cYbMmHCBJk/f76O0RTc86677pKBAwfKY489Jq+//rrOU5s2bfT3xtpqFbxbtmyRs846S7nUqVMn3FfHjh3lnXfe0fvu3r1b77dw4UIpKCiQLl266N+PPfZYueeee5RPTk6O1K1bVxljHn/+85/LddddJ+eff772iWfGfVeuXCmNGzeWIUOGyM0336ysUFAfVuF//etfgjHhua644grtAwW8fv/738u///1vHQOE9O233y4DBgxwtPZYiQRIoPYQoOCtPXPNJyUBVwQgeJ955hmZMmWKih4IE5RIwQuBdeedd8rjjz8u3bp1k08//VRFGCymsMzGKxCqEKH4+YMf/ECFEsTzu+++Kw0aNNDmP/zhDwWfyKO5HED0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2TJljJ/Y3MD6DN9eY52OJ3gxBrBAIB+C9eDKAKHt9WASZ/9CWIsESCCdCFDwptNscawkQAIkQAIkQAIkQAKuCVDwukbGBiRAAiRAAiRAAiRAAulEgII3nWaLYyUBEiABEiABEiABEnBNgILXNTI2IAESIAESIAESIAESSCcCFLzpNFscKwmQAAmQAAmQAAmQgGsCFLyukbEBCZAACZAACZAACZBAOhGg4E2n2eJYSYAESIAESIAESIAEXBOg4HWNjA1IgARIgARIgARIgATSiQAFbzrNFsdKAiRAAiRAAiRAAiTgmgAFr2tkbEACJEACJEACJEACJJBOBCh402m2OFYSIAESIAESIAESIAHXBCh4XSNjAxIgARIgARIgARIggXQiQMGbTrPFsZIACZAACZAACZAACbgmQMHrGhkbkAAJkAAJkAAJkAAJpBMBCt50mi2OlQRIgARIgARIgARIwDUBCl7XyNiABEiABEiABEiABEggnQhQ8KbTbHGsJEACJEACJEACJEACrglQ8LpGxgYkQAIkQAIkQAIkQALpRICCN51mi2MlARIgARIgARIgARJwTYCC1zUyNiABEiABEiABEiABEkgnAhS86TRbHCsJkAAJkAAJkAAJkIBrAhS8rpGxAQmQAAmQAAmQAAmQQDoRoOBNp9niWEmABEiABEiABEiABFwToOB1jYwNSIAESIAESIAESIAE0okABW86zRbHSgIkQAIkQAIkQAIk4JoABa9rZGxAAiRAAiRAAiRAAiSQTgQoeNNptjhWEiABEiABEiABEiAB1wQoeF0jYwMSIAESIAESIAESIIF0IkDBm06zxbGSAAmQAAmQAAmQAAm4JkDB6xoZG5AACZAACZAACZAACaQTAQredJotjpUESIAESIAESIAESMA1gf8D+frUuAW9h2gAAAAASUVORK5CYII=" - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "fig = em.criterion_plot(res, max_evaluations=3000)\n", - "fig.show(renderer=\"png\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "cf0d7376", - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.8" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/source/how_to_guides/optimization/index.md b/docs/source/how_to_guides/optimization/index.md deleted file mode 100644 index 424d2da10..000000000 --- a/docs/source/how_to_guides/optimization/index.md +++ /dev/null @@ -1,22 +0,0 @@ -# Optimization - -```{toctree} ---- -maxdepth: 1 ---- -scipy_tutorial_2022 -how_to_specify_the_criterion_function -how_to_specify_parameters -how_to_specify_algorithm_and_algo_options -how_to_specify_bounds -how_to_specify_constraints -how_to_use_logging -how_to_use_the_dashboard -how_to_handle_errors_during_optimization -how_to_scale_optimization_problems -how_to_do_multistart_optimizations -how_to_benchmark_optimization_algorithms -how_to_visualize_histories -how_to_visualize_an_optimization_problem -how_to_pick_an_optimizer -``` diff --git a/docs/source/how_to_guides/optimization/robinson-crusoe-covariance.csv b/docs/source/how_to_guides/optimization/robinson-crusoe-covariance.csv deleted file mode 100644 index 12465f9a1..000000000 --- a/docs/source/how_to_guides/optimization/robinson-crusoe-covariance.csv +++ /dev/null @@ -1,18 +0,0 @@ - -category,name,value -delta,delta,0.95 -wage_fishing,exp_fishing,0.1 -wage_fishing,contemplation_with_friday,0.4 -nonpec_fishing,constant,-1 -nonpec_friday,constant,-1 -nonpec_friday,not_fishing_last_period,-1 -nonpec_hammock,constant,2.5 -nonpec_hammock,not_fishing_last_period,-1 -shocks_cov, var_fishing,1 -shocks_cov,cov_friday_fishing,0 -shocks_cov,var_friday,1 -shocks_cov,cov_hammock_fishing,-0.2 -shocks_cov,cov_hammock_friday,0 -shocks_cov,var_hammock,1 -lagged_choice_1_hammock,constant,1 -meas_error,sd_fishing,1e-6 diff --git a/docs/source/how_to_guides/optimization/robinson-crusoe-sdcorr.csv b/docs/source/how_to_guides/optimization/robinson-crusoe-sdcorr.csv deleted file mode 100644 index 0f8221be6..000000000 --- a/docs/source/how_to_guides/optimization/robinson-crusoe-sdcorr.csv +++ /dev/null @@ -1,17 +0,0 @@ -category,name,value -delta,delta,0.95 -wage_fishing,exp_fishing,0.1 -wage_fishing,contemplation_with_friday,0.4 -nonpec_fishing,constant,-1.0 -nonpec_friday,constant,-1.0 -nonpec_friday,not_fishing_last_period,-1.0 -nonpec_hammock,constant,2.5 -nonpec_hammock,not_fishing_last_period,-1.0 -shocks_sdcorr,sd_fishing,1.0 -shocks_sdcorr,sd_friday,1.0 -shocks_sdcorr,sd_hammock,1.0 -shocks_sdcorr,corr_friday_fishing,0.0 -shocks_sdcorr,corr_hammock_fishing,-0.2 -shocks_sdcorr,corr_hammock_friday,0.0 -lagged_choice_1_hammock,constant,1.0 -meas_error,sd_fishing,1e-06 diff --git a/docs/source/how_to_guides/optimization/scipy_tutorial_2022.md b/docs/source/how_to_guides/optimization/scipy_tutorial_2022.md deleted file mode 100644 index 3e99040d0..000000000 --- a/docs/source/how_to_guides/optimization/scipy_tutorial_2022.md +++ /dev/null @@ -1,7 +0,0 @@ -(estimagic_scipy2022)= - -# estimagic tutorial at SciPy2022 conference - -
- IMAGE ALT TEXT -
diff --git a/docs/source/index.md b/docs/source/index.md index 6ad7d0a39..20b5a20d5 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,23 +1,28 @@ +# +
```{raw} html - + - + ```

-`estimagic` is a Python package for nonlinear optimization with or without constraints. -It is particularly suited to solve difficult nonlinear estimation problems. On top, it -provides functionality to perform statistical inference on estimated parameters. +*optimagic* is a Python package for numerical optimization. It is a unified interface to +optimizers from SciPy, NlOpt and many other Python packages. -For a complete introduction to optimization in estimagic, check out the -{ref}`estimagic_scipy2022` +*optimagic*'s `minimize` function works just like SciPy's, so you don't have to adjust +your code. You simply get more optimizers for free. On top you get powerful diagnostic +tools, parallel numerical derivatives and more. If you want to see what *optimagic* can +do, check out this [tutorial](tutorials/optimization_overview.ipynb) -If you want to learn more about estimagic, dive into one of the following topics +*optimagic* was formerly called *estimagic*, because it also provides functionality to +perform statistical inference on estimated parameters. *estimagic* is now a subpackage +of *optimagic*, which is documented [here](estimagic). `````{grid} 1 2 2 2 --- @@ -29,16 +34,16 @@ gutter: 3 :class-img-top: index-card-image :shadow: md -```{button-link} getting_started/index.html +```{button-link} tutorials/index.html --- click-parent: ref-type: ref class: stretched-link index-card-link sd-text-primary --- -Getting Started +Tutorials ``` -New users of estimagic should read this first. +New users of optimagic should read this first. ```` @@ -48,7 +53,7 @@ New users of estimagic should read this first. :class-img-top: index-card-image :shadow: md -```{button-link} how_to_guides/index.html +```{button-link} how_to/index.html --- click-parent: ref-type: ref @@ -67,7 +72,7 @@ Detailed instructions for specific and advanced tasks. :class-img-top: index-card-image :shadow: md -```{button-link} getting_started/installation.html +```{button-link} installation.html --- click-parent: ref-type: ref @@ -76,7 +81,7 @@ class: stretched-link index-card-link sd-text-primary Installation ``` -Installation instructions for estimagic and optional dependencies. +Installation instructions for optimagic and optional dependencies. ```` @@ -106,7 +111,7 @@ List of numerical optimizers and their optional parameters. :class-img-top: index-card-image :shadow: md -```{button-link} explanations/index.html +```{button-link} explanation/index.html --- click-parent: ref-type: ref @@ -125,7 +130,7 @@ Background information on key topics central to the package. :class-img-top: index-card-image :shadow: md -```{button-link} reference_guides/index.html +```{button-link} reference/index.html --- click-parent: ref-type: ref @@ -134,7 +139,7 @@ class: stretched-link index-card-link sd-text-primary API Reference ``` -Detailed description of the estimagic API. +Detailed description of the optimagic API. ```` @@ -154,7 +159,7 @@ class: stretched-link index-card-link sd-text-primary Videos ``` -Collection of tutorials, talks, and screencasts on estimagic. +Collection of tutorials, talks, and screencasts on optimagic. ```` @@ -165,47 +170,51 @@ Collection of tutorials, talks, and screencasts on estimagic. hidden: true maxdepth: 1 --- -getting_started/index -how_to_guides/index -explanations/index -reference_guides/index +tutorials/index +how_to/index +explanation/index +reference/index development/index videos algorithms +estimagic/index +installation ``` -## Highlights +______________________________________________________________________ -### Optimization +We thank all institutions that have funded or supported optimagic (formerly estimagic) -- estimagic wraps algorithms from *scipy.optimize*, *nlopt*, *pygmo* and more. See - {ref}`list_of_algorithms` -- estimagic implements constraints efficiently via reparametrization, so you can solve - constrained problems with any optimzer that supports bounds. See {ref}`constraints` -- The parameters of an optimization problem can be arbitrary pytrees. See {ref}`params`. -- The complete history of parameters and function evaluations can be saved in a database - for maximum reproducibility. See [How to use logging] -- Painless and efficient multistart optimization. See [How to do multistart] -- The progress of the optimization is displayed in real time via an interactive - dashboard. See {ref}`dashboard`. +```{image} _static/images/aai-institute-logo.svg +--- +width: 185px +--- +``` -### Estimation and Inference +```{image} _static/images/numfocus_logo.png +--- +width: 200 +--- +``` + +```{image} _static/images/tra_logo.png +--- +width: 240px +--- +``` -- You can estimate a model using method of simulated moments (MSM), calculate standard - errors and do sensitivity analysis with just one function call. See [MSM Tutorial] -- Asymptotic standard errors for maximum likelihood estimation. -- estimagic also provides bootstrap confidence intervals and standard errors. Of course - the bootstrap procedures are parallelized. +```{image} _static/images/hoover_logo.png +--- +width: 192px +--- +``` -### Numerical differentiation +```{image} _static/images/transferlab-logo.svg +--- +width: 420px +--- +``` -- estimagic can calculate precise numerical derivatives using - [Richardson extrapolations](https://en.wikipedia.org/wiki/Richardson_extrapolation). -- Function evaluations needed for numerical derivatives can be done in parallel with - pre-implemented or user provided batch evaluators. +______________________________________________________________________ **Useful links for search:** {ref}`genindex` | {ref}`modindex` | {ref}`search` - -[how to do multistart]: how_to_guides/optimization/how_to_do_multistart_optimizations -[how to use logging]: how_to_guides/optimization/how_to_use_logging -[msm tutorial]: getting_started/estimation/first_msm_estimation_with_estimagic diff --git a/docs/source/installation.md b/docs/source/installation.md new file mode 100644 index 000000000..2df5bdab1 --- /dev/null +++ b/docs/source/installation.md @@ -0,0 +1,63 @@ +# Installation + +## Basic installation + +The preferred way to install optimagic is via `conda` or `mamba`. To do so, open a +terminal and type: + +``` +conda install -c conda-forge optimagic +``` + +Alternatively, you can install optimagic via pip: + +``` +pip install estimagic +``` + +In both cases, you get optimagic and all of its mandatory dependencies. + +## Installing optional dependencies + +Only `scipy` is a mandatory dependency of optimagic. Other algorithms become available +if you install more packages. We make this optional because you will rarely need all of +them in the same project. + +For an overview of all optimizers and the packages you need to install to enable them, +see {ref}`list_of_algorithms`. + +To enable all algorithms at once, do the following: + +``` +conda -c conda-forge install nlopt +``` + +``` +pip install Py-BOBYQA +``` + +``` +pip install DFO-LS +``` + +``` +conda install -c conda-forge petsc4py +``` + +*Note*: `` `petsc4py` `` is not available on Windows. + +``` +conda install -c conda-forge cyipopt +``` + +*Note*: Make sure you have at least `cyipopt` 1.4. + +``` +conda install -c conda-forge pygmo +``` + +``` +pip install fides>=0.7.4 +``` + +*Note*: Make sure you have at least `fides` 0.7.4. diff --git a/docs/source/reference_guides/algo_options.md b/docs/source/reference/algo_options.md similarity index 61% rename from docs/source/reference_guides/algo_options.md rename to docs/source/reference/algo_options.md index aa6cbc32d..367644521 100644 --- a/docs/source/reference_guides/algo_options.md +++ b/docs/source/reference/algo_options.md @@ -3,6 +3,6 @@ # The default algorithm options ```{eval-rst} -.. automodule:: estimagic.optimization.algo_options +.. automodule:: optimagic.optimization.algo_options :members: ``` diff --git a/docs/source/reference_guides/batch_evaluators.md b/docs/source/reference/batch_evaluators.md similarity index 62% rename from docs/source/reference_guides/batch_evaluators.md rename to docs/source/reference/batch_evaluators.md index dc27fd31c..845f056de 100644 --- a/docs/source/reference_guides/batch_evaluators.md +++ b/docs/source/reference/batch_evaluators.md @@ -3,6 +3,6 @@ # Batch evaluators ```{eval-rst} -.. automodule:: estimagic.batch_evaluators +.. automodule:: optimagic.batch_evaluators :members: ``` diff --git a/docs/source/reference_guides/index.md b/docs/source/reference/index.md similarity index 62% rename from docs/source/reference_guides/index.md rename to docs/source/reference/index.md index af2547a25..3ee07cee1 100644 --- a/docs/source/reference_guides/index.md +++ b/docs/source/reference/index.md @@ -1,7 +1,7 @@ -# API +# optimagic API ```{eval-rst} -.. currentmodule:: estimagic +.. currentmodule:: optimagic ``` (maximize-and-minimize)= @@ -43,20 +43,6 @@ ``` -```{eval-rst} -.. dropdown:: count_free_params - - .. autofunction:: count_free_params - -``` - -```{eval-rst} -.. dropdown:: check_constraints - - .. autofunction:: check_constraints - -``` - ```{eval-rst} .. dropdown:: OptimizeResult @@ -65,119 +51,118 @@ ``` -(first_derivative)= - -## Derivatives - -```{eval-rst} -.. dropdown:: first_derivative - - .. autofunction:: first_derivative - -``` - ```{eval-rst} -.. dropdown:: second_derivative +.. dropdown:: Bounds - .. autofunction:: second_derivative + .. autoclass:: Bounds + :members: ``` ```{eval-rst} -.. dropdown:: derivative_plot +.. dropdown:: Constraints - .. autofunction:: derivative_plot + .. autoclass:: FixedConstraint + :members: + .. autoclass:: IncreasingConstraint + :members: -``` + .. autoclass:: DecreasingConstraint + :members: -(estimation)= + .. autoclass:: EqualityConstraint + :members: -## Estimation + .. autoclass:: ProbabilityConstraint + :members: -```{eval-rst} -.. dropdown:: estimate_ml + .. autoclass:: PairwiseEqualityConstraint + :members: - .. autofunction:: estimate_ml + .. autoclass:: FlatCovConstraint + :members: -``` + .. autoclass:: FlatSDCorrConstraint + :members: -```{eval-rst} -.. dropdown:: estimate_msm + .. autoclass:: LinearConstraint + :members: - .. autofunction:: estimate_msm + .. autoclass:: NonlinearConstraint + :members: ``` ```{eval-rst} -.. dropdown:: get_moments_cov +.. dropdown:: NumdiffOptions - .. autofunction:: get_moments_cov + .. autoclass:: NumdiffOptions + :members: ``` ```{eval-rst} -.. dropdown:: lollipop_plot +.. dropdown:: MultistartOptions - .. autofunction:: lollipop_plot + .. autoclass:: MultistartOptions + :members: ``` ```{eval-rst} -.. dropdown:: estimation_table +.. dropdown:: ScalingOptions - .. autofunction:: estimation_table + .. autoclass:: ScalingOptions + :members: ``` ```{eval-rst} -.. dropdown:: render_html +.. dropdown:: LogOptions - .. autofunction:: render_html + .. autoclass:: SQLiteLogOptions + :members: ``` ```{eval-rst} -.. dropdown:: render_latex +.. dropdown:: History - .. autofunction:: render_latex + .. autoclass:: History + :members: ``` ```{eval-rst} -.. dropdown:: LikelihoodResult +.. dropdown:: count_free_params - .. autoclass:: LikelihoodResult - :members: + .. autofunction:: count_free_params ``` ```{eval-rst} -.. dropdown:: MomentsResult - - .. autoclass:: MomentsResult - :members: - +.. dropdown:: check_constraints + .. autofunction:: check_constraints ``` -(bootstrap)= +(first_derivative)= -## Bootstrap +## Derivatives ```{eval-rst} -.. dropdown:: bootstrap +.. dropdown:: first_derivative + + .. autofunction:: first_derivative - .. autofunction:: bootstrap ``` ```{eval-rst} -.. dropdown:: BootstrapResult - - .. autoclass:: BootstrapResult - :members: +.. dropdown:: second_derivative + .. autofunction:: second_derivative ``` diff --git a/docs/source/reference_guides/utilities.md b/docs/source/reference/utilities.md similarity index 65% rename from docs/source/reference_guides/utilities.md rename to docs/source/reference/utilities.md index 8d19e47b8..842691bac 100644 --- a/docs/source/reference_guides/utilities.md +++ b/docs/source/reference/utilities.md @@ -3,6 +3,6 @@ # Utility functions ```{eval-rst} -.. automodule:: estimagic.utilities +.. automodule:: optimagic.utilities :members: ``` diff --git a/docs/source/tutorials/index.md b/docs/source/tutorials/index.md new file mode 100644 index 000000000..18c7760dd --- /dev/null +++ b/docs/source/tutorials/index.md @@ -0,0 +1,60 @@ +(tutorials)= + +# Tutorials + +This section provides an overview of optimagic. It's a good starting point if you are +new to optimagic. For more in-depth examples using advanced options, check out the +[how-to guides](how-to). + +`````{grid} 1 2 2 2 +--- +gutter: 3 +--- +````{grid-item-card} +:text-align: center +:img-top: ../_static/images/optimization.svg +:class-img-top: index-card-image +:shadow: md + +```{button-link} optimization_overview.html +--- +click-parent: +ref-type: ref +class: stretched-link index-card-link sd-text-primary +--- +Optimization +``` + +Learn numerical optimization with estimagic. + +```` + +````{grid-item-card} +:text-align: center +:img-top: ../_static/images/differentiation.svg +:class-img-top: index-card-image +:shadow: md + +```{button-link} numdiff_overview.html +--- +click-parent: +ref-type: ref +class: stretched-link index-card-link sd-text-primary +--- +Differentiation +``` + +Learn numerical differentiation with estimagic. + +```` + +````` + +```{toctree} +--- +hidden: true +maxdepth: 1 +--- +optimization_overview +numdiff_overview +``` diff --git a/docs/source/tutorials/numdiff_overview.ipynb b/docs/source/tutorials/numdiff_overview.ipynb new file mode 100644 index 000000000..5068523a7 --- /dev/null +++ b/docs/source/tutorials/numdiff_overview.ipynb @@ -0,0 +1,330 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Numerical differentiation\n", + "\n", + "In this tutorial, you will learn how to numerically differentiate functions with\n", + "optimagic." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om\n", + "import pandas as pd" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Basic usage of `first_derivative`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def fun(params):\n", + " return params @ params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fd = om.first_derivative(\n", + " func=fun,\n", + " params=np.arange(5),\n", + ")\n", + "\n", + "fd.derivative" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Basic usage of `second_derivative`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sd = om.second_derivative(\n", + " func=fun,\n", + " params=np.arange(5),\n", + ")\n", + "\n", + "sd.derivative.round(3)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## You can parallelize" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fd = om.first_derivative(\n", + " func=fun,\n", + " params=np.arange(5),\n", + " n_cores=4,\n", + ")\n", + "\n", + "fd.derivative" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sd = om.second_derivative(\n", + " func=fun,\n", + " params=np.arange(5),\n", + " n_cores=4,\n", + ")\n", + "\n", + "sd.derivative.round(3)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## `params` do not have to be vectors\n", + "\n", + "In optimagic, params can be arbitrary [pytrees](https://jax.readthedocs.io/en/latest/pytrees.html). Examples are (nested) dictionaries of numbers, arrays and pandas objects. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def dict_fun(params):\n", + " return params[\"a\"] ** 2 + params[\"b\"] ** 2 + (params[\"c\"] ** 2).sum()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fd = om.first_derivative(\n", + " func=dict_fun,\n", + " params={\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])},\n", + ")\n", + "\n", + "fd.derivative" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Description of the output\n", + "\n", + "> Note. Understanding the output of the first and second derivative requires terminolgy\n", + "> of pytrees. Please refer to the\n", + "> [JAX documentation of pytrees](https://jax.readthedocs.io/en/latest/pytrees.html).\n", + "\n", + "The output tree of `first_derivative` has the same structure as the params tree.\n", + "Equivalent to the 1-d numpy array case, where the gradient is a vector of shape\n", + "`(len(params),)`. If, however, the params tree contains non-scalar entries like\n", + "`numpy.ndarray`'s, `pandas.Series`', or `pandas.DataFrame`'s, the output is not expanded\n", + "but a block is created instead. In the above example, the entry `params[\"c\"]` is a\n", + "`pandas.Series` with 3 entries. Thus, the first derivative output contains the\n", + "corresponding 3x1-block of the gradient at the position `[\"c\"]`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fd.derivative[\"c\"]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sd = om.second_derivative(\n", + " func=dict_fun,\n", + " params={\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])},\n", + ")\n", + "\n", + "sd.derivative" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Description of the output\n", + "\n", + "> Note. Understanding the output of the first and second derivative requires terminolgy\n", + "> of pytrees. Please refer to the\n", + "> [JAX documentation of pytrees](https://jax.readthedocs.io/en/latest/pytrees.html).\n", + "\n", + "The output of `second_derivative` when using a general pytrees looks more complex but\n", + "is easy once we remember that the second derivative is equivalent to applying the first\n", + "derivative twice.\n", + "\n", + "The output tree is a product of the params tree with itself. This is equivalent to the\n", + "1-d numpy array case, where the hessian is a matrix of shape\n", + "`(len(params), len(params))`. If, however, the params tree contains non-scalar entries\n", + "like `numpy.ndarray`'s, `pandas.Series`', or `pandas.DataFrame`'s, the output is not\n", + "expanded but a block is created instead. In the above example, the entry `params[\"c\"]`\n", + "is a 3-dimensional `pandas.Series`. Thus, the second derivative output contains the\n", + "corresponding 3x3-block of the hessian at the position `[\"c\"][\"c\"]`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sd.derivative[\"c\"][\"c\"].round(3)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## There are many options\n", + "\n", + "You can choose which finite difference method to use, whether we should respect\n", + "parameter bounds, or whether to evaluate the function in parallel. Let's go through\n", + "some basic examples. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## You can choose the difference method\n", + "\n", + "> Note. A mathematical explanation of the background of the difference methods can be\n", + "> found on the corresponding [explanation page](../explanation/numdiff_background.md)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fd = om.first_derivative(\n", + " func=fun,\n", + " params=np.arange(5),\n", + " method=\"backward\", # default: 'central'\n", + ")\n", + "\n", + "fd.derivative" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "sd = om.second_derivative(\n", + " func=fun,\n", + " params=np.arange(5),\n", + " method=\"forward\", # default: 'central_cross'\n", + ")\n", + "\n", + "sd.derivative.round(3)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## You can add bounds " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "params = np.arange(5)\n", + "\n", + "fd = om.first_derivative(\n", + " func=fun,\n", + " params=params,\n", + " # forces first_derivative to use forward differences\n", + " bounds=om.Bounds(lower=params, upper=params + 1),\n", + ")\n", + "\n", + "fd.derivative" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Of course, bounds also work in `second_derivative`." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + }, + "vscode": { + "interpreter": { + "hash": "40d3a090f54c6569ab1632332b64b2c03c39dcf918b08424e98f38b5ae0af88f" + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/source/tutorials/optimization_overview.ipynb b/docs/source/tutorials/optimization_overview.ipynb new file mode 100644 index 000000000..31e6b46b4 --- /dev/null +++ b/docs/source/tutorials/optimization_overview.ipynb @@ -0,0 +1,534 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Numerical optimization\n", + "\n", + "Using simple examples, this tutorial shows how to do an optimization with optimagic. More details on the topics covered here can be found in the [how to guides](../how_to/index.md)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import optimagic as om\n", + "import pandas as pd" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Basic usage of `minimize`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere(params):\n", + " return params @ params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + ")\n", + "\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## `params` do not have to be vectors\n", + "\n", + "In optimagic, params can by arbitrary [pytrees](https://jax.readthedocs.io/en/latest/pytrees.html). Examples are (nested) dictionaries of numbers, arrays and pandas objects. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def dict_sphere(params):\n", + " return params[\"a\"] ** 2 + params[\"b\"] ** 2 + (params[\"c\"] ** 2).sum()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=dict_sphere,\n", + " params={\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])},\n", + " algorithm=\"scipy_powell\",\n", + ")\n", + "\n", + "res.params" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## The result contains all you need to know" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=dict_sphere,\n", + " params={\"a\": 0, \"b\": 1, \"c\": pd.Series([2, 3, 4])},\n", + " algorithm=\"scipy_neldermead\",\n", + ")\n", + "res" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## You can visualize the convergence" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.criterion_plot(res, max_evaluations=300)\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.params_plot(\n", + " res,\n", + " max_evaluations=300,\n", + " # optionally select a subset of parameters to plot\n", + " selector=lambda params: params[\"c\"],\n", + ")\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## There are many optimizers\n", + "\n", + "If you install some optional dependencies, you can choose from a large (and growing) set of optimization algorithms -- all with the same interface!\n", + "\n", + "For example, we wrap optimizers from `scipy.optimize`, `nlopt`, `cyipopt`, `pygmo`, `fides`, `tao` and others. \n", + "\n", + "We also have some optimizers that are not part of other packages. Examples are a `parallel Nelder-Mead` algorithm, The `BHHH` algorithm and a `parallel Pounders` algorithm.\n", + "\n", + "See the full list [here](../how_to_guides/optimization/how_to_specify_algorithm_and_algo_options" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## You can add bounds" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "bounds = om.Bounds(lower=np.arange(5) - 2, upper=np.array([10, 10, 10, np.inf, np.inf]))\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " bounds=bounds,\n", + ")\n", + "\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## You can fix parameters " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " constraints=om.FixedConstraint(selector=lambda params: params[[1, 3]]),\n", + ")\n", + "\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Or impose other constraints\n", + "\n", + "As an example, let's impose the constraint that the first three parameters are valid probabilities, i.e. they are between zero and one and sum to one:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.array([0.1, 0.5, 0.4, 4, 5]),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " constraints=om.ProbabilityConstraint(selector=lambda params: params[:3]),\n", + ")\n", + "\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "For a full overview of the constraints we support and the corresponding syntaxes, check out [the documentation](../how_to/how_to_constraints.md).\n", + "\n", + "Note that `\"scipy_lbfgsb\"` is not a constrained optimizer. If you want to know how we achieve this, check out [the explanations](../explanation/implementation_of_constraints.md)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## There is also maximize\n", + "\n", + "If you ever forgot to switch back the sign of your criterion function after doing a maximization with `scipy.optimize.minimize`, there is good news:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def upside_down_sphere(params):\n", + " return -params @ params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.maximize(\n", + " fun=upside_down_sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_bfgs\",\n", + ")\n", + "\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "optimagic got your back." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## You can provide closed form derivatives" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "def sphere_gradient(params):\n", + " return 2 * params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " jac=sphere_gradient,\n", + ")\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Or use parallelized numerical derivatives" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " numdiff_options=om.NumdiffOptions(n_cores=6),\n", + ")\n", + "\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Turn local optimizers global with multistart\n", + "\n", + "Multistart optimization requires finite soft bounds on all parameters. Those bounds will\n", + "be used for sampling but not enforced during optimization." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "bounds = om.Bounds(soft_lower=np.full(10, -5), soft_upper=np.full(10, 15))\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(10),\n", + " algorithm=\"scipy_neldermead\",\n", + " bounds=bounds,\n", + " multistart=om.MultistartOptions(convergence_max_discoveries=5),\n", + ")\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## And plot the criterion history of all local optimizations" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "fig = om.criterion_plot(res)\n", + "fig.show(renderer=\"png\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Exploit the structure of your optimization problem\n", + "\n", + "Many estimation problems have a least-squares structure. If so, specialized optimizers that exploit this structure can be much faster than standard optimizers. The `sphere` function from above is the simplest possible least-squarse problem you could imagine: the least-squares residuals are just the params. \n", + "\n", + "To use least-squares optimizers in optimagic, you need to declare mark your function with \n", + "a decorator and return the least-squares residuals instead of the aggregated function value. \n", + "\n", + "More details can be found [here](../how_to/how_to_criterion_function.md)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "@om.mark.least_squares\n", + "def ls_sphere(params):\n", + " return params" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=ls_sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"pounders\",\n", + ")\n", + "res.params.round(5)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Of course, any least-squares problem can also be solved with a standard optimizer. \n", + "\n", + "There are also specialized optimizers for likelihood functions. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Using and reading persistent logging\n", + "\n", + "For long-running and difficult optimizations, it can be worthwhile to store the progress in a persistent log file. You can do this by providing a path to the `logging` argument:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " logging=\"my_log.db\",\n", + " log_options={\"if_database_exists\": \"replace\"},\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can read the entries in the log file (while the optimization is still running or after it has finished) as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "reader = om.OptimizeLogReader(\"my_log.db\")\n", + "reader.read_history().keys()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "For more information on what you can do with the log file and LogReader object, check out [the logging tutorial](../how_to/how_to_logging.ipynb)\n", + "\n", + "The persistent log file is always instantly synchronized when the optimizer tries a new parameter vector. This is very handy if an optimization has to be aborted and you want to extract the current status. It can be displayed in `criterion_plot` and `params_plot`, even while the optimization is running. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Customize your optimizer\n", + "\n", + "Most algorithms have a few optional arguments. Examples are convergence criteria or tuning parameters. You can find an overview of supported arguments [here](../how_to/how_to_specify_algorithm_and_algo_options.md)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "algo_options = {\n", + " \"convergence.ftol_rel\": 1e-9,\n", + " \"stopping.maxiter\": 100_000,\n", + "}\n", + "\n", + "res = om.minimize(\n", + " fun=sphere,\n", + " params=np.arange(5),\n", + " algorithm=\"scipy_lbfgsb\",\n", + " algo_options=algo_options,\n", + ")\n", + "res.params.round(5)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.14" + }, + "vscode": { + "interpreter": { + "hash": "40d3a090f54c6569ab1632332b64b2c03c39dcf918b08424e98f38b5ae0af88f" + } + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/source/videos.md b/docs/source/videos.md index bb73e9606..098551dc4 100644 --- a/docs/source/videos.md +++ b/docs/source/videos.md @@ -2,7 +2,7 @@ # Videos -Check out our tutorials, talks and screencasts about estimagic. +Check out our tutorials, talks and screencasts about optimagic. ## Talks and tutorials @@ -44,7 +44,7 @@ taught at the University of Bonn by also [Janoś Gabler](https://github.com/janosg). You can find all screencasts of the course on the [course webite](https://effective-programming-practices.vercel.app/landing-page.html). -Here, we show the screencasts about numerical optimization and estimagic. +Here, we show the screencasts about numerical optimization and optimagic. ### Introduction to numerical optimization @@ -56,7 +56,7 @@ allowfullscreen> ``` -### Using estimagic’s minimize and maximize +### Using optimagic’s minimize and maximize ```{raw} html