.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/model_inspection/plot_history_in.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_model_inspection_plot_history_in.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_model_inspection_plot_history_in.py:


Plot training history with robust grouping and scale handling
=============================================================

This example teaches you how to use GeoPrior's
``plot_history_in`` helper.

Unlike the plot scripts in ``figure_generation/``, this function is a
small model-inspection utility. It is designed for training logs and
history dictionaries rather than paper-ready figure builders.

Why this matters
----------------
Training histories often contain a mixture of:

- headline losses,
- task-specific losses,
- physics diagnostics,
- validation curves,
- and sometimes values that cross zero.

This helper makes those histories easier to inspect because it:

- accepts History-like or dict-like inputs,
- groups metrics automatically or from user-defined groups,
- auto-adds validation curves,
- and handles log-like scaling safely.

.. GENERATED FROM PYTHON SOURCE LINES 31-35

Imports
-------
We call the real plotting helper from the package and feed it a
compact synthetic history dictionary.

.. GENERATED FROM PYTHON SOURCE LINES 35-45

.. code-block:: Python


    from __future__ import annotations

    import tempfile
    from pathlib import Path

    import numpy as np

    from geoprior.models import plot_history








.. GENERATED FROM PYTHON SOURCE LINES 46-67

Build a compact synthetic training history
------------------------------------------
The helper accepts either:

- a Keras ``History`` object,
- a plain dict,
- or any object exposing ``.history`` as a dict.

For the lesson page, a plain dict is the simplest choice.

We include:

- total losses,
- task losses,
- physics losses,
- epsilon diagnostics,
- validation curves.

The epsilon series intentionally includes values near zero and a
small negative value so the requested log scale will safely fall
back to ``symlog`` for that subplot.

.. GENERATED FROM PYTHON SOURCE LINES 67-199

.. code-block:: Python


    epochs = np.arange(1, 13, dtype=int)

    loss = np.array(
        [
            2.40,
            1.92,
            1.55,
            1.28,
            1.06,
            0.92,
            0.82,
            0.74,
            0.68,
            0.64,
            0.61,
            0.58,
        ],
        dtype=float,
    )

    val_loss = np.array(
        [
            2.55,
            2.05,
            1.68,
            1.42,
            1.20,
            1.06,
            0.96,
            0.90,
            0.86,
            0.83,
            0.81,
            0.80,
        ],
        dtype=float,
    )

    history = {
        "loss": loss.tolist(),
        "val_loss": val_loss.tolist(),
        "subs_pred_loss": (
            0.74 * loss + 0.02 * np.sin(epochs)
        ).tolist(),
        "val_subs_pred_loss": (
            0.77 * val_loss + 0.02 * np.cos(epochs)
        ).tolist(),
        "gwl_pred_loss": (
            0.46 * loss + 0.02 * np.cos(epochs / 2.0)
        ).tolist(),
        "val_gwl_pred_loss": (
            0.48 * val_loss + 0.02 * np.sin(epochs / 2.0)
        ).tolist(),
        "physics_loss": (
            np.array(
                [
                    0.82,
                    0.64,
                    0.49,
                    0.37,
                    0.28,
                    0.22,
                    0.18,
                    0.15,
                    0.13,
                    0.12,
                    0.11,
                    0.10,
                ]
            )
        ).tolist(),
        "physics_loss_scaled": (
            np.array(
                [
                    0.40,
                    0.33,
                    0.27,
                    0.21,
                    0.17,
                    0.14,
                    0.12,
                    0.11,
                    0.10,
                    0.095,
                    0.090,
                    0.086,
                ]
            )
        ).tolist(),
        "epsilon_prior": (
            np.array(
                [
                    0.21,
                    0.17,
                    0.13,
                    0.09,
                    0.06,
                    0.04,
                    0.02,
                    0.01,
                    0.005,
                    0.000,
                    -0.003,
                    0.002,
                ]
            )
        ).tolist(),
        "epsilon_cons": (
            np.array(
                [
                    0.16,
                    0.13,
                    0.10,
                    0.08,
                    0.06,
                    0.045,
                    0.032,
                    0.020,
                    0.012,
                    0.008,
                    0.004,
                    0.002,
                ]
            )
        ).tolist(),
    }

    print("History keys")
    for k in history:
        print(" -", k)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    History keys
     - loss
     - val_loss
     - subs_pred_loss
     - val_subs_pred_loss
     - gwl_pred_loss
     - val_gwl_pred_loss
     - physics_loss
     - physics_loss_scaled
     - epsilon_prior
     - epsilon_cons




