pyfebiopt.optimize.feb_bindings
===============================

.. py:module:: pyfebiopt.optimize.feb_bindings

.. autoapi-nested-parse::

   Simplified FEBio template helpers.



Classes
-------

.. autoapisummary::

   pyfebiopt.optimize.feb_bindings.BuildContext
   pyfebiopt.optimize.feb_bindings.ParameterBinding
   pyfebiopt.optimize.feb_bindings.EvaluationBinding
   pyfebiopt.optimize.feb_bindings.FebTemplate
   pyfebiopt.optimize.feb_bindings.FebBuilder


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

.. py:class:: BuildContext

   Formatting options applied while writing FEBio templates.

   :param fmt: ``printf``-style format string used for numeric values.
   :param namespaces: Optional mapping passed to :func:`xml.etree.ElementTree.findall`.


   .. py:attribute:: fmt
      :type:  str
      :value: '%.20e'



   .. py:attribute:: namespaces
      :type:  dict[str, str]


   .. py:method:: format_value(value: Number) -> str

      Format a scalar value according to the ``fmt`` pattern.

      :returns: String representation suitable for FEBio XML content.



.. py:class:: ParameterBinding

   Map a single theta value onto an XML element's text content.

   The XPath is evaluated with :func:`ElementTree.findall`. All matching nodes
   are updated; set ``required`` to ``False`` to ignore missing nodes.


   .. py:attribute:: theta_name
      :type:  str


   .. py:attribute:: xpath
      :type:  str


   .. py:attribute:: required
      :type:  bool
      :value: True



   .. py:method:: apply(root: xml.etree.ElementTree.Element, theta: collections.abc.Mapping[str, Number], ctx: BuildContext) -> None

      Insert formatted values into all nodes matched by ``xpath``.



.. py:class:: EvaluationBinding

   Bind an XPath to a value derived from multiple θ parameters.

   :param xpath: XPath targeting the XML node(s) to update.
   :param value: Expression or callable producing either a numeric value or plain text.
                 String expressions remain numeric-only; callable values may return
                 preformatted text for complex XML nodes such as vectors.
   :param required: Same semantics as :class:`ParameterBinding`.
   :param text_template: Optional :py:meth:`str.format` template receiving the formatted value
                         via the ``value`` placeholder, useful for nodes that contain mixed text
                         such as ``"2,{value}"`` in load curves.


   .. py:attribute:: xpath
      :type:  str


   .. py:attribute:: value
      :type:  str | collections.abc.Callable[[collections.abc.Mapping[str, Number]], ScalarOrText]


   .. py:attribute:: required
      :type:  bool
      :value: True



   .. py:attribute:: text_template
      :type:  str | None
      :value: None



   .. py:method:: __post_init__() -> None


   .. py:method:: apply(root: xml.etree.ElementTree.Element, theta: collections.abc.Mapping[str, Number], ctx: BuildContext) -> None

      Apply the evaluated value to all matching nodes.



.. py:class:: FebTemplate

   FEBio template plus bindings applied during rendering.


   .. py:attribute:: template_path
      :type:  pathlib.Path | str


   .. py:attribute:: bindings
      :type:  list[Binding]
      :value: []



   .. py:method:: __post_init__() -> None


   .. py:method:: add_binding(binding: Binding) -> None

      Register an additional binding for this template.



   .. py:method:: render(theta: collections.abc.Mapping[str, Number], ctx: BuildContext | None = None) -> xml.etree.ElementTree.ElementTree

      Render the template into an XML tree using the supplied parameters.

      :returns: Parsed :class:`xml.etree.ElementTree.ElementTree` ready for saving.



   .. py:method:: write(theta: collections.abc.Mapping[str, Number], out_path: pathlib.Path | str, ctx: BuildContext | None = None) -> pathlib.Path

      Render and write the template to ``out_path``.

      :returns: Path to the written FEB file.



.. py:class:: FebBuilder

   Render FEBio input files under a dedicated case subfolder.


   .. py:attribute:: template
      :type:  FebTemplate


   .. py:attribute:: subfolder
      :type:  str


   .. py:method:: build(theta: collections.abc.Mapping[str, Number], out_root: pathlib.Path | str, out_name: str | None = None, ctx: BuildContext | None = None) -> pathlib.Path

      Render the template into the case subfolder and return the FEB path.

      :returns: Full path to the generated FEB document.