# sas1997/sama architecture

> Architecture diagram of the GitHub repository sas1997/sama, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sas1997/sama
- Repository: https://github.com/sas1997/sama

## Overview

SAMA is a Python platform for sizing and operating hybrid renewable-energy microgrids. Users configure system, load, weather, and tariff inputs, run an optimizer to minimize lifecycle cost (with emissions available as a second objective), then inspect simulation and financial results. The graph includes the documented optimizer and tariff branches; some subsystem links are omitted because their calling code was not sampled.

Main entry points: [`src/samapy/optimizers`](https://github.com/sas1997/sama/tree/main/src/samapy/optimizers) (Optimizer suite), [`src/samapy/cli/runner.py`](https://github.com/sas1997/sama/blob/main/src/samapy/cli/runner.py) (CLI runner), [`src/samapy/pricing`](https://github.com/sas1997/sama/tree/main/src/samapy/pricing) (Tariff calculations), [`src/samapy/ems/EMS_EV.py`](https://github.com/sas1997/sama/blob/main/src/samapy/ems/EMS_EV.py) (EV dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_wizard["Config wizard<br/>[wizard.py]"]
  node_config["Project config"]
  node_runner["CLI runner<br/>[runner.py]"]
  node_inputs["Input data<br/>[Input_Data.py]"]
end

subgraph group_optimization["Optimization"]
  node_optimizers["Optimizer suite"]
  node_pso["PSO<br/>[pso.py]"]
  node_ade["ADE"]
  node_abc["ABC"]
  node_gwo["Grey Wolf"]
end

subgraph group_simulation["Energy simulation"]
  node_results["Simulation results<br/>[Results.py]"]
  node_ems["Energy dispatch<br/>[EMS.py]"]
  node_ems_ev["EV dispatch<br/>[EMS_EV.py]"]
  node_input_profiles["Load and weather profiles<br/>[Input_Data.py]"]
  node_solar["Solar irradiance"]
  node_ev["EV demand tools<br/>[EV_demand_dest.py]"]
end

subgraph group_assessment["Economic assessment"]
  node_pricing["Tariff calculations"]
  node_bill["Electricity bills"]
  node_service_charge["Service charges<br/>[service_charge.py]"]
  node_cashflow["Lifecycle cash flow"]
end

subgraph group_support["Component models"]
  node_battery["Battery models<br/>[Battery_Model.py]"]
  node_heat_pump["Heat pump models<br/>[BB_HP_Bosch.py]"]
  node_heat_pump_goodman["Goodman heat pump<br/>[BB_HP_Goodman.py]"]
end

node_user(("Microgrid designer"))

node_user -->|"configures"| node_wizard
node_wizard -->|"writes config"| node_config
node_user -->|"starts run"| node_runner
node_runner -->|"loads config"| node_config
node_runner -->|"sets parameters"| node_inputs
node_runner -->|"selects algorithm"| node_optimizers
node_optimizers -->|"dispatches"| node_pso
node_optimizers -->|"dispatches"| node_ade
node_optimizers -->|"dispatches"| node_abc
node_optimizers -->|"dispatches"| node_gwo
node_results -->|"calls dispatch"| node_ems
node_results -->|"calls EV dispatch"| node_ems_ev
node_inputs -->|"provides profiles"| node_input_profiles
node_ems_ev -->|"uses models"| node_battery
node_ems_ev -->|"uses demand"| node_ev
node_pricing -->|"includes"| node_bill
node_pricing -->|"includes"| node_service_charge
node_pricing -->|"includes"| node_cashflow

click node_wizard "https://github.com/sas1997/sama/blob/main/src/samapy/cli/wizard.py"
click node_runner "https://github.com/sas1997/sama/blob/main/src/samapy/cli/runner.py"
click node_inputs "https://github.com/sas1997/sama/blob/main/src/samapy/core/Input_Data.py"
click node_optimizers "https://github.com/sas1997/sama/tree/main/src/samapy/optimizers"
click node_pso "https://github.com/sas1997/sama/blob/main/src/samapy/optimizers/pso.py"
click node_ade "https://github.com/sas1997/sama/blob/main/src/samapy/optimizers/AdvancedDifferentialEvolution.py"
click node_abc "https://github.com/sas1997/sama/blob/main/src/samapy/optimizers/ArtificialBeeColony.py"
click node_gwo "https://github.com/sas1997/sama/blob/main/src/samapy/optimizers/GreyWolfOptimizer.py"
click node_results "https://github.com/sas1997/sama/blob/main/src/samapy/results/Results.py"
click node_ems "https://github.com/sas1997/sama/blob/main/src/samapy/ems/EMS.py"
click node_ems_ev "https://github.com/sas1997/sama/blob/main/src/samapy/ems/EMS_EV.py"
click node_input_profiles "https://github.com/sas1997/sama/blob/main/src/samapy/core/Input_Data.py"
click node_solar "https://github.com/sas1997/sama/blob/main/src/samapy/utilities/sam_monofacial_poa.py"
click node_ev "https://github.com/sas1997/sama/blob/main/src/samapy/utilities/EV_demand_dest.py"
click node_battery "https://github.com/sas1997/sama/blob/main/src/samapy/models/Battery_Model.py"
click node_heat_pump "https://github.com/sas1997/sama/blob/main/src/samapy/models/BB_HP_Bosch.py"
click node_heat_pump_goodman "https://github.com/sas1997/sama/blob/main/src/samapy/models/BB_HP_Goodman.py"
click node_pricing "https://github.com/sas1997/sama/tree/main/src/samapy/pricing"
click node_bill "https://github.com/sas1997/sama/blob/main/src/samapy/pricing/Electricity_Bill_Calculator.py"
click node_service_charge "https://github.com/sas1997/sama/blob/main/src/samapy/pricing/service_charge.py"
click node_cashflow "https://github.com/sas1997/sama/blob/main/src/samapy/pricing/Advanced_multi_cashflow.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_wizard,node_config,node_runner,node_inputs toneBlue
class node_optimizers,node_pso,node_ade,node_abc,node_gwo toneAmber
class node_results,node_ems,node_ems_ev,node_input_profiles,node_solar,node_ev toneMint
class node_pricing,node_bill,node_service_charge,node_cashflow toneRose
class node_battery,node_heat_pump,node_heat_pump_goodman,node_user toneIndigo
```

## Components

### Configuration

- [Config wizard](https://github.com/sas1997/sama/blob/main/src/samapy/cli/wizard.py): `src/samapy/cli/wizard.py`
- **Project config**
- [CLI runner](https://github.com/sas1997/sama/blob/main/src/samapy/cli/runner.py): `src/samapy/cli/runner.py`
- [Input data](https://github.com/sas1997/sama/blob/main/src/samapy/core/Input_Data.py): `src/samapy/core/Input_Data.py`

### Optimization

- [Optimizer suite](https://github.com/sas1997/sama/tree/main/src/samapy/optimizers): `src/samapy/optimizers`
- [PSO](https://github.com/sas1997/sama/blob/main/src/samapy/optimizers/pso.py): `src/samapy/optimizers/pso.py`
- [ADE](https://github.com/sas1997/sama/blob/main/src/samapy/optimizers/AdvancedDifferentialEvolution.py): `src/samapy/optimizers/AdvancedDifferentialEvolution.py`
- [ABC](https://github.com/sas1997/sama/blob/main/src/samapy/optimizers/ArtificialBeeColony.py): `src/samapy/optimizers/ArtificialBeeColony.py`
- [Grey Wolf](https://github.com/sas1997/sama/blob/main/src/samapy/optimizers/GreyWolfOptimizer.py): `src/samapy/optimizers/GreyWolfOptimizer.py`

### Energy simulation

- [Simulation results](https://github.com/sas1997/sama/blob/main/src/samapy/results/Results.py): `src/samapy/results/Results.py`
- [Energy dispatch](https://github.com/sas1997/sama/blob/main/src/samapy/ems/EMS.py): `src/samapy/ems/EMS.py`
- [EV dispatch](https://github.com/sas1997/sama/blob/main/src/samapy/ems/EMS_EV.py): `src/samapy/ems/EMS_EV.py`
- [Load and weather profiles](https://github.com/sas1997/sama/blob/main/src/samapy/core/Input_Data.py): `src/samapy/core/Input_Data.py`
- [Solar irradiance](https://github.com/sas1997/sama/blob/main/src/samapy/utilities/sam_monofacial_poa.py): `src/samapy/utilities/sam_monofacial_poa.py`
- [EV demand tools](https://github.com/sas1997/sama/blob/main/src/samapy/utilities/EV_demand_dest.py): `src/samapy/utilities/EV_demand_dest.py`

### Economic assessment

- [Tariff calculations](https://github.com/sas1997/sama/tree/main/src/samapy/pricing): `src/samapy/pricing`
- [Electricity bills](https://github.com/sas1997/sama/blob/main/src/samapy/pricing/Electricity_Bill_Calculator.py): `src/samapy/pricing/Electricity_Bill_Calculator.py`
- [Service charges](https://github.com/sas1997/sama/blob/main/src/samapy/pricing/service_charge.py): `src/samapy/pricing/service_charge.py`
- [Lifecycle cash flow](https://github.com/sas1997/sama/blob/main/src/samapy/pricing/Advanced_multi_cashflow.py): `src/samapy/pricing/Advanced_multi_cashflow.py`

### Component models

- [Battery models](https://github.com/sas1997/sama/blob/main/src/samapy/models/Battery_Model.py): `src/samapy/models/Battery_Model.py`
- [Heat pump models](https://github.com/sas1997/sama/blob/main/src/samapy/models/BB_HP_Bosch.py): `src/samapy/models/BB_HP_Bosch.py`
- [Goodman heat pump](https://github.com/sas1997/sama/blob/main/src/samapy/models/BB_HP_Goodman.py): `src/samapy/models/BB_HP_Goodman.py`

### Other components

- **Microgrid designer**

## Connections

- Microgrid designer → Config wizard: configures
- Config wizard → Project config: writes config
- Microgrid designer → CLI runner: starts run
- CLI runner → Project config: loads config
- CLI runner → Input data: sets parameters
- CLI runner → Optimizer suite: selects algorithm
- Optimizer suite → PSO: dispatches
- Optimizer suite → ADE: dispatches
- Optimizer suite → ABC: dispatches
- Optimizer suite → Grey Wolf: dispatches
- Simulation results → Energy dispatch: calls dispatch
- Simulation results → EV dispatch: calls EV dispatch
- Input data → Load and weather profiles: provides profiles
- EV dispatch → Battery models: uses models
- EV dispatch → EV demand tools: uses demand
- Tariff calculations → Electricity bills: includes
- Tariff calculations → Service charges: includes
- Tariff calculations → Lifecycle cash flow: includes