# marsopt
**Mixed Adaptive Random Search for Optimization**
[](https://pypi.org/project/marsopt/)
[](LICENSE)
[](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[](https://pypi.org/project/marsopt/)\n[](LICENSE)\n[](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"
}
JSON
