Metadata-Version: 2.4
Name: shamash-orogen
Version: 0.3.0
Summary: Algorithms that turn a planet's plate tectonics into a map: terrain, climate, hydrology, erosion, sand seas, settlements and networks.
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: shapely>=2

# shamash-orogen

Algorithms that turn a plate-tectonic history into terrain: the
reconstruction of the plates themselves, and from it global lon/lat grids that
GDAL and QGIS read directly. Its input is one tectonics phase as
[shamash-core](https://codeberg.org/schobernoise/shamash-core) lays it out
(`<body>/tectonics/phase-N/`: the plates and continents as drawn and every
plate's Euler pole; then a snapshot of them every few Myr, and the present with
new seafloor shared along mid-ocean ridges). shamash-core depends on it and
calls it in-process.

Plain Python with numpy and shapely; it never imports GDAL, QGIS or pygplates:

```bash
uv pip install --python ~/Dev/projects/shamash/shamash-core/venv/bin/python -e ~/Dev/projects/shamash/shamash-orogen
```

## Algorithms

One verb each, all `python -m orogen VERB PHASE OUT [--resolution DEG] [--crs WKTFILE]`
but `reconstruct`, which writes into the phase:

- **`reconstruct`**: the plates drawn at `duration` Ma turned rigidly about
  their Euler poles at a constant rate to 0 Ma (Rodrigues' rotation, Cox &
  Hart 1986), cut at the antimeridian and closed through a pole a plate comes
  to cover; continents split along the plates and carried by them; slivers of
  imperfect snapping resolved; the overlap and gap reported. Writes
  `reconstructed/{plates,continents}_<t>Ma.geojson` every `step` Myr and
  `next/`, the present made to tile the globe again (overlaps to the plate
  with more continent, gaps shared along mid-ocean ridges). ea's 19 plates,
  21 snapshots: 4 s.
- **`seafloor`**: seafloor age and depth at the present. Within each plate's
  half of an opened ocean, age runs from 0 at the ridge to the phase's duration
  at the plate's edge; ocean floor older than the phase is assumed `duration +
  --initial-age` (60 Myr). Depth from age by GDH1 (Stein & Stein 1992).
  Writes `seafloor_age.asc`, `seafloor_depth.asc`.
- **`history`**: where the action was. On a fixed grid, the Myr each cell lay
  under two or more plates (convergence) and under none (divergence) over the
  phase. Writes `overlap_myr.asc`, `gap_myr.asc`.
- **`boundaries`**: the present plate boundaries every 0.5°, classified from
  the two plates' Euler-pole velocities and the crust on each side:
  collision, subduction, island arc, rift, ridge, transform; with the
  shortening each has seen (closing rate × duration). Writes
  `boundaries.geojson`.
- **`orogeny`**: the relief the boundaries raise or cut, Earth-shaped
  heuristic profiles across each kind (flat-topped collision ranges, trench and
  cordillera, trench and island arc, rift valley). Writes `relief.asc`.
- **`dem`**: everything composed: continental lowlands rising inland, shelf
  and slope down to the age-depth ocean floor, the boundaries' relief, and
  fractal noise on the sphere, rougher where the ground was raised; relief and
  noise scaled by Earth's gravity over `--gravity`, clipped to `--range`.
  Writes `dem.png` (16-bit, `--range` spans black to white), `dem_8bit.png`
  (the same rounded away from sea level, for a drawing program to reproduce
  exactly) and `dem.json`,
  and with `--asc` the float grid `dem.asc`. ea's phase 1 at 0.1°: 2 minutes.

- **`climate`** (`orogen climate DEM_PNG OUT --planet planet.json --range LOW
  HIGH`): a body's climate from its heights and the parameters shamash-core
  writes to `climate/planet.json`. A seasonal energy balance model on the
  lon/lat grid (outgoing radiation linearised about the body's own
  equilibrium, moist and anisotropic heat transport, ice that brightens the
  albedo while its global mean stays the body's Bond albedo), Hadley cells
  from Held & Hou scaled to Earth's 30 deg, an ITCZ that follows the warmest
  air, rain at the ITCZ and along storm tracks, carried upwind over land by a
  semi-Lagrangian sweep, and the sea's heat carried by wind-driven gyres
  (`ocean.py`, the Stommel model: western boundary currents, coastal
  upwelling). Writes monthly-derived temperatures, precipitation,
  Köppen-Geiger classes (`koppen.py`, Kottek et al. 2006, coloured as Beck et
  al. 2018), solstice winds, ocean currents and `climate.json`. Earth at
  1 deg: 23 s, 64% of land cells in the right main class.

`--crs` takes the body's geographic CRS as WKT (shamash-core's
`qgis/project.json` holds it) and writes it beside each grid as a `.prj`.

## Roadmap

- [x] Seafloor age and depth, convergence footprint (0.5° in seconds)
- [x] Plate boundaries classified from relative Euler velocities: collision,
      subduction, island arc, rift, transform
- [x] Mountain, trench and arc profiles from them
- [x] One global DEM at 0.1°, as a 16-bit PNG
- [ ] Erosion: the ranges are smooth heuristic profiles plus noise, with no
      valleys cut by water
- [ ] More than one phase: ocean floor and mountains carried from phase to
      phase instead of each phase starting fresh
- [x] `shamash map terrain`, writing the inputs and running this
- [x] The reconstruction itself, replacing pygplates (2026-10-16)
- [x] A climate model with Köppen-Geiger classes (2026-10-16)
- [x] Wind-driven ocean currents and coastal upwelling (2026-10-16)
- [ ] Climate: monsoons, a North Atlantic Drift that reaches Norway, cloud-albedo
- [ ] Release to PyPI, since shamash-core depends on it
