Metadata-Version: 2.4
Name: frequensolve
Version: 0.3.0
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: sympy<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: hpc
Requires-Dist: bokeh<4.0.0,>=3.4.2; extra == "hpc"
Requires-Dist: dask<2026.0.0,>=2025.1.0; extra == "hpc"
Requires-Dist: dask-jobqueue<0.10.0,>=0.9.0; extra == "hpc"
Requires-Dist: distributed<2026.0.0,>=2024.12.0; extra == "hpc"
Requires-Dist: keyring<26.0.0,>=25.0.0; extra == "hpc"
Requires-Dist: paramiko<4.0.0,>=3.5.0; extra == "hpc"
Requires-Dist: pyfftw<0.16,>=0.14; extra == "hpc"
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: keyring<26.0.0,>=25.0.0; extra == "parallel"
Requires-Dist: paramiko<4.0.0,>=3.5.0; extra == "parallel"
Requires-Dist: pyfftw<0.16,>=0.14; extra == "parallel"
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: hypothesis<7.0.0,>=6.100.0; 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: jsonschema<5.0.0,>=4.23.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.14.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.

Create an isolated environment and install the released FrequenSolve Python
API with:

```bash
python3.10 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install frequensolve
frequensolve --version
```

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

### Stampede3 quick setup

Install the HPC dependencies into the active environment, generate a site
profile, authenticate once, and check it:

```bash
python -m pip install "frequensolve[hpc]"

frequensolve site configure stampede3 \
  --account YOUR_TACC_ALLOCATION \
  --solver /absolute/remote/path/to/FS_seismic
frequensolve site connect
frequensolve site check
```

The configuration command prompts for the TACC username and writes a minimal
`~/.frequensolve/site.toml`. The built-in Stampede3 preset supplies the login
host, launcher, partitions, and standard Intel MPI, PETSc, and parallel-HDF5
runtime modules. Users do not normally need to specify a credential label, SSH
key, hostname, or module list.

`frequensolve site connect` establishes an OpenSSH connection that scripts,
notebooks, `fs.Site()` instances, and transfers can reuse for up to eight
hours. It does not modify `~/.ssh/config`. See
[Share one SSH login across FrequenSolve sessions](docs/guides/ssh-connection-sharing.md)
for the optional generic OpenSSH configuration alternative.

After setup, activate the environment and use the saved default site from any
script or notebook:

```bash
. .venv/bin/activate
frequensolve site connect
python your_script.py
```

```python
import frequensolve as fs

with fs.Site() as site:
    result = site.submit(job).wait()
```

For custom Slurm clusters, local solvers, cloud execution, multiple profiles,
and site-level overrides, see the
[site configuration guide](docs/source/user_guide/site_configuration.rst).
Direct constructors such as `fs.LocalSite(...)` and `fs.AWSSite(...)` remain
available for advanced cases. Scheduler templates and the adaptive runner are
installed with FrequenSolve, so `PYTHONPATH` is not required for site setup.

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.
It also runs a single Python 3.12 lane with the visual and seismic-IO extras,
and installs both built distribution formats on Ubuntu and macOS. The stable
`Required CI` job aggregates every PR-safe gate.

Run the optional local visual and seismic-IO lane with:

```bash
python -m pip install -e ".[dev,parallel,visual,seismic-io]"
make test-optional-extras
```

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. Creating a
release candidate is the paid, manual release gate: it requires successful
`Required CI` evidence for the exact source SHA and calls the pinned
FrequenSolveDockerImage solver workflow with an immutable final FrequenSolver
release before creating any tag. The evidence JSON, preferred FrequenSolver
release/commit, and checksum-bound heavy-test archive follow that commit through
final promotion and publication. Release
candidates are published to TestPyPI, and final releases are published to PyPI.
See [RELEASING.md](RELEASING.md) for the maintainer workflow.

Released wheels and source distributions include the preferred FrequenSolver
pairing proven by that evidence. Local and HPC sites check the configured
executable once before submission. An unknown or different pair produces a
warning by default, and remote identity probes time out after 15 seconds; set
`frequensolver_policy = "strict"` in the site profile to require the tested
release and commit, or `"off"` to opt out explicitly.

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.
