pyfebiopt 0.1.0
Python optimization engine for FEBio
Requires Python: >=3.11
Keywords: FEBio, IFEA, Inverse Optimization

# 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](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.