{
    "info": {
        "author": "Romain Strock",
        "author_email": "romain.strock@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 5 - Production/Stable",
            "Intended Audience :: Developers",
            "Intended Audience :: Education",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Topic :: Scientific/Engineering",
            "Topic :: Scientific/Engineering :: Artificial Intelligence",
            "Topic :: Scientific/Engineering :: Mathematics",
            "Topic :: Software Development",
            "Topic :: Software Development :: Libraries",
            "Topic :: Software Development :: Libraries :: Python Modules"
        ],
        "description": "Covariance Matrix Adaptation Evolution Strategy (CMA-ES)\n--------------------------------------------------------\n\nA Tensorflow v2 implementation.\n\n## What is CMA-ES?\n\nQuoting [The CMA Evolution Strategy][1] homepage:\n\n> The CMA-ES (Covariance Matrix Adaptation Evolution Strategy) is an evolutionary algorithm for difficult non-linear non-convex black-box optimisation problems in continuous domain. It is considered as state-of-the-art in evolutionary computation and has been adopted as one of the standard tools for continuous optimisation in many (probably hundreds of) research labs and industrial environments around the world. \n\n## Installation\n\nThe package is [available on PyPI](https://pypi.org/project/cma-es/) and can be installed with pip:\n\n```sh\npip install cma-es\n```\n\n## Example Usage\n\n### 1. Define the fitness function\n\nThe CMA class expects a fitness function with the following signature:\n\n```    \nArgs:\n  x: tf.Tensor of shape (M, N)\n\nReturns:\n  Fitness evaluations: tf.Tensor of shape (M,)\n```\n\nWhere `M` is the number of solutions to evaluate and `N` is the dimension of a single solution.\n\n```python\ndef fitness_fn(x):\n    \"\"\"\n    Six-Hump Camel Function\n    https://www.sfu.ca/~ssurjano/camel6.html\n    \"\"\"\n    return (\n        (4 - 2.1 * x[:,0]**2 + x[:,0]**4 / 3) * x[:,0]**2 +\n        x[:,0] * x[:,1] +\n        (-4 + 4 * x[:,1]**2) * x[:,1]**2\n    )\n```\n\n![Figure1: Six-Hump Camel Function](six_hump_camel_fn.png?raw=true)\n\n### 2. Configure CMA-ES\n\n```python\nfrom cma import CMA\n\ncma = CMA(\n    initial_solution=[1.5, -0.4],\n    initial_step_size=1.0,\n    fitness_function=fitness_fn,\n)\n```\n\nThe initial solution and initial step size (i.e. initial standard deviation of the search distribution) are problem specific.\n\nThe population size is automatically set by default, but it can be overidden by specifying the parameter `population_size`.\n\nFor bounded constraint optimization problems, the parameter `enforce_bounds` can be set, e.g. `enforce_bounds=[[-2, 2], [-1, 1]]` for a 2D function.\n\n### 3. Run the optimizer\n\nThe search method runs until the maximum number of generation is reached or until one of the early termination criteria is met. By default, the maximum number of generations is 500.\n\n```python\nbest_solution, best_fitness = cma.search()\n```\n\nThe notebook [`Example 1 - Six Hump Camel Function`][4] goes into more details, including ways to plot the optimization path such as in the figure below.\n\n![Figure 2: Optimization path](cma_trace.png?raw=true)\n\n## Logging\n\nA user-defined callabck function can be specified to inspect variables during the search.\n\nIt is mainly intended for logging purpose, e.g:\n\n```python\nmax_epochs = 500\n\ndef logging_function(cma, logger):\n    if cma.generation % 10 == 0:\n        fitness = cma.best_fitness()\n        logger.info(f'Generation {cma.generation} - fitness {fitness}')\n\n    if cma.termination_criterion_met or cma.generation == max_epochs:\n        sol = cma.best_solution()\n        fitness = cma.best_fitness()\n        logger.info(f'Final solution at gen {cma.generation}: {sol} (fitness: {fitness})')\n\ncma = CMA(\n    initial_solution=[1.5, -0.4],\n    initial_step_size=1.0,\n    fitness_function=fitness_fn,\n    callback_function=logging_function,\n)\ncma.search(max_epochs)\n```\n\nCheck out an example logging progress to TensorBoard: [tensorboard_example.py][6]\n\n## Run on a GPU\n\nBy virtue of being written using TensorFlow, it is trivial to run CMA on a GPU:\n\n```python\nwith tf.device('/GPU:0'):\n    cma.search()\n```\n\n## More examples\n\n- Jupyter notebooks with examples are available:\n  - [Example 1 - Six-Hump Camel Function][4]\n  - [Example 2 - Schwefel Function][5]\n  - [Example 3 - Logging to TensorBoard][6]\n- Unit tests provide a few more examples: `cma/core_test.py`\n\n## Resources\n\n- [CMA-ES at Wikipedia][3]\n- [The CMA Evolution Strategy][1]\n- [The CMA Evolution Strategy: A Tutorial][2]\n\n[1]: http://cma.gforge.inria.fr/\n[2]: https://arxiv.org/abs/1604.00772\n[3]: https://en.wikipedia.org/wiki/CMA-ES\n[4]: https://nbviewer.jupyter.org/github/srom/cma-es/blob/master/notebook/Example%201%20-%20Six%20Hump%20Camel%20Function.ipynb\n[5]: https://nbviewer.jupyter.org/github/srom/cma-es/blob/master/notebook/Example%202%20-%20Schwefel%20Function.ipynb\n[6]: https://github.com/srom/cma-es/blob/master/notebook/tensorboard_example.py",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/srom/cma-es",
        "keywords": "optimization,numerical-optimization,tensorflow",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "cma-es",
        "package_url": "https://pypi.org/project/cma-es/",
        "platform": "",
        "project_url": "https://pypi.org/project/cma-es/",
        "project_urls": {
            "Homepage": "https://github.com/srom/cma-es"
        },
        "release_url": "https://pypi.org/project/cma-es/1.2.0/",
        "requires_dist": null,
        "requires_python": ">=3.6",
        "summary": "Covariance Matrix Adaptation Evolution Strategy (CMA-ES) implemented with TensorFlow v2",
        "version": "1.2.0"
    },
    "last_serial": 5989290,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "06d3b3c130f1701ccfa3e9d88c2c981a",
                    "sha256": "437dd3d3ed4d251d8e302624fa6ad8a9b0c36e99b6cb2d75593077967de1ea47"
                },
                "downloads": -1,
                "filename": "cma-es-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "06d3b3c130f1701ccfa3e9d88c2c981a",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 7042,
                "upload_time": "2019-10-11T16:15:50",
                "url": "https://files.pythonhosted.org/packages/d9/e3/0f748fb567b258a0ebefe2236585d688f1246fab151375db79f230e74bca/cma-es-1.0.0.tar.gz"
            }
        ],
        "1.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "97b2b9a934e18d1072061bef0f033700",
                    "sha256": "844d22b357dcabe267168591ef342ad000696ff2558d5cab3a09e41183a18ce4"
                },
                "downloads": -1,
                "filename": "cma-es-1.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "97b2b9a934e18d1072061bef0f033700",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 7329,
                "upload_time": "2019-10-12T11:54:30",
                "url": "https://files.pythonhosted.org/packages/0c/7a/204ce21f692c6795a6e0c55df3b9dddba3fe8a8e5683730656b291fae149/cma-es-1.1.0.tar.gz"
            }
        ],
        "1.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "f64806f43f3ac3a27ce97c0d12d8de81",
                    "sha256": "5ff8d532cffd6dded1903b71c6b2b8acc8493cf6612b40cbf7392f81ed61928e"
                },
                "downloads": -1,
                "filename": "cma-es-1.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "f64806f43f3ac3a27ce97c0d12d8de81",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 8670,
                "upload_time": "2019-10-17T11:45:21",
                "url": "https://files.pythonhosted.org/packages/56/7c/dd12bd33b12578cb82206858afc526b5923c90d10d7e65f089da10580c35/cma-es-1.2.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "f64806f43f3ac3a27ce97c0d12d8de81",
                "sha256": "5ff8d532cffd6dded1903b71c6b2b8acc8493cf6612b40cbf7392f81ed61928e"
            },
            "downloads": -1,
            "filename": "cma-es-1.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "f64806f43f3ac3a27ce97c0d12d8de81",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 8670,
            "upload_time": "2019-10-17T11:45:21",
            "url": "https://files.pythonhosted.org/packages/56/7c/dd12bd33b12578cb82206858afc526b5923c90d10d7e65f089da10580c35/cma-es-1.2.0.tar.gz"
        }
    ]
}