# Architecture

This page describes what each module in `pyflow_acdc` owns, and how the
layers depend on one another. It is a developer-oriented map, not an API
reference (see the API pages for signatures).

## Layering overview

```
constants  →  Classes  →  grid_creator / grid_modifications / grid_analysis
                  │
                  ├─→  ACDC_PF                      (power flow)
                  ├─→  pyomo_model_solve              (generic Pyomo solve)
                  ├─→  ACDC_OPF (+ NL / L models)   (optimal power flow)
                  ├─→  ACDC_*_TEP / Array_OPT        (planning / sizing)
                  ├─→  Time_series(_clustering)      (time-series studies)
                  └─→  Results_class / Export_files / Graph_* / Mapping  (output)
```

Lower layers never import from higher layers. `constants` is a leaf module
(no intra-package imports); `Classes` is the shared data model that almost
everything else builds on.

## Core model and construction

- **`constants.py`** — Single source of truth for domain constants and
  string enums (`NodeType`, `ConverterDCType`, `DataInput`, `Polarity`,
  `PowerLossModel`, `CableType`, `ConverterOpfFxType`, `AcDcSide`,
  `PriceZoneCategory`, `ObjComponent`, `CssMode`, `MIPBackend`,
  `PricingStrategy`, `TSType`), default tuples, tolerances/iteration caps,
  and shared helpers (`present_value_factor`, `default_obj_weights`).
  Owns: magic-value/string centralisation. Does not own: any grid logic.
- **`Classes.py`** — The data model: `Grid` plus element classes
  (`Node_AC/DC`, `Line_AC/DC`, `AC_DC_converter`, `Gen_AC/DC`, `Ren_Source`,
  `Price_Zone` and subclasses, `TimeSeries`, cable/sizing helpers). Owns
  per-object state and derived electrical quantities (e.g. `Ybus`).
- **`grid_creator.py`** — Build a `Grid` from data tables, MATPOWER `.mat`
  files, pickles, or a turbine graph. Owns import/parsing.
- **`grid_modifications.py`** — Add or mutate elements after creation
  (`add_*`, line-type conversions, time/investment series wiring).
- **`grid_analysis.py`** — Topology/analysis utilities: `analyse_grid`,
  coordinate transforms (`pol2cart`/`cart2pol`/…), `Cable_parameters`,
  `Converter_parameters`, fuel-mix distribution.

## Analysis engines

- **`ACDC_PF.py`** — Power flow: `power_flow`, `ac_power_flow`,
  `dc_power_flow`, `acdc_sequential` (aliases `Power_flow`, etc. remain for
  backward compatibility). Pure Numpy no pyomo needed.
- **`ACDC_OPF.py`** — OPF orchestration: `optimal_pf` / `optimal_l_pf`,
  objective assembly (`obj_w_rule`, `opf_obj`), result translation back onto the
  `Grid` (`translate_pyf_opf`, `opf_line_res`, …). Calls
  `pyomo_model_solve` for the actual solve.
- **`pyomo_model_solve.py`** — Generic Pyomo solve layer shared by OPF, TEP,
  array, and time-series drivers: `pyomo_model_solve`, solver log parsers,
  feasibility checks, `reset_to_initialize`, `export_solver_progress_to_excel`.
  Distinct from `solver_utils.py` (environment probe only).
- **`ACDC_OPF_NL_model.py`** — Builds the non-linear Pyomo model (full AC/DC
  physics, converters, price zones, optional TEP variables).
- **`AC_OPF_L_model.py`** — Builds the linear (DC-style) Pyomo model with
  McCormick linearisations for cable-type selection.

## Planning and sizing

- **`ACDC_Static_TEP.py`** — Static transmission-expansion planning and
  multi-scenario TEP; sensitivity analyses.
- **`ACDC_MultiPeriod_TEP.py`** — Multi-period (investment-horizon) TEP.
- **`ACDC_sequential_STEP.py`** — Sequential static TEP runs over time.
- **`ACDC_TEP_pymoo.py`** — Population-based (pymoo) outer TEP with OPF
  subproblems.
- **`Array_OPT.py`** — Offshore inter-array sizing orchestration: **route**
  MIP (``MIP_path_graph``, Pyomo or OR-Tools CP-SAT; optional joint cable types
  via ``enable_cable_types``) and **CSS** dispatch (``wind_farm_CSS``,
  ``sequential_CSS``). Owns spanning-tree / flow / ``ct_limit`` constraints.
  Install ``[OPF]`` for Pyomo CSS; ``[LINEAR_ARRAY]`` for OR-Tools MIP/CSS + HiGHS.
- **`AC_L_CSS_ortools.py`** — OR-Tools ``linear_solver`` CSS only: cable type
  per active CT line on a fixed topology; no routing. Used when
  ``CSS_L_solver='ortools'``.
- **`_tep_utils.py`** — Shared TEP economics (annuity/present-value factor).

## Time series

- **`Time_series.py`** — Time-series power flow / OPF drivers and result
  aggregation.
- **`Time_series_clustering.py`** — Representative-period clustering of
  time-series inputs.
- **`Market_Coeff.py`** — Price-zone quadratic cost curves from EPEX order books
  and ENTSO-E day-ahead CSVs (`price_zone_coef_data`, `clean_entsoe_data`, …).

## Output and visualisation

- **`Results_class.py`** — `Results` container and reporting tables.
- **`Export_files.py`** — Export a grid to runnable Python, MATLAB, or
  pickle; code generation for loaders.
- **`Graph_and_plot.py`** — Static / Plotly network and result plots.
- **`Graph_Dash.py`** — Interactive Dash applications.
- **`Mapping.py`** — Geographic (folium) maps.

## Support

- **`windfarm_loader.py`** — Load a bundled wind-farm case grid plus its
  GeoJSON context.
- **`solver_utils.py`** — Detect available Pyomo solvers and OR-Tools backends
  (does not run models).
- **`__init__.py`** — Public API surface (`__all__`), optional-dependency
  guards, and the `cases` example-grid loader.

## Conventions

- Optional dependencies are imported behind `try/except ImportError` with
  feature flags (`HAS_OPF`, `HAS_DASH`, …). New optional features follow the
  same pattern.
- Public string values that form a closed vocabulary live in `constants.py`
  as `(str, Enum)` members. Stored attributes / dict keys use `.value`
  (plain strings) to preserve serialization; comparisons use the enum member.
- See `CONTRIBUTING.md` for coding and testing expectations.