Overview and installation
=========================

Goal of pyFEBiOpt
-----------------

FEBio provides an optimization workflow, but that workflow is limited when a project
needs flexible multi-objective costs, custom post-processing, several experiments,
or Python-side orchestration. pyFEBiOpt fills that gap by binding SciPy optimizers
to FEBio simulations through a featured, easy-to-use optimization engine.

Typical workflow
----------------

1. Prepare experimental data as arrays.
2. Declare the FEBio material or geometry parameters to fit.
3. Bind those parameters to locations in a ``.feb`` template.
4. Run FEBio for each candidate parameter set.
5. Read the generated ``.xplt`` output.
6. Optionally postprocess results and generate figures with PyVista.
7. Convert simulation output into residuals for one or more objectives.
8. Let SciPy drive the next parameter update.

Installation
------------

pyFEBiOpt can be installed in either a standard Python virtual environment or a
Conda environment. In both cases, FEBio must be installed separately.

Python virtual environment
~~~~~~~~~~~~~~~~~~~~~~~~~~

Create and activate the environment:

.. code-block:: bash

   python -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip

Install the published package from PyPI:

.. code-block:: bash

   pip install pyfebiopt

Or clone the repository and install from the local checkout:

.. code-block:: bash

   git clone https://gitlab.com/autrera-group/pyfebiopt.git
   cd pyfebiopt
   pip install .

Conda environment
~~~~~~~~~~~~~~~~~

Create and activate the environment:

.. code-block:: bash

   conda create -n pyfebiopt python=3.11
   conda activate pyfebiopt
   python -m pip install --upgrade pip

Install the published package from PyPI:

.. code-block:: bash

   pip install pyfebiopt

Or clone the repository and install from the local checkout:

.. code-block:: bash

   git clone https://gitlab.com/autrera-group/pyfebiopt.git
   cd pyfebiopt
   pip install .

.. warning::

   pyFEBiOpt is exercised on Linux, especially Ubuntu. FEBio itself must be
   installed separately and available through the command configured in
   ``RunnerOptions.command`` or on ``PATH``.