#############################################
First inversion with the toy Gaussian model
#############################################

After running a :doc:`first forward run<../first-simu/index>` with perturbed outputs from known emissions
using the :doc:`Toy Gaussian Model</documentation/plugins/models/dummy>`,
you can carry out an academic inversion using these "true" observations.

This tutorial uses the **4D-VAR algorithm with the M1QN3 quasi-Newton minimizer** —
the most commonly used variational method in atmospheric inversions.
For a comparison of all algorithms available in pyCIF, see
:doc:`comparing-algorithms`.

.. contents::
   :local:

Prerequisites
=============

You need a completed forward simulation (see :doc:`../first-simu/toy-gaussian`)
whose output ``obsvect`` directory will serve as the observation vector for the inversion.

Step 1 — Prepare the observation vector
=========================================

Copy the ``obsvect`` directory from the ``workdir`` of your forward simulation
and rename it to ``ref_obsvect`` inside the same ``outdir``:

.. code-block:: bash

    cp -r $outdir/fwd_long_noMCF/obsvect $outdir/ref_obsvect

The inversion YAML references this directory via its ``obsvect/dir_obsvect`` key.

Step 2 — Set up the YAML configuration
========================================

Download the reference YAML:

* :doc:`4D-VAR inversion, full-pixel control vector, M1QN3 minimizer</yaml-examples/dummy/config_inversion_long_full_4dvar_M1QN3>`

Edit the following two paths to match your environment:

.. code-block:: yaml

    rootdir: &rootdir /path/to/CIF/
    outdir: &outdir   /path/to/output/dir/

Everything else — the model, observation operator, and data vector — is already
configured for the same 5-day Toy Gaussian setup used in the forward tutorial.

Step 3 — Run the inversion
============================

.. code-block:: bash

    python -m pycif path/to/config_inversion_long_full_4dvar_M1QN3.yml

.. warning::

    Before running a real inversion with a new model configuration, always
    :doc:`test the adjoint<../testing-codes/index>` first.
    The Toy Gaussian model is already validated, so you can skip this step here.

Step 4 — Explore the outputs
==============================

After convergence, ``workdir`` (``$outdir/inversion_long_full_4dvar_M1QN3/``) contains:

.. code-block:: text

    workdir/
    ├── controlvect/
    │   ├── flux/CH4/
    │   │   └── controlvect_flux_CH4.nc   optimized fluxes (x, xb, x_phys, xb_phys)
    │   └── simulator/
    │       ├── cost.txt                  cost function J at each iteration
    │       └── gradcost.txt              gradient norm ‖∇J‖ at each iteration
    └── obsoperator/
        ├── fwd_-001/obsvect/             prior simulated concentrations
        └── fwd_-002/obsvect/             posterior simulated concentrations

Open ``controlvect/flux/CH4/controlvect_flux_CH4.nc`` in any NetCDF viewer
(``ncview``, ``xarray``) to compare the prior fluxes ``xb_phys`` with the
optimised fluxes ``x_phys``.

.. note::

    A perfect retrieval is unlikely with only 5 stations and a short 5-day window.
    Try increasing ``nstations`` in the data vector to see how observational density
    affects the inversion quality.

Posterior uncertainties (Monte Carlo)
---------------------------------------

The YAML includes a ``mode/montecarlo`` block that estimates posterior uncertainties
by running the inversion on perturbed copies of the observation vector.
The result is stored in ``controlvect/flux/CH4/controlvect_flux_CH4.nc``
as the variable ``pa_std`` (posterior standard deviation).

To disable this (faster run), comment out the ``montecarlo`` block in the YAML.

=============
Going further
=============

* **Other inversion algorithms** — See :doc:`comparing-algorithms` for 4D-VAR with the
  conjugate-gradient minimizer, the analytical solution, and the EnSRF ensemble method.

* **Spatial resolution of the control vector** — The control vector can work at
  full-pixel resolution (``hpixels``), aggregated spatial bands (``ibands``), or
  a single global scalar (``global``).  All three variants are available in
  :doc:`/yaml-examples/dummy/index` (look for ``_full_``, ``_bands_``, ``_global_``
  in the YAML names).

* **Article-quality benchmark** — The CI ``article`` and ``article-uncertainties``
  jobs run all algorithms across all resolutions and generate publication-quality
  figures.  See :doc:`../further-inversions/article-examples`.

* **All dummy YAML examples** — :doc:`/yaml-examples/dummy/index`