Installation — OGR Slip2D documentation

OGR Slip2D is a Python package, ogr-slip2d. Until signed installers are published, it is installed from its public source code into a virtual environment.

1.1.1Requirements#

Python 3.11 or newer. The continuous-integration runs test the suite on 3.11, 3.12 and 3.13.
Git, to clone the repository (or download it as a ZIP from GitHub).

Everything else is installed by pip from the package metadata: NumPy, SciPy, Shapely, pyclipper, ezdxf, h5py, Matplotlib, PySide6, QtAwesome, Typer, Rich, Pydantic and ReportLab.

1.1.2Installing from source#

Clone the repository, create a virtual environment inside it, activate it and install the package in editable mode:

git clone https://github.com/samuelsl27/OGR-Slip2D.git
cd OGR-Slip2D
python -m venv .venv
.venv\Scripts\activate            # Windows
source .venv/bin/activate         # macOS and Linux
pip install -e .

The editable install (-e) links the package to the folder you cloned, so git pull is enough to update the code. On macOS and some Linux distributions the interpreter is called python3.

1.1.3The three commands#

Table 1.1.1 Commands installed by the package.

Command	Equivalent	What it starts
`ogr-slip2d`	`python -m ogr_gui`	The desktop program
`ogr-slip2d-cli`	`python -m ogr_cli`	The command-line interface (Section 5.2)
`ogr-slip2d-mcp`	`python -m ogr_mcp`	The MCP server for AI agents (Section 5.1); needs the `[mcp]` extra

The program opens with an empty project. File → Load Demo Slope loads a small sample model (a 10 m high, 1V:1H slope in silty clay with a water table), which is a quick way to check that the analysis runs. Section 1.2 builds a model from scratch.

1.1.4Optional extras#

Table 1.1.2 Optional dependency groups, installed with pip install -e ".[name]".

Extra	Adds	Needed for
`mcp`	The official MCP SDK for Python (`mcp>=2.1,<3`, MIT licence)	The MCP server
`dev`	pytest, pytest-qt, black, ruff, mypy	Development tools
`docs`	Sphinx and its theme	Building documentation locally

Several extras can be combined: pip install -e ".[mcp,dev]". Connecting an AI agent is described step by step on the AI & MCP page.

1.1.5Running the test suite#

The project uses its own test runner, tests/_runner.py; pytest is not required, and the test modules cannot be imported outside the runner. The graphical tests build Qt widgets, so they need Qt's off-screen platform:

# Windows (PowerShell)
$env:QT_QPA_PLATFORM = "offscreen"; python tests/_runner.py
# macOS and Linux
QT_QPA_PLATFORM=offscreen python tests/_runner.py

The full suite (5 265 tests in version 0.1.235) takes about half an hour; the time varies between identical runs, so take it only as an approximate guide. To work on one area, run only part of it:

python tests/_runner.py transient          # files whose name contains it
python tests/_runner.py -k erfc            # tests whose name contains it
python tests/_runner.py --list transient   # show the selection, run nothing

Note

A pattern that matches nothing exits with code 2 instead of announcing an empty success. A filtered run prints a FILTERED RUN warning around its totals, because only the full suite can support a release.

1.1.6Updating and uninstalling#

From the repository folder, with the environment active: git pull, then pip install -e . again to pick up any new dependency. To uninstall, delete the cloned folder, since the virtual environment lives inside it.

1.1.7Interface language#

The interface is available in English and Spanish (File → Preferences… → Language). The program starts in English; in version 0.1.235 the choice of language is not stored between sessions. Screenshots in this documentation show the English interface.