Make each worker access cached topography file

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI Workflow
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  format-check:
+    name: Run Black Formatter
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Black
+        run: pip install black==26.3.0
+
+      - name: Run Black
+        run: black --check .
+
+  docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ConorMacBride/install-package@v1
+        with:
+          apt: libgeos-dev graphviz
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10.5"
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install sphinx furo sphinx-changelog
+      - name: Sphinx build
+        run: |
+          sphinx-build docs/source _build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

.gitignore

@@ -7,6 +7,23 @@
 *.pdf
 *.png
 *.json
+*.bat
+*.log
+*.egg-info
+*.swp
+*.bak
 
 /docs/build/*
 .VSCodeCounter/*
+/notebooks/*
+/preprint/*
+/poster/*
+*submission/*
+manuscript/*
+first_revision/*
+outputs/*
+local_archive/*
+
+# Local configuration (never commit!)
+pycsa/local_paths.py
+setup_paths_local.sh

README.md

@@ -1,15 +1,15 @@
 <p align="center">
-  <a href="https://ray-chew.github.io/pyCSAM/index.html">
-  <img alt="CSAM Logo" src="https://ray-chew.github.io/pyCSAM/_static/logo.png">
+  <a href="https://ray-chew.github.io/pyCSA/index.html">
+  <img alt="CSA Logo" src="https://ray-chew.github.io/pyCSA/_static/logo.png">
   </a>
 </p>
 
-<h2 align="center">Constrained Spectral Approximation Method</h2>
+<h2 align="center">Constrained Spectral Approximation</h2>
 
 
 <p align="center">
-<a href="https://github.com/ray-chew/pyCSAM/actions/workflows/documentation.yml">
-<img alt="GitHub Actions: docs" src=https://img.shields.io/github/actions/workflow/status/ray-chew/pyCSAM/documentation.yml?logo=github&label=docs>
+<a href="https://github.com/ray-chew/pyCSA/actions/workflows/documentation.yml">
+<img alt="GitHub Actions: docs" src=https://img.shields.io/github/actions/workflow/status/ray-chew/pyCSA/documentation.yml?logo=github&label=docs>
 </a>
 <a href="https://www.gnu.org/licenses/gpl-3.0">
 <img alt="License: GPL v3" src=https://img.shields.io/badge/License-GPLv3-blue.svg>
@@ -20,7 +20,7 @@
 </p>
 
 
-The Constrained Spectral Approximation Method (CSAM) is a physically sound and robust method for approximating the spectrum of subgrid-scale orography. It operates under the following constraints:
+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
@@ -32,15 +32,15 @@ This method is primarily used to represent terrain for weather forecasting purpo
 
 ---
 
-**[Read the documentation here](https://ray-chew.github.io/pyCSAM/index.html)**
+**[Read the documentation here](https://ray-chew.github.io/pyCSA/index.html)**
 
 ---
 
 ## Requirements
 
-See [`requirements.txt`](https://github.com/ray-chew/pyCSAM/blob/main/requirements.txt)
+See [`requirements.txt`](https://github.com/ray-chew/pyCSA/blob/main/requirements.txt)
 
-> **NOTE:**  The Sphinx dependencies can be found in [`docs/conf.py`](https://github.com/ray-chew/pyCSAM/blob/main/docs/source/conf.py).
+> **NOTE:**  The Sphinx dependencies can be found in [`docs/conf.py`](https://github.com/ray-chew/pyCSA/blob/main/docs/source/conf.py).
 
 
 ## Usage
@@ -51,17 +51,17 @@ Fork this repository and clone your remote fork.
 
 ### Configuration
 
-The user-defined input parameters are in the [`inputs`](https://github.com/ray-chew/pyCSAM/tree/main/inputs) subpackage. These parameters are imported into the run scripts in [`runs`](https://github.com/ray-chew/pyCSAM/tree/main/runs). 
+The user-defined input parameters are in the [`inputs`](https://github.com/ray-chew/pyCSA/tree/main/inputs) subpackage. These parameters are imported into the run scripts in [`runs`](https://github.com/ray-chew/pyCSA/tree/main/runs).
 
 ### Execution
 
-A simple setup can be found in [`runs.idealised_isosceles`](https://github.com/ray-chew/pyCSAM/blob/main/runs/idealised_isosceles.py). To execute this run script:
+A simple setup can be found in [`runs.idealised_isosceles`](https://github.com/ray-chew/pyCSA/blob/main/runs/idealised_isosceles.py). To execute this run script:
 
 ```console
 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](https://ray-chew.github.io/pyCSAM/api.html).
+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](https://ray-chew.github.io/pyCSA/api.html).
 
 ## License
 

docs/source/conf.py

@@ -18,9 +18,9 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "CSAM"
-copyright = "2024, Ray Chew, Stamen Dolaptchiev, Maja-Sophie Wedel, Ulrich Achatz"
-author = "Ray Chew, Stamen Dolaptchiev, Maja-Sophie Wedel, Ulrich Achatz"
+project = "CSA"
+copyright = "2024, Ray Chew"
+author = "Ray Chew"
 
 # The full version, including alpha/beta/rc tags
 release = "v0.95.1"

docs/source/index.rst

@@ -1,4 +1,4 @@
-CSAM's Home
+CSA's Home
 ===========
 
 .. toctree::
@@ -19,7 +19,7 @@ CSAM's Home
 
 
 
-This page documents the codebase for the Constrained Spectral Approximation Method (CSAM). CSAM is a physically sound and robust method for approximating the spectrum of subgrid-scale orography. It operates under the following constraints:
+This page documents the codebase for the Constrained Spectral Approximation Method (CSA). CSA 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

docs/source/modules/runs.icon_usgs_test.rst

@@ -1,7 +1,7 @@
 runs.icon_usgs_test
 ===================
 
-Run script for CSAM experiments involving the ICON grid and the USGS GMTED 2010 orographic dataset.
+Run script for CSA experiments involving the ICON grid and the USGS GMTED 2010 orographic dataset.
 
 
 

docs/source/quick_start.rst

@@ -1,6 +1,6 @@
 Quickstart
 ==========
-A quick and dirty guide to using the CSAM codebase
+A quick and dirty guide to using the CSA codebase
 
 Requirements
 ^^^^^^^^^^^^
@@ -13,9 +13,9 @@ To run the code, make sure the following packages are installed, preferably in a
 
 Overview
 ^^^^^^^^
-The CSAM codebase is structured modularly, see :numref:`structure` for a graphical overview.
+The CSA codebase is structured modularly, see :numref:`structure` for a graphical overview.
 
-The package :mod:`wrappers` provides interfaces to the core code components in :mod:`src` and :mod:`vis`. For example, it defines the First and Second Approximation steps in the CSAM algorithm and applies the tapering of the physical data. Refer to the :doc:`APIs <api>` for more details.
+The package :mod:`wrappers` provides interfaces to the core code components in :mod:`src` and :mod:`vis`. 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 :doc:`APIs <api>` for more details.
 
 Helper functions and data structures are provided for the processing of user-defined topographies (:mod:`src.var.topo`), grids (:mod:`src.var.grid`), and input parameters (:mod:`src.var.params`).
 
@@ -24,8 +24,8 @@ These *building blocks* are the assembled for different kinds of experiments in
 .. graphviz::
     :align: center
     :name: structure
-    :alt: CSAM program structure
-    :caption: CSAM program structure
+    :alt: CSA program structure
+    :caption: CSA program structure
 
     digraph {    
         graph [
@@ -209,4 +209,4 @@ Alternatively, the run script could be executed via ``ipython``.
 
 .. note::
 
-    The development of the CSAM codebase frontend is currently ongoing. The current design approach of the program structure aims to simplify debugging and diagnostics using an ``ipython`` environment.
+    The development of the CSA codebase frontend is currently ongoing. The current design approach of the program structure aims to simplify debugging and diagnostics using an ``ipython`` environment.

examples/etopo_loader_example.py

@@ -0,0 +1,96 @@
+"""
+Example script demonstrating how to use the ETOPO 2022 15 arc-second loader
+
+This script shows how to:
+1. Set up parameters for ETOPO data loading
+2. Load a regional topography dataset
+3. Apply coarse-graining for different resolutions
+"""
+
+import numpy as np
+from pycsa.core import io, var
+
+
+class params:
+    """Simple parameter class for ETOPO loading"""
+
+    def __init__(self):
+        # Path to ETOPO data directory (must end with /)
+        self.path_etopo = "/home/ray/git-projects/spec_appx/data/etopo_15s/"
+
+        # Define region of interest [lat_min, lat_max]
+        self.lat_extent = [30.0, 45.0]
+
+        # Define region of interest [lon_min, lon_max]
+        self.lon_extent = [-120.0, -105.0]
+
+        # Coarse-graining factor (1 = no coarse-graining, 2 = 2x2 average, etc.)
+        # ETOPO 15" has ~3600 points per 15 degrees, so coarse-graining is useful
+        # etopo_cg = 2  -> ~30" resolution
+        # etopo_cg = 4  -> ~60" resolution (1 arc-minute)
+        # etopo_cg = 8  -> ~120" resolution (2 arc-minutes)
+        self.etopo_cg = 1  # Default: no coarse-graining
+
+
+# Example 1: Load high-resolution data (15 arc-seconds, no coarse-graining)
+print("Example 1: Loading high-resolution ETOPO data...")
+params1 = params()
+params1.etopo_cg = 1
+cell1 = var.topo_cell()
+
+loader1 = io.ncdata.read_etopo_topo(cell1, params1, verbose=True)
+print(f"Loaded: {len(cell1.lat)} x {len(cell1.lon)} = {cell1.topo.shape}")
+print(f"Lat range: {cell1.lat.min():.4f} to {cell1.lat.max():.4f}")
+print(f"Lon range: {cell1.lon.min():.4f} to {cell1.lon.max():.4f}")
+print(f"Elevation range: {cell1.topo.min():.1f} to {cell1.topo.max():.1f} meters")
+print()
+
+
+# Example 2: Load with 4x coarse-graining (~60" resolution)
+print("Example 2: Loading with 4x coarse-graining...")
+params2 = params()
+params2.etopo_cg = 4
+cell2 = var.topo_cell()
+
+loader2 = io.ncdata.read_etopo_topo(cell2, params2)
+print(f"Loaded: {len(cell2.lat)} x {len(cell2.lon)} = {cell2.topo.shape}")
+print(f"Data reduction factor: {cell1.topo.size / cell2.topo.size:.1f}x")
+print()
+
+
+# Example 3: Load a small region
+print("Example 3: Loading a small region (35-37°N, -115 to -110°W)...")
+params3 = params()
+params3.lat_extent = [35.0, 37.0]
+params3.lon_extent = [-115.0, -110.0]
+params3.etopo_cg = 1
+cell3 = var.topo_cell()
+
+loader3 = io.ncdata.read_etopo_topo(cell3, params3)
+print(f"Loaded: {len(cell3.lat)} x {len(cell3.lon)} = {cell3.topo.shape}")
+print(f"Elevation range: {cell3.topo.min():.1f} to {cell3.topo.max():.1f} meters")
+print()
+
+
+# Example 4: Cross-dateline region (if needed)
+print("Example 4: Region spanning across dateline...")
+params4 = params()
+params4.lat_extent = [40.0, 50.0]
+params4.lon_extent = [170.0, -170.0]  # Crosses dateline
+params4.etopo_cg = 8
+cell4 = var.topo_cell()
+
+try:
+    loader4 = io.ncdata.read_etopo_topo(cell4, params4)
+    print(f"Loaded: {len(cell4.lat)} x {len(cell4.lon)} = {cell4.topo.shape}")
+except Exception as e:
+    print(f"Note: Dateline crossing may need verification: {e}")
+print()
+
+
+print("Done! All loaders completed successfully.")
+print("\nUsage tips:")
+print('- Set etopo_cg = 1 for full 15" resolution (very high-res!)')
+print('- Set etopo_cg = 4 for ~60" (~1.8 km at equator)')
+print('- Set etopo_cg = 8 for ~120" (~3.6 km at equator)')
+print("- Coarse-graining reduces memory and speeds up processing")

inputs/archive/debug_run.py

@@ -1,5 +1,4 @@
-"""User-defined parameters used in the debugger
-"""
+"""User-defined parameters used in the debugger"""
 
 import numpy as np
 from src import var

inputs/archive/lam_alaska_pmf_selector.py

@@ -3,7 +3,6 @@
 import matplotlib.pyplot as plt
 import pandas as pd
 
-
 # %%
 pmf_diffs = [
     -0.0652774741607357,