Quick Start
===========

This page walks you through running your first pyCIF simulation in a few minutes,
using the built-in **Toy Gaussian model** — a lightweight analytical transport model
that requires no external data or compiled code.

.. tip::

    The fastest way to get started is with the
    :doc:`CIF Docker image </docker/index>`, which ships with all dependencies
    pre-installed.  Pull it with:

    .. code-block:: bash

        docker pull pycif/pycif-ubuntu:latest

    Then jump straight to :ref:`qs-run`.

----

.. _qs-install:

Step 1 — Install pyCIF
-----------------------

If you have not installed pyCIF yet, follow the :doc:`installation guide </installation>`.
The short version:

.. code-block:: bash

    pip install --user pycif-*-py3-none-any.whl   # from a downloaded wheel

or directly from the repository:

.. code-block:: bash

    git clone git@gitlab.in2p3.fr:satinv/cif.git
    cd cif
    pip install --user --editable .

----

.. _qs-config:

Step 2 — Get the example configuration file
--------------------------------------------

Download the ready-made YAML configuration for the toy forward simulation:

:download:`config_fwd_long_noMCF.yml <yaml-examples/dummy/config_fwd_long_noMCF.yml>`

Alternatively, browse it online: :doc:`/yaml-examples/dummy/config_fwd_long_noMCF`.

Open the file and set the two path variables near the top:

.. code-block:: yaml

    rootdir: &rootdir /path/to/cif/sources/   # where pyCIF is installed / cloned
    outdir:  &outdir  /path/to/output/dir/    # where results will be written

Everything else is plug-and-play — no other edits are required for this first run.

----

.. _qs-run:

Step 3 — Run pyCIF
-------------------

.. code-block:: bash

    python -m pycif path/to/config_fwd_long_noMCF.yml

pyCIF will print progress to the terminal and write a log file
(:bash:`pycif.logtest`) in :bash:`outdir`.

The simulation covers five days (2010-01-01 to 2010-01-05) with a Gaussian
plume model, synthetic meteorology and five randomly placed observation stations.
It completes in a few seconds on any modern laptop.

----

.. _qs-outputs:

Step 4 — Explore the outputs
-----------------------------

Results are written to :bash:`${outdir}/fwd_long_noMCF/`:

.. code-block:: text

    fwd_long_noMCF/
    ├── config_fwd_long_noMCF.yml   ← copy of the config used
    ├── pycif.logtest               ← full run log
    ├── VERSION                     ← git commit ID for reproducibility
    ├── controlvect/                ← control-vector data (correlation matrix, …)
    ├── datavect/
    │   ├── fluxes/CH4/             ← input fluxes
    │   └── meteo/                  ← synthetic meteorological fields
    ├── model/
    │   └── H_matrix.pickle         ← saved observation operator matrix
    └── obsoperator/
        └── fwd_0000/
            ├── obsvect/            ← simulated concentrations (monitor.nc)
            └── controlvect/        ← netCDF-format control vector snapshot

Open :bash:`obsoperator/fwd_0000/obsvect/` to find :bash:`monitor.nc` files
containing the simulated concentrations at each station.

----

Next steps
----------

* **More simulations** — explore other models and setups in :doc:`/usertutos/index`.
* **Compare to observations** — see :doc:`/usertutos/first-comp-to-obs/index`.
* **Run an inversion** — see :doc:`/usertutos/first-inversion/index`.
* **Configuration reference** — browse the full YAML syntax in :doc:`/documentation/index`.
* **Plugin catalogue** — find available models, parsers and transforms in
  :doc:`/documentation/plugins/index`.