# kgreen7/nzupy architecture

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

- Interactive diagram: https://gitdiagram.com/kgreen7/nzupy
- Repository: https://github.com/kgreen7/nzupy

## Overview

NZUpy is a Python model for projecting and balancing NZ ETS unit supply and demand. A user configures years, scenarios and component assumptions through the NZUpy API, then runs scenarios to obtain price, emissions, supply and stockpile results; chart tools present those outputs. The graph preserves the documented supply and demand stages, scenario and optimisation machinery, data/configuration layer, and visualisation capabilities. Some source was unsampled, so links not established by excerpts or README are omitted; dashed links mark documented capabilities whose internal calls were not shown.

Main entry points: [`model/core/base_model.py`](https://github.com/kgreen7/nzupy/blob/main/model/core/base_model.py) (NZUpy API), [`model/interface/chart_generator.py`](https://github.com/kgreen7/nzupy/blob/main/model/interface/chart_generator.py) (Chart generator), [`model/core/runner.py`](https://github.com/kgreen7/nzupy/blob/main/model/core/runner.py) (Model runner), [`model/core/calculation_engine.py`](https://github.com/kgreen7/nzupy/blob/main/model/core/calculation_engine.py) (Calculation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Model orchestration"]
  node_api["NZUpy API<br/>[base_model.py]"]
  node_scenarios["Scenario manager"]
  node_runner["Model runner<br/>[runner.py]"]
  node_engine["Calculation engine"]
  node_optimiser["Price optimiser<br/>[optimiser.py]"]
end

subgraph group_supply["Supply components"]
  node_auction["Auctions<br/>[auction.py]"]
  node_industrial["Industrial allocation<br/>[industrial.py]"]
  node_forestry["Forestry response<br/>[forestry.py]"]
  node_stockpile["Stockpile dynamics<br/>[stockpile.py]"]
end

subgraph group_demand["Demand components"]
  node_emissions["Baseline emissions<br/>[emissions.py]"]
  node_response["Price response<br/>[price_response.py]"]
end

subgraph group_data["Configuration and data"]
  node_config["Model configuration<br/>[config.py]"]
  node_datahandler["Input data handler<br/>[data_handler.py]"]
  node_priceconvert["Price conversion<br/>[price_convert.py]"]
end

subgraph group_results["Results and charts"]
  node_formatter["Output formatter<br/>[output_format.py]"]
  node_chartgen["Chart generator<br/>[chart_generator.py]"]
  node_singlecharts["Single-run charts<br/>[single_charts.py]"]
  node_rangecharts["Range charts<br/>[range_charts.py]"]
  node_chartconfig["Chart configuration<br/>[chart_config.py]"]
end

node_user(("Model user"))

node_user -->|"configures and runs"| node_api
node_api -.->|"manages scenarios"| node_scenarios
node_api -->|"runs model"| node_runner
node_api -->|"evaluates gap"| node_engine
node_engine -->|"calculates stockpile"| node_stockpile
node_runner -.->|"uses optimiser"| node_optimiser
node_api -.->|"configures supply"| node_auction
node_api -.->|"configures supply"| node_industrial
node_api -.->|"configures supply"| node_forestry
node_api -.->|"configures supply"| node_stockpile
node_api -.->|"configures demand"| node_emissions
node_api -.->|"configures demand"| node_response
node_api -.->|"loads inputs"| node_datahandler
node_datahandler -.->|"uses conversion"| node_priceconvert
node_api -.->|"formats results"| node_formatter
node_user -->|"requests charts"| node_chartgen
node_chartgen -.->|"renders single runs"| node_singlecharts
node_chartgen -.->|"renders ranges"| node_rangecharts
node_singlecharts -.->|"uses styles"| node_chartconfig
node_rangecharts -.->|"uses styles"| node_chartconfig

click node_api "https://github.com/kgreen7/nzupy/blob/main/model/core/base_model.py"
click node_scenarios "https://github.com/kgreen7/nzupy/blob/main/model/core/scenario_manager.py"
click node_runner "https://github.com/kgreen7/nzupy/blob/main/model/core/runner.py"
click node_engine "https://github.com/kgreen7/nzupy/blob/main/model/core/calculation_engine.py"
click node_optimiser "https://github.com/kgreen7/nzupy/blob/main/model/core/optimiser.py"
click node_auction "https://github.com/kgreen7/nzupy/blob/main/model/supply/auction.py"
click node_industrial "https://github.com/kgreen7/nzupy/blob/main/model/supply/industrial.py"
click node_forestry "https://github.com/kgreen7/nzupy/blob/main/model/supply/forestry.py"
click node_stockpile "https://github.com/kgreen7/nzupy/blob/main/model/supply/stockpile.py"
click node_emissions "https://github.com/kgreen7/nzupy/blob/main/model/demand/emissions.py"
click node_response "https://github.com/kgreen7/nzupy/blob/main/model/demand/price_response.py"
click node_config "https://github.com/kgreen7/nzupy/blob/main/model/config.py"
click node_datahandler "https://github.com/kgreen7/nzupy/blob/main/model/utils/data_handler.py"
click node_priceconvert "https://github.com/kgreen7/nzupy/blob/main/model/utils/price_convert.py"
click node_formatter "https://github.com/kgreen7/nzupy/blob/main/model/utils/output_format.py"
click node_chartgen "https://github.com/kgreen7/nzupy/blob/main/model/interface/chart_generator.py"
click node_singlecharts "https://github.com/kgreen7/nzupy/blob/main/model/interface/single_charts.py"
click node_rangecharts "https://github.com/kgreen7/nzupy/blob/main/model/interface/range_charts.py"
click node_chartconfig "https://github.com/kgreen7/nzupy/blob/main/model/interface/chart_config.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_api,node_scenarios,node_runner,node_engine,node_optimiser,node_user toneBlue
class node_auction,node_industrial,node_forestry,node_stockpile toneAmber
class node_emissions,node_response toneMint
class node_config,node_datahandler,node_priceconvert toneRose
class node_formatter,node_chartgen,node_singlecharts,node_rangecharts,node_chartconfig toneIndigo
```

## Components

### Model orchestration

- [NZUpy API](https://github.com/kgreen7/nzupy/blob/main/model/core/base_model.py): `model/core/base_model.py`
- [Scenario manager](https://github.com/kgreen7/nzupy/blob/main/model/core/scenario_manager.py): `model/core/scenario_manager.py`
- [Model runner](https://github.com/kgreen7/nzupy/blob/main/model/core/runner.py): `model/core/runner.py`
- [Calculation engine](https://github.com/kgreen7/nzupy/blob/main/model/core/calculation_engine.py): `model/core/calculation_engine.py`
- [Price optimiser](https://github.com/kgreen7/nzupy/blob/main/model/core/optimiser.py): `model/core/optimiser.py`

### Supply components

- [Auctions](https://github.com/kgreen7/nzupy/blob/main/model/supply/auction.py): `model/supply/auction.py`
- [Industrial allocation](https://github.com/kgreen7/nzupy/blob/main/model/supply/industrial.py): `model/supply/industrial.py`
- [Forestry response](https://github.com/kgreen7/nzupy/blob/main/model/supply/forestry.py): `model/supply/forestry.py`
- [Stockpile dynamics](https://github.com/kgreen7/nzupy/blob/main/model/supply/stockpile.py): `model/supply/stockpile.py`

### Demand components

- [Baseline emissions](https://github.com/kgreen7/nzupy/blob/main/model/demand/emissions.py): `model/demand/emissions.py`
- [Price response](https://github.com/kgreen7/nzupy/blob/main/model/demand/price_response.py): `model/demand/price_response.py`

### Configuration and data

- [Model configuration](https://github.com/kgreen7/nzupy/blob/main/model/config.py): `model/config.py`
- [Input data handler](https://github.com/kgreen7/nzupy/blob/main/model/utils/data_handler.py): `model/utils/data_handler.py`
- [Price conversion](https://github.com/kgreen7/nzupy/blob/main/model/utils/price_convert.py): `model/utils/price_convert.py`

### Results and charts

- [Output formatter](https://github.com/kgreen7/nzupy/blob/main/model/utils/output_format.py): `model/utils/output_format.py`
- [Chart generator](https://github.com/kgreen7/nzupy/blob/main/model/interface/chart_generator.py): `model/interface/chart_generator.py`
- [Single-run charts](https://github.com/kgreen7/nzupy/blob/main/model/interface/single_charts.py): `model/interface/single_charts.py`
- [Range charts](https://github.com/kgreen7/nzupy/blob/main/model/interface/range_charts.py): `model/interface/range_charts.py`
- [Chart configuration](https://github.com/kgreen7/nzupy/blob/main/model/interface/chart_config.py): `model/interface/chart_config.py`

### Other components

- **Model user**

## Connections

- Model user → NZUpy API: configures and runs (evidence: `README.md`)
- NZUpy API → Scenario manager: manages scenarios (evidence: `model/core/base_model.py`)
- NZUpy API → Model runner: runs model (evidence: `model/core/base_model.py`)
- NZUpy API → Calculation engine: evaluates gap (evidence: `model/core/base_model.py`)
- Calculation engine → Stockpile dynamics: calculates stockpile (evidence: `model/core/calculation_engine.py`)
- Model runner → Price optimiser: uses optimiser (evidence: `model/core/runner.py`)
- NZUpy API → Auctions: configures supply (evidence: `model/core/base_model.py`)
- NZUpy API → Industrial allocation: configures supply (evidence: `model/core/base_model.py`)
- NZUpy API → Forestry response: configures supply (evidence: `model/core/base_model.py`)
- NZUpy API → Stockpile dynamics: configures supply (evidence: `model/core/base_model.py`)
- NZUpy API → Baseline emissions: configures demand (evidence: `model/core/base_model.py`)
- NZUpy API → Price response: configures demand (evidence: `model/core/base_model.py`)
- NZUpy API → Input data handler: loads inputs (evidence: `model/core/base_model.py`)
- Input data handler → Price conversion: uses conversion (evidence: `model/utils/data_handler.py`)
- NZUpy API → Output formatter: formats results (evidence: `model/core/base_model.py`)
- Model user → Chart generator: requests charts (evidence: `README.md`)
- Chart generator → Single-run charts: renders single runs (evidence: `model/interface/chart_generator.py`)
- Chart generator → Range charts: renders ranges (evidence: `model/interface/chart_generator.py`)
- Single-run charts → Chart configuration: uses styles (evidence: `model/interface/single_charts.py`)
- Range charts → Chart configuration: uses styles (evidence: `model/interface/range_charts.py`)
