samapy 1.0.6

Solar Alone Multi-Objective Advisor

Open-Source Hybrid Renewable Energy Microgrid Optimization

SAMA is a free, open-source Python platform for the design, sizing, and operation optimization of hybrid renewable energy microgrids. It performs location-specific techno-economic assessment using site-dependent load profiles, meteorological data, component degradation models, and utility billing structures, with no license fees and no black-box code.

Developed by the FAST Research Group at Western University, London, Ontario, Canada.

Table of Contents

• Why SAMA?
• What SAMA Optimizes
• Key Capabilities
• Getting Started
  • Method 1: Raw Python Code
  • Method 2: Python Package (pip)
  • Method 3: Windows .exe (Alpha)
• Quick Start
• Optimization Algorithms
• Output Examples
• Documentation
• Publications
• Citation
• License
• Contact

Why SAMA?

Proprietary tools like HOMER Pro and HOMER Grid are closed-source and license-restricted. SAMA was built to remove that barrier:

• Free and open-source: GPL-3.0, forever
• Transparent algorithms: read, modify, and extend every line
• Validated: cross-validated against HOMER Pro across multiple U.S. climate zones
• No cost barriers: designed for researchers, students, and resource-constrained institutions worldwide

What SAMA Optimizes

SAMA finds the optimal combination of five system design variables by minimizing Net Present Cost (NPC) over a 25-year project lifetime:

Constraints include reliability (LPSP), renewable energy fraction, capital budget, and rooftop area limits. Multi-objective mode (EM=1) adds Levelized Emissions (LEM) as a second objective.

Key Capabilities

Getting Started

SAMA supports three usage methods. Choose the one that fits your workflow:

Method 1: Raw Python Code

For researchers and developers who want full access to source code and algorithms.

git clone https://github.com/Sas1997/SAMA.git
cd SAMA
pip install -e .

This installs SAMA in editable mode, so you can edit any file under src/samapy/ directly and see your changes immediately. Configure your system with the wizard or by editing src/samapy/core/Input_Data.py, then run:

samapy-run

Available algorithms: pso, ade, abc, gwo

Method 2: Python Package (pip)

The recommended method for most users. No source editing required.

pip install samapy

Note: The PyPI distribution name is samapy. Once installed, import and CLI commands use samapy. Step 1: Configure your project:

samapy-config

An interactive multi section wizard guides you through all parameters and saves samapy_config_COMPLETE.yaml. Step 2: Run the optimization:

samapy-run

Step 3: View results in samapy_outputs/

Additional run options:

samapy-run --algorithm ade          # override algorithm
samapy-run --output results/run1    # override output directory
samapy-run --dry-run --verbose      # validate config without running
samapy-run --no-gui                 # headless / server mode

Method 3: Windows .exe (Alpha)

A point-and-click GUI for non-technical users. No Python installation required. Currently in alpha.

https://github.com/Sas1997/SAMA

Quick Start

Run SAMAPY in five steps using bundled sample data (London, Ontario):

# 1. Install
pip install samapy

# 2. Create a project folder and navigate into it
mkdir my_samapy_project && cd my_samapy_project

# 3. Launch the configuration wizard (accept defaults for a quick test)
samapy-config

# 4. Run the optimization
samapy-run

# 5. View your results
#    samapy_outputs/figs/    → all charts (PNG/SVG)
#    samapy_outputs/data/    → Outputforplotting.csv (8,760-hour time series)

Expected runtime: 2–10 minutes for MaxIt=200, nPop=50 depending on hardware. The first run is slower due to one-time Numba JIT compilation of the EMS engine.

Optimization Algorithms

All four algorithms optimize the same 5-variable design space. Choose based on your preference for convergence speed vs. exploration depth:

For rigorous comparison, set Run_Time > 1 to average across multiple independent runs.

Output Examples

After samapy-run completes, results are organized in samapy_outputs/:

samapy_outputs/
├── Optimization.png                  ← convergence curve
├── figs/
│   ├── Cash_Flow.svg                 ← 25-year lifecycle cost breakdown
│   ├── Energy Distribution.png       ← annual energy supply by source
│   ├── Battery State of Charge.png   ← hourly SOC profile
│   ├── Grid Interconnection.png      ← hourly grid import/export
│   ├── electricity_comparison.png    ← SAMAPY system vs. grid-only cost
│   ├── hp_monthly_summary.png        ← heat pump COP and energy (if HP=1)
│   └── EV Energy.png                 ← EV charge/discharge (if EV=1)
└── data/
    ├── Outputforplotting.csv         ← full 8,760-hour time series
    └── cash_flow_data.csv            ← annual 25-year cash flow table

Documentation

Full documentation is available in this repository:

• SAMA_Documentation.md: Complete user guide covering all parameters, algorithms, financial models, input formats, troubleshooting, and mathematical formulations

Key documentation sections:

Publications

SAMA has been peer-reviewed and published across multiple journals. If you use SAMA in your research, please cite [A1]:

Citation

If you use SAMA in academic work, please cite the primary paper:

@article{sadat2023sama,
  title   = {A Free and open source microgrid optimization tool: {SAMA} the solar alone Multi-Objective Advisor},
  author  = {Sadat, Seyyed Ali and Takahashi, J. and Pearce, Joshua M.},
  journal = {Energy Conversion and Management},
  volume  = {298},
  pages   = {117686},
  year    = {2023},
  doi     = {10.1016/j.enconman.2023.117686}
}

License

SAMA is released under the GNU General Public License v3.0 (GPL-3.0). You are free to use, copy, modify, and distribute SAMA. Any derivative works must also be released under GPL-3.0.

Contact

FAST Research Group, Western University, London, Ontario, Canada

• GitHub: https://github.com/Sas1997/SAMA
• Issues and bug reports: Open an issue
• For the Windows .exe alpha version or reprint requests, contact the developers through the GitHub repository.

Made with ☀️ by the FAST Research Group · Western University · GPL-3.0