pyfebiopt 0.2.0

Python optimization engine for FEBio

pyFEBiOpt

pyFEBiOpt wraps FEBio simulations with a flexible Python optimization engine. FEBio provides an optimization workflow, but it is limited when a project needs custom post-processing, several objectives, or SciPy-level control. This project binds SciPy optimizers to FEBio simulations so you can optimize flexible multi-objective cost functions while keeping FEBio as the solver.

Highlights

• Inverse optimization engine with reparameterization, clean logging, monitoring, Jacobian helpers, FEB template bindings, and configurable runners/storage. Build parameter grids, run multiple cases, and keep artifacts organized with automatic cleanup/persistence policies.
• Post-processing via a fast binary .xplt reader with sliceable views for nodes, elements, faces, and regions (no copies until needed).
• Visualization utilities built on pyvista for quick mesh/result plotting.
• Extensible design: adapters for experiment data, telemetry hooks, series export, and structured configuration dataclasses to keep projects reproducible. Plug in your own experiment loaders or monitoring sinks without changing the engine.

Workflow

Most scripts declare experiment data, fitted parameters, FEB template bindings, one or more simulation cases, and EngineOptions. Engine.run() then renders FEB files, launches FEBio, reads .xplt outputs through adapters, assembles residuals for SciPy, and records logs/artifacts.

Roadmap

• Extensively document the API (usage, configuration, and extension points).
• Add more examples for the .xplt module, visualization, and optimization workflows.
• Expand monitoring UI (history pagination, richer iteration drill-down, export).
• Strengthen test coverage and benchmarks across optimization and I/O paths.
• Harden packaging/release automation (semantic-release, CI/CD, PyPI publishing).
• Add CI matrices for multiple Python versions and check FEBio compatibility against the latest stable releases.

Project Info

• Source: https://gitlab.com/autrera-group/pyfebiopt/
• Issues: https://gitlab.com/autrera-group/pyfebiopt/-/issues
• License: MIT (see LICENSE)

Quickstart

Tested on Ubuntu LTS (latest). Other platforms are untested.

1. Create an environment and install.

   Python virtual environment:

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

   Conda environment:

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

   Install the published package with pip:

   pip install pyfebiopt
   

   Or clone the repository and install from the local checkout:

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

2. Run a simple example:

   python examples/simple_biaxial_fit.py
   

   This will execute a basic optimization and log progress. Adjust the example input paths to point at your FEBio files if needed.

3. Launch the monitoring UI (optional):

   pyfebiopt-monitor
   

   Follow the printed URL to view live runs; the UI lists active runs, cost per iteration, series plots, and system metrics.

4. (Optional) Install the monitor as a service via the helper CLI:

   # run ad-hoc with overrides
   pyfebiopt-monitorctl run --host 0.0.0.0 --port 8765 --registry /tmp/pyfebiopt-registry.json --socket /tmp/pyfebiopt.sock
   
   # install user-level systemd service (default host/port 127.0.0.1:8765)
   pyfebiopt-monitorctl install
   
   # install system-wide (needs sudo) with custom host/port
   sudo pyfebiopt-monitorctl install --system --host 0.0.0.0 --port 8000 --force
   
   # uninstall
   pyfebiopt-monitorctl uninstall          # user
   sudo pyfebiopt-monitorctl uninstall --system
   

   Flags:

   • --host, --port: bind address/port for the web UI.
   • --registry: path to the run registry JSON.
   • --socket: path to the event socket used by workers. Exposing the monitor publicly is your responsibility—use VPN/reverse proxy if needed.

Contributing

See CONTRIBUTING.md for coding standards, CI details, and hook setup tips.

Support

Open an issue at https://gitlab.com/autrera-group/pyfebiopt/-/issues with details about your environment, FEBio version, Python version, and minimal reproduction steps. Questions, bug reports, and feature requests are welcome.