# Monarch Swarm Optimization (MSO)
A Python implementation of the Monarch Swarm Optimization algorithm, designed for solving binary optimization problems. MSO is inspired by the migration behavior of monarch butterflies and uses a novel approach combining swarm intelligence with gradient-based optimization.
## Features
- Binary optimization for various problem types
- Built-in command line interface
- Automatic result saving and history tracking
- Early stopping with known optimum
- Automatic progress reporting
- Custom problem file loading support
- Customizable algorithm parameters
- Built-in timeout mechanism
- Reproducible results with seed setting
## Installation
You can install MSO using pip:
```bash
pip install monarch-swarm-optimization
```
## Quick Start
Here's a simple example to get you started:
```python
from mso import MSO
import numpy as np
def simple_fitness(solution):
"""Example fitness function: maximize sum of elements."""
return np.sum(solution)
# Run optimization
MSO.run(
obj_func=simple_fitness, # Your fitness function
dim=20, # Problem dimension
pop_size=50, # Population size
max_iter=100, # Maximum iterations
obj_type='max', # Maximize the objective
neighbour_count=3 # Number of neighbors
)
```
Run your script with command line options:
```bash
# Basic run
python your_script.py
# Save results
python your_script.py --save-results yes
# Specify results directory
python your_script.py --save-results yes --results-dir my_results
# Set random seed
python your_script.py --seed 42
```
## Using With Problem Files
For problems that require loading data from files (e.g., Multiple Knapsack Problem):
```python
from mso import MSO
import numpy as np
from dataclasses import dataclass
@dataclass
class ProblemData:
"""Your problem data structure."""
dim: int
weights: np.ndarray
# ... other problem-specific data
def read_problem_file(filepath: str):
"""Your file reading function."""
# Read and parse your problem file
data = ProblemData(...)
known_optimum = ... # Optional
return data, known_optimum
def calculate_fitness(solution, data):
"""Your fitness calculation."""
# Calculate fitness using solution and problem data
return fitness_value
# Run optimization
MSO.run(
obj_func=calculate_fitness,
dim=None, # Will be set from problem file
load_problem_file=read_problem_file,
known_optimum=123.45, # Optional
tolerance=1e-6, # Required if known_optimum is set
pop_size=100,
max_iter=500,
obj_type='max'
)
```
## API Reference
### Main Parameters
Required:
- `obj_func`: Objective function to optimize
- `dim`: Problem dimension (or None if using problem file)
- `pop_size`: Population size (>0)
- `max_iter`: Maximum iterations (>0)
- `obj_type`: 'min' or 'max'
- `neighbour_count`: Number of neighbors (1 <= n < pop_size)
Optional:
- `load_problem_file`: Function to load problem data
- `gradient_strength`: Gradient influence (0-1, default=0.8)
- `base_learning_rate`: Learning rate (0-1, default=0.1)
- `known_optimum`: Known optimal value
- `tolerance`: Convergence tolerance
- `timeout`: Maximum runtime in seconds
- `seed`: Random seed for reproducibility
### Command Line Arguments
- `--save-results`: Whether to save results ('yes' or 'no', default='no')
- `--results-dir`: Directory to save results (default='results')
- `--seed`: Random seed for reproducibility
## Examples
The package includes several example implementations:
1. Basic binary optimization
2. Multiple Knapsack Problem (MKP)
Check the `examples/` directory in the repository for complete examples.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "monarch-swarm-optimization",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "optimization, swarm intelligence, metaheuristic, binary optimization",
"author": null,
"author_email": "Emrullah Gazioglu <emrullahgazioglu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fc/59/0d91a290c8b167dbbcc22abcae4be32c93ceed28ec63ba6abd404959ee78/monarch_swarm_optimization-0.1.1.tar.gz",
"platform": null,
"description": "# Monarch Swarm Optimization (MSO)\n\nA Python implementation of the Monarch Swarm Optimization algorithm, designed for solving binary optimization problems. MSO is inspired by the migration behavior of monarch butterflies and uses a novel approach combining swarm intelligence with gradient-based optimization.\n\n## Features\n\n- Binary optimization for various problem types\n- Built-in command line interface\n- Automatic result saving and history tracking\n- Early stopping with known optimum\n- Automatic progress reporting\n- Custom problem file loading support\n- Customizable algorithm parameters\n- Built-in timeout mechanism\n- Reproducible results with seed setting\n\n## Installation\n\nYou can install MSO using pip:\n\n```bash\npip install monarch-swarm-optimization\n```\n\n## Quick Start\n\nHere's a simple example to get you started:\n\n```python\nfrom mso import MSO\nimport numpy as np\n\ndef simple_fitness(solution):\n \"\"\"Example fitness function: maximize sum of elements.\"\"\"\n return np.sum(solution)\n\n# Run optimization\nMSO.run(\n obj_func=simple_fitness, # Your fitness function\n dim=20, # Problem dimension\n pop_size=50, # Population size\n max_iter=100, # Maximum iterations\n obj_type='max', # Maximize the objective\n neighbour_count=3 # Number of neighbors\n)\n```\n\nRun your script with command line options:\n```bash\n# Basic run\npython your_script.py\n\n# Save results\npython your_script.py --save-results yes\n\n# Specify results directory\npython your_script.py --save-results yes --results-dir my_results\n\n# Set random seed\npython your_script.py --seed 42\n```\n\n## Using With Problem Files\n\nFor problems that require loading data from files (e.g., Multiple Knapsack Problem):\n\n```python\nfrom mso import MSO\nimport numpy as np\nfrom dataclasses import dataclass\n\n@dataclass\nclass ProblemData:\n \"\"\"Your problem data structure.\"\"\"\n dim: int\n weights: np.ndarray\n # ... other problem-specific data\n\ndef read_problem_file(filepath: str):\n \"\"\"Your file reading function.\"\"\"\n # Read and parse your problem file\n data = ProblemData(...)\n known_optimum = ... # Optional\n return data, known_optimum\n\ndef calculate_fitness(solution, data):\n \"\"\"Your fitness calculation.\"\"\"\n # Calculate fitness using solution and problem data\n return fitness_value\n\n# Run optimization\nMSO.run(\n obj_func=calculate_fitness,\n dim=None, # Will be set from problem file\n load_problem_file=read_problem_file,\n known_optimum=123.45, # Optional\n tolerance=1e-6, # Required if known_optimum is set\n pop_size=100,\n max_iter=500,\n obj_type='max'\n)\n```\n\n## API Reference\n\n### Main Parameters\n\nRequired:\n- `obj_func`: Objective function to optimize\n- `dim`: Problem dimension (or None if using problem file)\n- `pop_size`: Population size (>0)\n- `max_iter`: Maximum iterations (>0)\n- `obj_type`: 'min' or 'max'\n- `neighbour_count`: Number of neighbors (1 <= n < pop_size)\n\nOptional:\n- `load_problem_file`: Function to load problem data\n- `gradient_strength`: Gradient influence (0-1, default=0.8)\n- `base_learning_rate`: Learning rate (0-1, default=0.1)\n- `known_optimum`: Known optimal value\n- `tolerance`: Convergence tolerance\n- `timeout`: Maximum runtime in seconds\n- `seed`: Random seed for reproducibility\n\n### Command Line Arguments\n\n- `--save-results`: Whether to save results ('yes' or 'no', default='no')\n- `--results-dir`: Directory to save results (default='results')\n- `--seed`: Random seed for reproducibility\n\n## Examples\n\nThe package includes several example implementations:\n\n1. Basic binary optimization\n2. Multiple Knapsack Problem (MKP)\n\nCheck the `examples/` directory in the repository for complete examples.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python implementation of Monarch Swarm Optimization algorithm",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/gazioglue/monarch-swarm-optimization/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/gazioglue/monarch-swarm-optimization#readme",
"Homepage": "https://github.com/gazioglue/monarch-swarm-optimization",
"Repository": "https://github.com/gazioglue/monarch-swarm-optimization.git",
"Usage": "https://github.com/gazioglue/monarch-swarm-optimization/blob/main/USAGE.md"
},
"split_keywords": [
"optimization",
" swarm intelligence",
" metaheuristic",
" binary optimization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d398fd5f723e4ff09cb79fc834e93dfa077564c7d64c4818ffec8899a0d87d95",
"md5": "cf9b7524df673ed27ae9c638ef8fb815",
"sha256": "f63ebecbc2b1823a0b42bc2a3c3881830b6418373444c4da3465658a4c6244fc"
},
"downloads": -1,
"filename": "monarch_swarm_optimization-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf9b7524df673ed27ae9c638ef8fb815",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10212,
"upload_time": "2025-01-05T06:42:42",
"upload_time_iso_8601": "2025-01-05T06:42:42.886835Z",
"url": "https://files.pythonhosted.org/packages/d3/98/fd5f723e4ff09cb79fc834e93dfa077564c7d64c4818ffec8899a0d87d95/monarch_swarm_optimization-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc590d91a290c8b167dbbcc22abcae4be32c93ceed28ec63ba6abd404959ee78",
"md5": "21c34654f146e7856bb3ef2b673be453",
"sha256": "0b13267cefe0220905fa81baab2fb86fc017fdc49db887f31440e170da1911d9"
},
"downloads": -1,
"filename": "monarch_swarm_optimization-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "21c34654f146e7856bb3ef2b673be453",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9891,
"upload_time": "2025-01-05T06:42:45",
"upload_time_iso_8601": "2025-01-05T06:42:45.851881Z",
"url": "https://files.pythonhosted.org/packages/fc/59/0d91a290c8b167dbbcc22abcae4be32c93ceed28ec63ba6abd404959ee78/monarch_swarm_optimization-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-05 06:42:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gazioglue",
"github_project": "monarch-swarm-optimization",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "monarch-swarm-optimization"
}
JSON
