Metadata-Version: 2.4
Name: pyfebiopt
Version: 0.1.0
Summary: Python optimization engine for FEBio
Project-URL: Homepage, https://gitlab.com/autrera-group/pyfebiopt/
Project-URL: Documentation, https://pyfebiopt-defe5b.gitlab.io/
Project-URL: Source, https://gitlab.com/autrera-group/pyfebiopt/
Project-URL: Issues, https://gitlab.com/autrera-group/pyfebiopt/-/issues
Author-email: Andrés Utrera Soto <andres.utrera@usach.cl>
License-File: LICENSE
Keywords: FEBio,IFEA,Inverse Optimization
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.111.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: numpy>=2.3.5
Requires-Dist: prettytable>=3.17.0
Requires-Dist: psutil>=5.9
Requires-Dist: pyvista>=0.46.4
Requires-Dist: scipy>=1.16.3
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: watchdog>=4.0.0
Provides-Extra: dev
Requires-Dist: black>=24.2; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: python-semantic-release<10,>=9; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Requires-Dist: sphinx-autodoc-typehints>=3.2.0; extra == 'dev'
Requires-Dist: sphinx-rtd-theme>=3.0.2; extra == 'dev'
Requires-Dist: sphinxcontrib-napoleon>=0.7; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

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