User guide
==========

CaNN is built around a small set of user-facing concepts.

Core concepts
-------------

- ``TrainedModel``: a trained surrogate + the ``ModelConfig`` it was trained with.
- ``ModelConfig``: parameter bounds and the *ordering* of model inputs/outputs.
- ``MarketSurface``: observed market data to calibrate to.
- ``CalibrationConfig``: optimizer and batching settings for calibration.
- ``TrainingConfig``: training hyperparameters for building a surrogate.

Data layout (important)

The columns of ``MarketSurface.market_inputs`` must match the ordering specified by
``trained_model.model_config.market_inputs``.

If you pass the right values in the wrong order, calibration will still run but produce nonsense.

Typical workflow
----------------

Forward pass (offline learning)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Train a surrogate from synthetic or historical data (see :doc:`examples`).
2. Save the trained weights as an artifact for later reuse.

Backward pass (online calibration)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Load a pretrained surrogate (or one you trained offline).
2. Build a ``MarketSurface`` with ``market_inputs`` and ``observed``.
3. Run ``calibrate_model``.
4. Validate the fit by predicting the surface using the calibrated parameters.

Where to look next
------------------

- Examples: see :doc:`examples`.
- Architecture / implementation details: see :doc:`design`.
- API reference: see :doc:`api/index`.