.. GENERATED FROM PYTHON SOURCE LINES 200-212

Plot a grouped inspection dashboard
-----------------------------------
Here we provide explicit groups so the figure reads like a compact
training dashboard.

Two useful points to notice:

- the helper automatically adds validation curves for the non-val
  keys in each group;
- the epsilon panel requests ``log`` scaling, but because one
  series touches or crosses zero, the helper safely switches that
  subplot to ``symlog``.

.. GENERATED FROM PYTHON SOURCE LINES 212-252

.. code-block:: Python


    groups = {
        "Losses": [
            "loss",
            "subs_pred_loss",
            "gwl_pred_loss",
        ],
        "Physics": [
            "physics_loss",
            "physics_loss_scaled",
        ],
        "Epsilons": [
            "epsilon_prior",
            "epsilon_cons",
        ],
    }

    ysc = {
        "Losses": "log",
        "Physics": "log",
        "Epsilons": "log",
    }

    plot_history(
        history,
        metrics=groups,
        layout="subplots",
        title="GeoPrior training dashboard",
        max_cols=2,
        show_grid=True,
        grid_props={
            "linestyle": ":",
            "alpha": 0.55,
        },
        yscale_settings=ysc,
        linewidth=1.8,
        marker="o",
        markersize=3,
    )




.. image-sg:: /auto_examples/model_inspection/images/sphx_glr_plot_history_in_001.png
   :alt: GeoPrior training dashboard, Losses, Physics, Epsilons
   :srcset: /auto_examples/model_inspection/images/sphx_glr_plot_history_in_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 253-265

Let the helper auto-group the history
-------------------------------------
If ``metrics=None``, the function creates groups automatically.

Its default rule is simple:

- keys containing ``loss`` go into a shared ``Losses`` group;
- other non-validation keys become their own titled groups.

We save that second figure to disk to demonstrate the helper's
save behavior. When the path has no extension, the function adds
``.png`` automatically.

.. GENERATED FROM PYTHON SOURCE LINES 265-288

.. code-block:: Python


    tmp_dir = Path(
        tempfile.mkdtemp(prefix="gp_sg_plot_history_")
    )
    save_stem = tmp_dir / "history_autogroup"

    plot_history(
        history,
        metrics=None,
        layout="subplots",
        title="Auto-grouped history view",
        max_cols=3,
        style="default",
        savefig=str(save_stem),
        linewidth=1.5,
    )

    saved_png = tmp_dir / "history_autogroup.png"

    print("")
    print("Saved file")
    print(" -", saved_png)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    [OK] Saved figure -> /tmp/gp_sg_plot_history_f1adi742/history_autogroup.png

    Saved file
     - /tmp/gp_sg_plot_history_f1adi742/history_autogroup.png




.. GENERATED FROM PYTHON SOURCE LINES 289-302

Learn how to read the grouped dashboard
---------------------------------------
A good reading order is:

1. start with the total loss panel;
2. compare task-specific losses to see which head is harder to fit;
3. inspect the physics panel to see whether the physics objective is
   stabilizing;
4. inspect the epsilon panel to see whether the residual-style
   diagnostics are shrinking, oscillating, or crossing zero.

This is why the grouped layout is often more useful than a single
all-metrics figure.

.. GENERATED FROM PYTHON SOURCE LINES 304-317

Why the safe log handling matters
---------------------------------
Training diagnostics are often positive at the beginning and then
drift toward zero, and some residual-like quantities may even cross
zero.

A strict log axis would fail or hide those values.
This helper instead:

- uses ``log`` when the subplot data are strictly positive;
- otherwise falls back to ``symlog``.

That makes it much safer for physics-oriented training histories.

.. GENERATED FROM PYTHON SOURCE LINES 319-333

Why this page belongs in model_inspection
-----------------------------------------
This helper is not a paper-figure script and it is not an artifact
builder.

Its role is to inspect:

- optimization behavior,
- validation drift,
- and physics-diagnostic evolution

during or after training.

So it fits naturally in a model-inspection section.

.. GENERATED FROM PYTHON SOURCE LINES 335-343

A natural next lesson
---------------------
After this page, the clean next lessons are:

- ``plot_epsilons_in.py``
- ``plot_physics_losses_in.py``

because both are thin, task-specific wrappers around
``plot_history_in(...)``.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 1.341 seconds)


.. _sphx_glr_download_auto_examples_model_inspection_plot_history_in.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_history_in.ipynb <plot_history_in.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_history_in.py <plot_history_in.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_history_in.zip <plot_history_in.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_