# Pelagic — source and reproduction

Complete simulation, material renderer, encounter framing and film exporter for
Pelagic. The code generates its own geometry and material fields. No external
images, textures or model downloads are needed. Initial and selected simulation
states and the expected encounter pixel hash are included. This compact website
edition omits only the optional reference JPEG; all source and numerical states
are unchanged. The image command regenerates that JPEG, and `--verify` still
compares against the retained expected pixel hash.

Pelagic is the blue material treatment of Living Surface / Confluence; some
source filenames retain the name Confluence. The selected state is step 180,
with 207,195 living model cells.

## 1. Set up

Unzip the archive and open a terminal in its `Pelagic_Simulation` directory.
Use Python 3.12 and a C++17 compiler (`g++` or `clang++`). FFmpeg with `libx264`
is required only for the film. The tested environment is Linux, Python 3.12.14,
g++ 13.3.0 and FFmpeg 6.1.1. On Windows, use WSL. The build helper supports
macOS, but that platform has not been checked against the reference pixels.

```sh
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

The requirements pin NumPy 2.3.5, SciPy 1.17.0 and Pillow 12.3.0. Install the
compiler and FFmpeg separately with your operating system's package manager.
The image and film entry points compile `native.cpp` automatically. Set `CXX`
to select another compiler, or run `python build_native.py` to rebuild it.

## 2. Reproduce the images

```sh
python render_pelagic.py
```

This renders the supplied step-180 checkpoint and writes:

| File in `output/images/` | Dimensions | Purpose |
| --- | --- | --- |
| `Confluence_Pelagic.png` | 6000 × 4000 | Full landscape |
| `Pelagic_Encounter.png` | 3552 × 3996 | Primary encounter, 8:9 |
| `Pelagic_Encounter_Web.jpg` | 1440 × 1620 | Web encounter |
| `Confluence_Record.json` | — | Render settings |
| `Encounter_Record.json` | — | Crop and pixel hash |

The encounter is the native-resolution rectangle `(1150, 2, 4702, 3998)` from
the landscape: left/top inclusive, right/bottom exclusive. No colour adjustment
or deformation is applied. The encounter PNG has an sRGB profile and a 300 dpi
metadata tag, which does not change its pixel dimensions. The web image uses
Lanczos resizing and JPEG quality 94.

To render and compare encounter RGB pixels with the delivered original:

```sh
python render_pelagic.py --verify
```

Verification requires the default width and reference state. It compares
decoded pixels, since metadata and compression can alter file bytes without
changing the artwork. For a quick preview:

```sh
python render_pelagic.py --width 1500 --out preview_images
```

## 3. Reproduce the film

```sh
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 python make_pelagic_video.py --jobs 4
```

This rebuilds growth from `world/state_0000.npz`, verifies that it reaches the
supplied step-180 state, renders the moving geometry and fields, then writes
`Pelagic_Simulation.mp4`.

The export is 1920 × 1280, H.264, 24 fps, 841 frames and about 35.04 seconds,
with no audio: a one-second opening hold, about thirty seconds of development
and a four-second ending hold. The fixed viewpoint shows the full landscape,
with the still's palette, lighting and coating treatment. It does not use the
narrower encounter crop.

Use `--jobs 1` to reduce memory use. A smaller preview:

```sh
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 python make_pelagic_video.py --width 960 --jobs 2 --work preview_video --output Pelagic_Preview.mp4
```

Temporary checkpoints and frames stay in `rendered/`, or your `--work`
directory. Restart with the same command after an interruption; valid frames
are reused. Use a fresh work directory after changing resolution, model
settings or rendering code. Re-encode a complete default frame sequence with:

```sh
python make_pelagic_video.py --encode-only
```

Allow several GB of temporary disk space and several minutes of computation.
Default video workers used roughly under 1 GB each in the tested environment.
The 6000-pixel still needs several GB of available RAM.

## 4. Regenerate the world from its seed

The image command starts at the saved selected state. The film reruns growth
from the saved initial state. To regenerate the initial conditions as well:

```sh
python build_native.py
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 python run_confluence.py --out regenerated --steps 180 --seed 41 --strength 1.6
python render_pelagic.py --state regenerated/state_0180.npz --out regenerated_images --verify
```

The domain is 360 × 240 model units on a 320 × 213 resource grid. Model seed:
41; environment seed: 919; flow strength: 1.6; rendering coating coefficient:
2.0. Full numerical settings are in `world/config.json`. Model units and steps
are not calibrated biological lengths or times.

Exact trajectories can depend on platform, compiler and numerical-library
versions. The film command stops if its endpoint differs from the supplied
state. The supplied checkpoint remains available for rendering. Movie bytes
can vary with FFmpeg and encoder versions.

## Source map

| File | Role |
| --- | --- |
| `model.py` | Cell growth, resources, secretion, division and saved state |
| `environment.py` | Initial terrain, water and scalar transport |
| `buckling.py` | Reduced deforming-film calculation |
| `native.cpp` | Cell mechanics and geometry rasterization |
| `build_native.py` | Compile the native library |
| `run_confluence.py` | Run a world from its seed |
| `render_confluence.py` | Original material renderer and palettes |
| `render_pelagic.py` | Pelagic-only render and encounter exports |
| `animate_pelagic.py` | Render interpolated simulation states |
| `make_pelagic_video.py` | Regenerate, verify, render and encode the film |
| `validate_confluence.py` | Accounting and causal-rule checks |
| `MODEL.md` | Equations, material treatment and animation method |
| `world/` | Initial/selected states, configuration and trajectory metrics |
| `reference/` | Expected encounter pixel hash |
| `validation/` | Recorded model and source-release checks |
| `Render_Record.json` | Selected still settings and palette |
| `Animation_Record.json` | Delivered film settings and verification |
| `Manifest.json` | SHA-256 hashes of packaged files |

Change colours in `render_confluence.py` under `PALETTES['Pelagic']`. Change
growth settings in `model.py` or supply a configuration dictionary to `Surface`.
These changes create a new variation; reference checks describe the original.
To repeat the model checks after compiling:

```sh
python validate_confluence.py --world world/state_0180.npz --out validation_recheck
```