Installation¶

Requirements¶

OS: Linux or macOS (Windows is not currently supported).
Python: 3.10 or higher (required by the jax dependency).
Key runtime dependencies: geopandas, pandas, numpy, scipy, jax/jaxlib, statsmodels, matplotlib, and the mesh/geospatial stack (shapely, gmsh, meshio, pygmsh, pyproj).

See pyproject.toml or environment.yml in the repository for the complete, versioned dependency list.

Option 1: pip¶

pip install geossm

Option 2: from source with Conda (recommended for development)¶

Several of geossm’s dependencies (gmsh, mfem, jax) are easiest to install consistently through Conda, so this is the recommended route if you plan to build meshes, run the low-rank models, or work on the package itself.

Clone the repository:

git clone https://github.com/jacopoRodeschini/geossm.git
cd geossm

Create the geossm Conda environment from environment.yml (using the faster libmamba solver is recommended):

conda config --set solver libmamba
conda update -n base -c defaults conda
conda env create -f environment.yml

Activate the environment and install the package in editable mode:
```
conda activate geossm
pip install -e .
```

Verifying the installation¶

import geossm
print(geossm.__version__)

Optional extras¶

geossm defines a few optional dependency groups in pyproject.toml:

Extra	Purpose
`test`	`pytest` / `pytest-cov` for running the test suite.
`docs`	Sphinx, the Furo theme, and sphinx-design, to build this documentation locally (see User Guide’s development notes below).
`dev`	Linting (`ruff`), type checking (`mypy`), packaging (`build`, `twine`), and pre-commit hooks, on top of `test`.
`interactive`	Jupyter/IPython tooling for interactive/notebook usage.

Install one or more extras with, e.g.:

pip install -e ".[docs]"
pip install -e ".[dev,test]"

Building this documentation locally¶

Once the docs extra is installed (on top of a full geossm installation, since the API reference imports the package), build the HTML docs with:

sphinx-build -b html docs/source docs/build/html

and preview them with a simple HTTP server:

python -m http.server --directory docs/build/html 8000

Then open http://localhost:8000 in a browser. The docs/build/ directory is generated output and is not committed to the repository (see .gitignore).

Uninstalling¶

pip uninstall geossm
# and, if you created it, the Conda environment:
conda remove -n geossm --all