Read FEBio results with XPLT
============================

Purpose
-------

The ``pyfebiopt.xplt`` module reads FEBio ``.xplt`` files and exposes result data
as sliceable views. Use it directly for postprocessing, or inside optimization
adapters when an objective needs values from a FEBio run.

Reader pipeline
---------------

1. Parse the file header and dictionary to discover variable names, storage
   formats, and whether each variable is nodal, elemental, facial, or regional.
2. Parse mesh data: nodes, domains, surfaces, node sets, connectivity, and name
   lookup tables.
3. Load all states with ``readAllStates()`` or selected states with
   ``readSteps([...])``.
4. Build ``Results`` views at ``xp.results`` so variables can be sliced by time,
   region, item, node, and component.

Basic read
----------

.. code-block:: python

   import numpy as np

   from pyfebiopt.xplt import xplt

   xp = xplt("run.xplt")
   xp.readAllStates()

   displacement = xp.results["displacement"]
   tip_z = displacement.time(-1).nodes(-1).comp("z")
   tip_z = np.asarray(tip_z, dtype=float)

Selectors
---------

``time(sel)``
   Selects one state, several states, or all states with ``":"``.

``nodes(sel)`` and ``nodeset(name)``
   Select nodal values by node index or named FEBio node set.

``domain(name)`` and ``surface(name)``
   Select element or face results by named domain/surface.

``items(sel)``, ``elems(sel)``, ``faces(sel)``, and ``enodes(sel)``
   Select element, face, or element-node axes depending on the variable storage.

``comp(sel)``
   Select result components. Vector components use ``"x"``, ``"y"``, ``"z"``;
   symmetric tensor components use tokens such as ``"xx"``, ``"yy"``, ``"zz"``,
   ``"xy"``, ``"yz"``, and ``"xz"``.

Element result example
----------------------

.. code-block:: python

   xp = xplt("run.xplt")
   xp.readAllStates()

   stress = xp.results["stress"].domain("sample")
   sigma_xx = stress.time(":").items(0).comp("xx")
   time = np.asarray(xp._time, dtype=float)

The view API keeps slicing lazy until values are evaluated, which makes it usable
for large outputs. Missing variables on selected states are represented with
``NaN`` arrays of the expected shape so downstream array code can stay vectorized.

Read more in the API
--------------------

For full class and method details, see the generated
:doc:`XPLT API reference <../api/pyfebiopt/xplt/index>`, especially
:doc:`the reader entry point <../api/pyfebiopt/xplt/xplt/index>` and
:doc:`result view classes <../api/pyfebiopt/xplt/views/index>`.