Project Structure

GreenFlux is organized by physical domain rather than by one large monolithic simulation file.

Core Packages

• greenflux.crop: tomato crop biomass and staged fruit development.
• greenflux.equations: pure scalar equations and correlations, including psychrometrics, optical functions and fluid-flow heat-transfer correlations.
• greenflux.flows: coupled transfer equations for heat, vapour, CO2 and ventilation.
• greenflux.components: physical component models such as air zones, cover, canopy, floor, thermal screen and solar balance.
• greenflux.controls: climate, low-level and HVAC control logic.
• greenflux.actuation: shared physical actuator command objects used by controls, management policies and problem environments. This centralizes the language of actions without embedding decision logic.
• greenflux.management: high-level operational policies that produce actuation commands, such as static or day/night management schedules.
• greenflux.equipment: first-class greenhouse equipment models such as lamps, boilers, heat pumps, pipe circuits, screens, ventilation, humidity control, CO2 sources and irrigation/fertigation devices.
• greenflux.fluid: finite-volume fluid cells, discretized walls and thermal storage components used to assemble hydraulic or air-side equipment models.
• greenflux.rootzone: substrate/root-zone water balance, drainage and water stress helpers.
• greenflux.systems.greenhouse_unit: explicit greenhouse unit assembly. This is the first reusable Python composition layer over the scalar component ports.
• greenflux.systems.examples: executable greenhouse/global-system scenarios.
• greenflux.systems.greenhouse_1: traceable Python approximation of Greenhouses.Examples.Greenhouse_1 with Modelica variable mapping, component inventory and time-series export.
• greenflux.simulators: generic fixed-step simulation engines and result records for systems following the Parameters/State/Inputs/Fluxes/StepResult convention, plus optional SciPy adapters for adaptive vector ODE integration.
• greenflux.graph and greenflux.graph_builders: residual graph primitives plus reusable assembly helpers for port-level component connections.
• greenflux.config: validated user-facing configuration objects. The dataclass layer is dependency-free; the optional Pydantic layer is enabled by the config extra.
• greenflux.projects: project-level definitions for site, geometry, envelope, equipment, crop and named simulation cases. This is the project definition layer used before building executable model parameters.
• greenflux.problems: problem-centric wrappers over projects. A greenhouse problem binds one project, one simulation case, an objective, actuation schedule, weather forcing and initial conditions into a deterministic environment.
• greenflux.experiments: reproducible experiment packages that run one problem and emit compact summaries with objective metrics, final observations and provenance. Experiments are also the intended unit for generated ML datasets, including baseline, perturbed, fault-injected and sensor-subset runs.
• greenflux.benchmarks: benchmark collections for running comparable experiments against metric thresholds. Benchmarks are the natural place to compare controllers, anomaly detectors, fault-diagnosis tasks and public validation contracts.
• greenflux.calibration: calibration dataset registry and hardcoded coefficient audit metadata. This keeps dataset recommendations and calibratable-coefficient status available to code, tests and future CLI reports.
• greenflux.io: optional exporters for analysis-oriented result formats such as xarray.Dataset, including crop/biomass exporters with a dedicated fruit-stage dimension.
• greenflux.weather: EPW/TMY weather management through optional pvlib, normalized into greenhouse forcing records and GreenhouseUnitInputs.
• greenflux.analysis: post-processing, validation metrics, crop/environment calibration workflows, deterministic parameter sweeps and bounded optimization helpers. The reusable optimizer wrapper lives in greenflux.analysis.optimization; model-specific modules should build objectives and bounds on top of it instead of embedding ad hoc optimizers. Dynamic validation metrics live here so generated datasets can be evaluated by level error, increment error, drift and horizon windows.
• greenflux.scenarios: executable scenario runners that turn configuration into repeatable simulations, outputs and validation reports.
• greenflux.cli: command-line entry point for running scenario files.

Internal source-reference helpers are kept separate from the public validation contract. Public validation is based on reproducible Python simulations and measured greenhouse datasets.

Dependency Policy

The core package should stay small and importable for simulation workloads:

• Required: numpy
• Plotting: matplotlib via the plots extra
• Data analysis: pandas and xarray via the data extra
• Numerical solvers: scipy via the simulation extra
• Parameter-search backends: optuna via the optimization extra
• Configuration validation: pydantic via the config extra
• Scenario files: pyyaml via the scenarios extra for YAML; TOML uses the standard library on Python 3.11+ and tomli through the config extra on Python 3.10.
• Energy assets: energydatamodel via the edm extra
• Units: pint via the units extra
• Psychrometric cross-checks: psychrolib via the psychrometrics extra
• Thermodynamic humid-air properties: CoolProp via the psychrometrics or equipment-modeling extra
• Detailed equipment-network backends such as TESPy: document first, then add only behind import-lazy interfaces when a tested equipment model needs them
• Performance experiments: numba via the performance extra

Optional dependencies must have graceful fallbacks or be imported only inside the functions/examples that need them.

Completion Target

Completing the library means three layers are present:

1. Scalar equation ports with unit tests.
2. Reusable component assemblies such as GreenhouseUnit.
3. Measured-data simulation comparisons for greenhouse climate, crop growth, equipment behavior and project workflows.
4. Dataset-generation workflows that preserve physical truth, measurements, controls, equipment response, fault metadata and validation diagnostics. GreenLight, PCSE/WOFOST, AquaCrop, DSSAT and TRNSYS-style greenhouse models, including the prioritized equipment, crop and scenario gaps. and the current coefficient-hardcoding audit. results used to validate the public package. See docs/project_management.md for project definitions and simulation-case workflows. See docs/actuation_management.md for the equipment, actuation, controls and management-policy boundaries. See docs/experiment_framework.md for the problem, experiment and benchmark workflow inspired by enflow/emflow's problem-centric modelling philosophy. control and observability workflow philosophy. See docs/weather_management.md for EPW/TMY weather loading and project-level weather-file references.