pyfebiopt.xplt.dictionary
=========================

.. py:module:: pyfebiopt.xplt.dictionary

.. autoapi-nested-parse::

   Dictionary parsing and buffer bootstrap for XPLT.

   The FEBio dictionary announces every variable written in the ``.xplt`` stream.
   Each entry couples a data type (``FEDataType``) with a storage format
   (``Storage_Fmt``) and a location (nodal, elemental, or facial). This module turns
   those announcements into Python structures used everywhere else in ``xplt``:

   - ``read_dictionary`` walks the binary blocks and yields a mapping such as
     ``{"displacement": {"type": "VEC3F", "format": "FMT_NODE"}}`` plus the original
     order and location lookup.
   - ``prepare_field_meta_and_buffers`` converts that mapping into lightweight
     metadata objects and allocates empty buffers keyed by variable and region.

   Example.
   --------
   .. code-block:: python

      reader = BinaryReader("run.xplt")
      dictionary, order, where = read_dictionary(reader)
      field_meta, buffers = prepare_field_meta_and_buffers(dictionary, where)
      # buffers now mirrors FEBio streams:
      # buffers.node_global["displacement"] -> list of per-time arrays

   Notes.
   ------
   - The dictionary order is preserved; consumers can rely on FEBio's output order.
   - Per-domain nodal variables create both ``node_global`` (global scope) and
     ``node_region`` slots so that later parsing can disambiguate based on region id.



Classes
-------

.. autoapisummary::

   pyfebiopt.xplt.dictionary.BufferStore


Functions
---------

.. autoapisummary::

   pyfebiopt.xplt.dictionary.read_dictionary
   pyfebiopt.xplt.dictionary.prepare_field_meta_and_buffers


Module Contents
---------------

.. py:function:: read_dictionary(reader: pyfebiopt.xplt.binary_reader.BinaryReader) -> tuple[dict[str, dict[str, str]], dict[str, list[str]], dict[str, str]]

   Return dictionary mapping, order per kind, and location map.


.. py:class:: BufferStore

   Typed buffers allocated for each variable kind.


   .. py:attribute:: node_global
      :type:  dict[str, list[numpy.ndarray | None]]


   .. py:attribute:: node_region
      :type:  dict[str, dict[str, list[numpy.ndarray | None]]]


   .. py:attribute:: elem_item
      :type:  dict[str, dict[str, list[numpy.ndarray | None]]]


   .. py:attribute:: elem_mult
      :type:  dict[str, dict[str, list[pyfebiopt.xplt.types.MultLike | None]]]


   .. py:attribute:: elem_region
      :type:  dict[str, dict[str, list[numpy.ndarray | None]]]


   .. py:attribute:: face_item
      :type:  dict[str, dict[str, list[numpy.ndarray | None]]]


   .. py:attribute:: face_mult
      :type:  dict[str, dict[str, list[pyfebiopt.xplt.types.MultLike | None]]]


   .. py:attribute:: face_region
      :type:  dict[str, dict[str, list[numpy.ndarray | None]]]


.. py:function:: prepare_field_meta_and_buffers(dictionary: dict[str, dict[str, str]], where: dict[str, str]) -> tuple[dict[str, pyfebiopt.xplt.views._FieldMeta], BufferStore]

   Create field metadata and empty buffers keyed by variable.

   :returns: Parsed metadata and corresponding buffers.
   :rtype: tuple[dict[str, _FieldMeta], BufferStore]