Metadata-Version: 2.4
Name: frequensolve
Version: 0.2.1
Summary: FrequenSolve Python API 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://docs.frequensol.com
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: blake3<2.0.0,>=1.0.5
Requires-Dist: bottleneck<2.0.0,>=1.3.6
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: tqdm<5.0.0,>=4.66.4
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: requests<3.0.0,>=2.31.0; 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 API

[![Coverage](https://codecov.io/gh/FrequenSol/FrequenSolve/branch/v2/graph/badge.svg)](https://app.codecov.io/gh/FrequenSol/FrequenSolve/tree/v2)
[![Python 3.10-3.14](https://img.shields.io/badge/python-3.10--3.14-blue.svg)](pyproject.toml)

FrequenSolve Python is the authoring and orchestration API 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 FrequenSolve Python API and lightweight mesh bindings needed to prepare inputs and inspect outputs.

## Installation

FrequenSolve supports Python 3.10 through 3.14 on macOS and Linux.

Install the released FrequenSolve Python API with:

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

Because the repository is public, you can also install from a source checkout
when you want local examples, documentation sources, or editable development:

```bash
python -m pip install -e .
```

Install optional capabilities only when needed:

```bash
python -m pip install "frequensolve[visual]"      # matplotlib and PyVista plotting
python -m pip install "frequensolve[parallel]"    # local Dask execution
python -m pip install "frequensolve[hpc]"         # SSH and SLURM site support
python -m pip install "frequensolve[cloud]"       # FrequenSol Cloud API and S3 access
python -m pip install "frequensolve[seismic-io]"  # SEG-Y/ASDF IO helpers
python -m pip install "frequensolve[fast-fft]"    # pyFFTW acceleration
python -m pip install "frequensolve[inversion]"   # PyLops-compatible FWI operators
```

## Quickstart

```python
import frequensolve as fs

u = fs.ureg

project = fs.Project(name="quickstart", path="./scratch/quickstart")
sim = project.new_simulation(
    name="simple_acoustic",
    physics="acoustic",
    dimension=2,
    units={"length": "km", "velocity": "km/s", "density": "g/cm^3"},
)

model = fs.LayeredModel(name="model", dimension=2, x_limits=[0.0, 1.0])
model.add_surface(name="top", depth=0.0 * u.km)
model.add_layer(
    name="layer",
    properties={"Vp": 1.5 * u.km / u.s, "Rho": 2.2 * u.g / u.cm**3},
)
model.add_surface(name="bottom", depth=0.5 * u.km)

sim += model
sim += model.hex_mesh_generator([8, 4])
project.save()
```

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

## Sites And Tutorials

Configure the standard execution site once in `~/.frequensolve/site.toml`, then create it in scripts and notebooks with `fs.Site()`. On first use, `fs.Site()` creates a starter config at that path and raises an exception asking you to review it; rerun after accepting or editing the profiles. Direct constructors such as `fs.LocalSite(...)` and `fs.AWSSite(...)` remain available for advanced cases.

Starter config:

```toml
default = "cloud"

[sites.cloud]
type = "aws"
domain = "app.frequensol.com"
interactive = true
verbose = true

[sites.local]
type = "local"
shutdown_on_completion = true
verbose = true

[sites.hpc]
type = "stampede3"
rel_path = "scratch/frequensolve_tutorials"
queue = "skx-dev"
nodes = 1
duration = "00:30:00"
procs_per_node = 4
procs_per_task = 1
poll_interval = 10
verbose = true
```

The tutorial notebooks live in `examples/tutorials`. The local documentation catalog is `docs/source/tutorials/index.rst`, with site-specific examples under `examples/tutorials/02_sites`.

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

GitHub CI runs unit tests, docs, and package checks on normal PRs and pushes.
The downstream Docker image integration gate is intentionally opt-in because it
spends Docker/GitHub Actions minutes. To run it, manually dispatch the `CI`
workflow with `RUN_DOCKER_IMAGE_INTEGRATION=true`.

Release checks:

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

For releases, use PEP 440 package versions and `v`-prefixed tags. Release
candidates are published to TestPyPI, and final releases are published to PyPI.
See [RELEASING.md](RELEASING.md) for the maintainer workflow.

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
```

Published Python API docs are owned by the `FrequenSol/cloud-amplify`
`docs-site-app`. Use that repository's manual `Publish Python Docs` workflow to
build from a selected FrequenSolve release ref and publish immutable artifacts
under `/python/<version>/`, with `/python/latest/` updated after the versioned
artifact is present. The former `docs/host` Terraform stack in this repository
has been destroyed and removed.

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

## License And Support

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