marsopt


Namemarsopt JSON
Version 0.1.0 PyPI version JSON
download
home_pageNone
SummaryMixed Adaptive Random Search for Optimization
upload_time2025-03-01 08:10:41
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseMIT License
keywords python optimization adaptive-random-search hyperparameter-tuning hyperparameter-optimization mixed-parameter-space categorical-parameters machine-learning data-science metaheuristics
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # marsopt
**Mixed Adaptive Random Search for Optimization**

[![PyPI version](https://img.shields.io/pypi/v/marsopt.svg)](https://pypi.org/project/marsopt/)
[![License](https://img.shields.io/github/license/sibirbil/marsopt.svg)](LICENSE)
[![Python Versions](https://img.shields.io/pypi/pyversions/marsopt.svg)](https://pypi.org/project/marsopt/)

`marsopt` is a Python library designed to simplify and accelerate hyperparameter and black-box optimization. It supports **continuous**, **integer**, and **categorical** variables. Based on **Mixed Adaptive Random Search** (MARS) algorithm, `marsopt` dynamically balances exploration and exploitation through:
- **adaptive noise** for sampling,
- **elite selection** to guide the search toward promising regions,
- flexible handling of **log-scale** and **categorical** parameters,
- minimization **or** maximization of any user-defined objective.

MARS iteratively refines a population of “elite” solutions and generates new candidates by **perturbing** those elites with gradually decreasing noise. For a more detailed explanation of MARS, see our **[algorithm overview](https://marsopt.readthedocs.io/en/latest/algorithm.html)** in the documentation.

## Features
- **Mixed Variable Support**: Optimize integer, float (with optional log-scale), and categorical variables in the same study.  
- **Adaptive Sampling**: Early iterations explore widely, while later iterations exploit the best regions found, thanks to a built-in **cosine annealing** scheme for noise.  
- **Easy Setup**: Simply define an objective function, specify a variable search space, and run `study.optimize()`.  
- **Resume & Extend**: Continue a `Study` with more trials at any time without losing past information.  
- **Rich Tracking**: Inspect all trial details (objective values, parameters, times, and so on) for deeper analysis.  

## Installation
Install `marsopt` from PyPI:

```bash
pip install marsopt
```

## Getting Started

Below is a simplified example of how to use `marsopt` to tune a few common hyperparameters:

```python
from marsopt import Study, Trial
import numpy as np

def objective(trial: Trial) -> float:
    lr = trial.suggest_float("learning_rate", 1e-4, 1e-1, log=True)
    layers = trial.suggest_int("num_layers", 1, 5)
    optimizer = trial.suggest_categorical("optimizer", ["adam", "sgd", "rmsprop"])

    score = -5 * (np.log10(lr) + 3) ** 2  
    score += np.log1p(layers) * 10  
    score += {"adam": 15, "sgd": 5, "rmsprop": 20}[optimizer]

    return score 

# Run optimization
study = Study(direction="minimize", random_state=42) # Minimize the  score
study.optimize(objective, n_trials=50)
```

### Documentation
For more detailed information about the API and advanced usage, please refer to the full [documentation](https://marsopt.readthedocs.io/en/latest/).

## Contributing

Contributions are welcome! If you'd like to improve `marsopt` or suggest new features, feel free to fork the repository and submit a pull request.

## License
This project is licensed under the [MIT License](LICENSE).  


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "marsopt",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "python, optimization, adaptive-random-search, hyperparameter-tuning, hyperparameter-optimization, mixed-parameter-space, categorical-parameters, machine-learning, data-science, metaheuristics",
    "author": null,
    "author_email": "Samet Copur <sametcopur@yahoo.com>, Ilker Birbil <sibirbil@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/81/c0/c6b9a241f34a5bbf870f3ced0c67ffb0a201b84891d36cb54ca51ecd0725/marsopt-0.1.0.tar.gz",
    "platform": null,
    "description": "# marsopt\n**Mixed Adaptive Random Search for Optimization**\n\n[![PyPI version](https://img.shields.io/pypi/v/marsopt.svg)](https://pypi.org/project/marsopt/)\n[![License](https://img.shields.io/github/license/sibirbil/marsopt.svg)](LICENSE)\n[![Python Versions](https://img.shields.io/pypi/pyversions/marsopt.svg)](https://pypi.org/project/marsopt/)\n\n`marsopt` is a Python library designed to simplify and accelerate hyperparameter and black-box optimization. It supports **continuous**, **integer**, and **categorical** variables. Based on **Mixed Adaptive Random Search** (MARS) algorithm, `marsopt` dynamically balances exploration and exploitation through:\n- **adaptive noise** for sampling,\n- **elite selection** to guide the search toward promising regions,\n- flexible handling of **log-scale** and **categorical** parameters,\n- minimization **or** maximization of any user-defined objective.\n\nMARS iteratively refines a population of \u201celite\u201d solutions and generates new candidates by **perturbing** those elites with gradually decreasing noise. For a more detailed explanation of MARS, see our **[algorithm overview](https://marsopt.readthedocs.io/en/latest/algorithm.html)** in the documentation.\n\n## Features\n- **Mixed Variable Support**: Optimize integer, float (with optional log-scale), and categorical variables in the same study.  \n- **Adaptive Sampling**: Early iterations explore widely, while later iterations exploit the best regions found, thanks to a built-in **cosine annealing** scheme for noise.  \n- **Easy Setup**: Simply define an objective function, specify a variable search space, and run `study.optimize()`.  \n- **Resume & Extend**: Continue a `Study` with more trials at any time without losing past information.  \n- **Rich Tracking**: Inspect all trial details (objective values, parameters, times, and so on) for deeper analysis.  \n\n## Installation\nInstall `marsopt` from PyPI:\n\n```bash\npip install marsopt\n```\n\n## Getting Started\n\nBelow is a simplified example of how to use `marsopt` to tune a few common hyperparameters:\n\n```python\nfrom marsopt import Study, Trial\nimport numpy as np\n\ndef objective(trial: Trial) -> float:\n    lr = trial.suggest_float(\"learning_rate\", 1e-4, 1e-1, log=True)\n    layers = trial.suggest_int(\"num_layers\", 1, 5)\n    optimizer = trial.suggest_categorical(\"optimizer\", [\"adam\", \"sgd\", \"rmsprop\"])\n\n    score = -5 * (np.log10(lr) + 3) ** 2  \n    score += np.log1p(layers) * 10  \n    score += {\"adam\": 15, \"sgd\": 5, \"rmsprop\": 20}[optimizer]\n\n    return score \n\n# Run optimization\nstudy = Study(direction=\"minimize\", random_state=42) # Minimize the  score\nstudy.optimize(objective, n_trials=50)\n```\n\n### Documentation\nFor more detailed information about the API and advanced usage, please refer to the full [documentation](https://marsopt.readthedocs.io/en/latest/).\n\n## Contributing\n\nContributions are welcome! If you'd like to improve `marsopt` or suggest new features, feel free to fork the repository and submit a pull request.\n\n## License\nThis project is licensed under the [MIT License](LICENSE).  \n\n",
    "bugtrack_url": null,
    "license": "MIT License",
    "summary": "Mixed Adaptive Random Search for Optimization",
    "version": "0.1.0",
    "project_urls": {
        "Documentation": "https://marsopt.readthedocs.io/en/latest/",
        "Repository": "https://github.com/sibirbil/marsopt",
        "Tracker": "https://github.com/sibirbil/marspot/issues"
    },
    "split_keywords": [
        "python",
        " optimization",
        " adaptive-random-search",
        " hyperparameter-tuning",
        " hyperparameter-optimization",
        " mixed-parameter-space",
        " categorical-parameters",
        " machine-learning",
        " data-science",
        " metaheuristics"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "1a253f8b0882e8b8b07f03fe35e4d02d82f28d26f20ec607808afc27a457c7e4",
                "md5": "5cccad5499a17d21e04b191c9e730bbb",
                "sha256": "dec7cf58605b31db17d663448fd52c1094780756615d7fe831293ca39e0ab858"
            },
            "downloads": -1,
            "filename": "marsopt-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5cccad5499a17d21e04b191c9e730bbb",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 13553,
            "upload_time": "2025-03-01T08:10:39",
            "upload_time_iso_8601": "2025-03-01T08:10:39.901203Z",
            "url": "https://files.pythonhosted.org/packages/1a/25/3f8b0882e8b8b07f03fe35e4d02d82f28d26f20ec607808afc27a457c7e4/marsopt-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "81c0c6b9a241f34a5bbf870f3ced0c67ffb0a201b84891d36cb54ca51ecd0725",
                "md5": "b6b1c7bdfcede3b7603df063f3cacf9f",
                "sha256": "099ad2793f6d6514d55c5edd7d9a89772a58d57af6c6589ae107118416c87bab"
            },
            "downloads": -1,
            "filename": "marsopt-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "b6b1c7bdfcede3b7603df063f3cacf9f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 14675,
            "upload_time": "2025-03-01T08:10:41",
            "upload_time_iso_8601": "2025-03-01T08:10:41.530395Z",
            "url": "https://files.pythonhosted.org/packages/81/c0/c6b9a241f34a5bbf870f3ced0c67ffb0a201b84891d36cb54ca51ecd0725/marsopt-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-03-01 08:10:41",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "sibirbil",
    "github_project": "marsopt",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "marsopt"
}
        
Elapsed time: 0.40685s