monarch-swarm-optimization


Namemonarch-swarm-optimization JSON
Version 0.1.1 PyPI version JSON
download
home_pageNone
SummaryA Python implementation of Monarch Swarm Optimization algorithm
upload_time2025-01-05 06:42:45
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseMIT
keywords optimization swarm intelligence metaheuristic binary optimization
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 1.25726s