Metadata-Version: 2.4
Name: pyfebiopt
Version: 0.2.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: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: python-semantic-release<10,>=9; extra == 'dev'
Requires-Dist: ruff>=0.14.8; extra == 'dev'
Requires-Dist: sphinx-autoapi>=3.6.0; 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 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](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.
