Constrained Spectral Approximation

The Constrained Spectral Approximation (CSA) method is a physically sound and robust method for approximating the spectrum of subgrid-scale orography. It operates under the following constraints:

• Utilises a limited number of spectral modes (no more than 100)
• Significantly reduces the complexity of physical terrain by over 500 times
• Maintains the integrity of physical information to a large extent
• Compatible with unstructured geodesic grids
• Inherently scale-aware

This method is primarily used to represent terrain for weather forecasting purposes, but it also shows promise for broader data analysis applications.

---

Read the documentation here

---

Requirements

See requirements.txt

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

Usage

Installation

Install the latest release from PyPI:

pip install pycsa-specappx

The distribution is named pycsa-specappx (the bare pycsa name was already taken on PyPI by an unrelated project), but the import name is unchanged — import pycsa.

To run the bundled experiment scripts in runs/ / examples/, or to contribute, work from a clone instead:

git clone https://github.com/ray-chew/pyCSA && cd pyCSA
pip install -e ".[test]"

Configuration

Run parameters are assembled programmatically inside the run scripts using the pycsa.config.params dataclass. Example experiment scripts live in runs/ and examples/; the reusable building blocks are in the pycsa package (pycsa.core, pycsa.wrappers, pycsa.plotting, pycsa.data, pycsa.compute).

Runs that read on-disk data (e.g. the global ICON+ETOPO pipeline) locate it through SPEC_APPX_* environment variables, which are read by pycsa/local_paths.py (copied from local_paths.py.template):

export SPEC_APPX_DATA_DIR=/path/to/data          # directory containing the ICON grid
export SPEC_APPX_ETOPO_DIR=/path/to/data/etopo_15s
export SPEC_APPX_MERIT_DIR=/path/to/MERIT        # MERIT runs only
export SPEC_APPX_REMA_DIR=/path/to/REMA          # MERIT runs only
export SPEC_APPX_OUTPUT_DIR=/path/to/outputs

Set these directly or with source setup_paths.sh. The bundled examples/ need no such setup — their data ships with the repo.

Execution

A simple setup can be found in runs/idealised_isosceles.py, a fixed-seed idealised benchmark. From a clone, run it directly:

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

However, the codebase is structured such that the user can easily assemble a run script to define their own experiments. Refer to the documentation for the available APIs.

Examples

Three self-contained examples ship with bundled data (no download needed):

• Idealised — pycsa-idealised (synthetic terrain with a known spectrum; see the tutorial).
• Aleutians / MERIT — examples/icon_regional_minimal.py (real ICON cell, ~10 s).
• Andes / ETOPO — examples/icon_etopo_andes.py (real ETOPO cell with ocean-aware masking; see the showcase).

License

GNU GPL v3 (tentative)

Contributions

Refer to the open issues that require attention.

Any changes, improvements, or bug fixes can be submitted to upstream via a pull request.