Quickstart

A quick and dirty guide to using the CSA codebase

Requirements

To run the code, make sure the following packages are installed, preferably in a virtual environment.

# Core runtime dependencies; mirror of [project.dependencies] in pyproject.toml.
# Optional/test extras (pytest, scikit-learn, ...) live in pyproject's [test] extra.
Cartopy>=0.25.0
dask[distributed]>=2026.1.2
h5py>=3.15.1
matplotlib>=3.10.7
netCDF4>=1.7.3
noise>=1.2.2
numba>=0.62.1
numpy>=2.2.6
pandas>=2.3.3
scipy>=1.15.3
tqdm>=4.66.0

Note

The Sphinx dependencies can be found in docs/source/conf.py.

Overview

The pyCSA codebase is structured modularly, see Fig. 1 for a graphical overview.

The subpackage pycsa.wrappers provides interfaces to the core code components in pycsa.core and the plotting helpers in pycsa.plotting. For example, it defines the First and Second Approximation steps in the CSA algorithm and applies the tapering of the physical data. Refer to the APIs for more details.

Helper functions and data structures are provided for the processing of user-defined topographies (pycsa.data.cell.topo), grids (pycsa.data.cell.grid), and input parameters (pycsa.config.params.params).

These building blocks are then assembled for different kinds of experiments in user-defined run scripts. Some examples live in the top-level runs/ and examples/ directories.

pyCSA program structure

Fig. 1 pyCSA program structure

A first run

The quickest way to see the method end-to-end is the bundled idealised isosceles experiment. After pip install -e . it is a single command via the pycsa-idealised console script:

pycsa-idealised

The equivalent direct invocations also work:

python -m runs.idealised_isosceles
python3 ./runs/idealised_isosceles.py

See the Tutorial: Idealised isosceles experiment for a step-by-step walkthrough of this experiment, the Showcase: ETOPO over the central Andes for a real-data ETOPO example over the Andes (bundled data, runs in seconds), and HPC reproducibility guide for the global ICON+ETOPO pipeline.

Note

Run parameters are assembled programmatically in the run scripts under runs/ and examples/ (using pycsa.config.params.params), rather than via a separate input module. The design favours debugging and diagnostics in an interactive ipython environment.