Metadata-Version: 2.4
Name: frequensolve
Version: 0.2.0
Summary: Python SDK for authoring and running FrequenSolve finite-element simulations
Author-email: FrequenSol <support@frequensol.com>
Maintainer-email: FrequenSol <support@frequensol.com>
License-Expression: MIT
Project-URL: Homepage, https://frequensol.com
Project-URL: Documentation, https://frequensol.com/docs
Project-URL: Support, https://frequensol.com/support
Keywords: finite-elements,seismic,wave-propagation,modeling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: blake3<2.0.0,>=1.0.5
Requires-Dist: click<9.0.0,>=8.1.8
Requires-Dist: h5py<4.0.0,>=3.12.1
Requires-Dist: jinja2<4.0.0,>=3.1.5
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: pint<1.0,>=0.24.4
Requires-Dist: scipy<2.0,>=1.13
Requires-Dist: toml<0.11.0,>=0.10.2
Requires-Dist: xarray<2026.0.0,>=2025.1.1
Provides-Extra: fast-fft
Requires-Dist: pyfftw<0.16,>=0.14; extra == "fast-fft"
Provides-Extra: cloud
Requires-Dist: boto3<2.0.0,>=1.36.23; extra == "cloud"
Requires-Dist: flask<4.0.0,>=3.1.0; extra == "cloud"
Requires-Dist: python-dotenv<2.0.0,>=1.0.1; extra == "cloud"
Requires-Dist: requests<3.0.0,>=2.31.0; extra == "cloud"
Requires-Dist: werkzeug<4.0.0,>=3.1.3; extra == "cloud"
Provides-Extra: parallel
Requires-Dist: bokeh<4.0.0,>=3.4.2; extra == "parallel"
Requires-Dist: dask<2026.0.0,>=2025.1.0; extra == "parallel"
Requires-Dist: dask-jobqueue<0.10.0,>=0.9.0; extra == "parallel"
Requires-Dist: distributed<2026.0.0,>=2024.12.0; extra == "parallel"
Requires-Dist: paramiko<4.0.0,>=3.5.0; extra == "parallel"
Requires-Dist: pyfftw<0.16,>=0.14; extra == "parallel"
Requires-Dist: python-dotenv<2.0.0,>=1.0.1; extra == "parallel"
Provides-Extra: hpc
Requires-Dist: paramiko<4.0.0,>=3.5.0; extra == "hpc"
Requires-Dist: python-dotenv<2.0.0,>=1.0.1; extra == "hpc"
Provides-Extra: inversion
Requires-Dist: pylops<3.0,>=2.4.0; extra == "inversion"
Provides-Extra: seismic-io
Requires-Dist: bitarray<4.0.0,>=3.0.0; extra == "seismic-io"
Requires-Dist: cython<4.0.0,>=3.0.12; extra == "seismic-io"
Requires-Dist: pyasdf<0.9.0,>=0.8.1; extra == "seismic-io"
Requires-Dist: scikit-learn<2.0.0,>=1.6.1; extra == "seismic-io"
Requires-Dist: segyio<2.0.0,>=1.9.12; extra == "seismic-io"
Requires-Dist: zfpy<2.0.0,>=1.0.1; extra == "seismic-io"
Provides-Extra: visual
Requires-Dist: matplotlib<4.0,>=3.7; extra == "visual"
Requires-Dist: pyvista<0.47,>=0.44; extra == "visual"
Provides-Extra: docs
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser<5.0.0,>=4.0.0; extra == "docs"
Requires-Dist: sphinx<9.0.0,>=8.1.3; extra == "docs"
Requires-Dist: sphinx-copybutton<0.6.0,>=0.5.1; extra == "docs"
Requires-Dist: sphinx-rtd-theme<4.0.0,>=3.0.2; extra == "docs"
Provides-Extra: dev
Requires-Dist: black<26.0.0,>=25.1.0; extra == "dev"
Requires-Dist: build<2.0.0,>=1.2.0; extra == "dev"
Requires-Dist: furo>=2024.8.6; extra == "dev"
Requires-Dist: ipykernel<7.0.0,>=6.29.5; extra == "dev"
Requires-Dist: isort<7.0.0,>=6.0.0; extra == "dev"
Requires-Dist: myst-parser<5.0.0,>=4.0.0; extra == "dev"
Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == "dev"
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov<7.0.0,>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock<4.0.0,>=3.12.0; extra == "dev"
Requires-Dist: pytest-mpl<0.18.0,>=0.16.1; extra == "dev"
Requires-Dist: pytest-timeout<3.0.0,>=2.2.0; extra == "dev"
Requires-Dist: pytest-xdist<4.0.0,>=3.5.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.9.0; extra == "dev"
Requires-Dist: sphinx<9.0.0,>=8.1.3; extra == "dev"
Requires-Dist: sphinx-copybutton<0.6.0,>=0.5.1; extra == "dev"
Requires-Dist: sphinx-rtd-theme<4.0.0,>=3.0.2; extra == "dev"
Requires-Dist: twine<7.0.0,>=6.0.0; extra == "dev"
Dynamic: license-file

