pyfebiopt 0.1.0

Python optimization engine for FEBio

pyfebiopt

pyFEBiOpt wraps the FEBio solver with a more flexible toolbox. FEBio ships with optimisation hooks, but they are intentionally narrow; this library delivers extremely flexible inverse optimisation, multi-objective workflows, and extensible, parallel computation that slot cleanly into existing FEBio projects.

Highlights

• Inverse optimisation engine with reparameterisation, clean logging, monitoring, Jacobian helpers, FEB template bindings, and configurable runners/storage. Build parameter grids, run multiple cases, and keep artefacts organised 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).
• Visualisation 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.

Roadmap

• Extensively document the API (usage, configuration, and extension points).
• Add more examples for the .xplt module, visualisation, and optimisation workflows.
• Expand monitoring UI (history pagination, richer iteration drill-down, export).
• Strengthen test coverage and benchmarks across optimisation 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. Install (from repo root):

   pip install .
   

   Or install the published package:

   pip install pyfebiopt
   

   Or clone and use a virtual env:

   git clone https://gitlab.com/autrera-group/pyfebiopt.git
   cd pyfebiopt
   python -m venv .venv && source .venv/bin/activate   # or conda create -n pyfebiopt python=3.11
   pip install -e ".[dev]"
   

2. Run a simple example:

   python examples/simple_biaxial_fit.py
   

   This will execute a basic optimisation 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.