Examples
========

This section shows how to use pyFEBiOpt in realistic workflows. Start with the
XPLT examples if you want to understand FEBio result reading and slicing. Move to
the optimization example when you are ready to connect a FEBio template, measured
data, and a SciPy optimizer.

.. note::

   The optimization examples execute FEBio. Make sure ``febio4`` is installed and
   available on ``PATH``, or edit ``FEBIO_COMMAND`` in the example script before
   running it.

What to read first
------------------

``xplt``
   Learn how to open a FEBio ``.xplt`` file, inspect available variables, select
   domains/surfaces/nodesets, and slice by time, item, node, and component. This is
   the foundation for both postprocessing and optimization adapters.

``optimization``
   Learn how an optimization script is assembled: experimental series,
   ``ParameterSpace``, FEB template bindings, simulation cases, adapters,
   ``EngineOptions``, monitoring, and final artifacts.

Runnable scripts
----------------

The repository includes two optimization scripts:

``examples/simple_biaxial_fit.py``
   Minimal biaxial fit. It fits one material parameter, reads ``stress`` from the
   generated ``.xplt`` file, and demonstrates the basic Engine workflow.

``examples/simple_biaxial_hz_fit.py``
   Holzapfel-Gasser biaxial fit. It discovers material parameters from the FEB
   template, fits two stress components, and shows a larger multi-objective setup.

Run an example
--------------

From the repository root:

.. code-block:: bash

   python examples/simple_biaxial_fit.py

Expected outputs depend on the configured storage mode, but optimization runs
normally produce:

- console progress from the optimizer,
- ``optimization.log`` under the work directory,
- exported ``results/*.txt`` series,
- final FEBio artifacts under ``optimized_simulations/`` when final export runs,
- live run information in the monitor when ``MonitorOptions(enabled=True)`` is set.

How examples relate to the API
------------------------------

Examples intentionally use the public API:

- ``pyfebiopt.xplt.xplt`` for result reading,
- ``pyfebiopt.optimize`` classes for optimization setup,
- ``SimulationAdapter`` to connect XPLT postprocessing to residual assembly,
- ``MonitorOptions`` and ``pyfebiopt-monitor`` for live run monitoring.

Use the generated API reference when you need exact constructor signatures or
method details.

.. toctree::
   :maxdepth: 1

   xplt
   optimization