# FrequenSolve Python SDK

FrequenSolve Python is the authoring and orchestration SDK for FrequenSol finite-element wave simulation software. It builds solver-ready simulation inputs, manages model and acquisition metadata, reads trace outputs, and provides optional adapters for local, SLURM, and cloud execution.

The commercial solver binaries and backend services are licensed separately. This repository contains the Python SDK and lightweight mesh bindings needed to prepare inputs and inspect outputs.

## Installation

FrequenSolve supports Python 3.10, 3.11, and 3.12 on macOS and Linux.

```bash
python -m pip install frequensolve
```

Install optional capabilities only when needed:

```bash
python -m pip install "frequensolve[parallel]"    # SLURM/SSH/Dask helpers
python -m pip install "frequensolve[fast-fft]"    # pyFFTW acceleration
python -m pip install "frequensolve[cloud]"       # FrequenSol cloud backend
python -m pip install "frequensolve[seismic-io]"  # SEG-Y/ASDF and seismic I/O
python -m pip install "frequensolve[visual]"      # plotting helpers
python -m pip install "frequensolve[dev,docs]"    # development and docs
```

## Quickstart

```python
from frequensolve.model import ModelSubdomain
from frequensolve.simulation import SeismicSimulation
from frequensolve.units import ureg

layer = ModelSubdomain(
    mesh_block_id=1,
    physics="acoustic",
    properties={
        "vp": 1.5 * ureg.km / ureg.s,
        "rho": 2.2 * ureg.g / ureg.cm**3,
    },
)

sim = SeismicSimulation(name="simple_acoustic")
sim.model.subdomains.append(layer)
sim.save("sim.json")
```

The SDK exports JSON/HDF5 contracts consumed by fast solver builds. Solver execution requires a licensed solver binary or an enabled FrequenSol execution backend.

## Development

Create a local development environment from the repository root:

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev,docs,visual]"
```

Run deterministic unit tests by default:

```bash
python -m pytest
```

Release checks:

```bash
pre-commit run --all-files
git status --short
python -m build
python -m twine check dist/*
```

For a release, build from a clean tagged commit. Versioneer uses plain PEP 440
tags, so tag releases as `0.2.0`, `0.2.1`, and so on. The GitHub release
workflow builds the sdist and wheel, rejects dirty or untagged versions, and can
publish to TestPyPI from `workflow_dispatch` or PyPI from a published GitHub
Release after Trusted Publishing is configured for the `testpypi` and `pypi`
environments.

Solver, cloud, HPC, and visual tests are marked and must be selected explicitly:

```bash
python -m pytest -m integration
python -m pytest -m cloud
python -m pytest -m hpc
python -m pytest -m visual
```

## Documentation

Build the Sphinx documentation locally with:

```bash
python -m pip install -e ".[docs]"
cd docs
make html
```

Fast solver contract updates are tracked in `docs/source/fast_solver_api_updates.rst`.

## License And Support

FrequenSolve Python SDK is open source under the MIT license. The fast solver is licensed separately; for solver access and support, contact support@frequensol.com.
