# Mercurys

> **Part of the [Celestial](https://celestial4498-prog.github.io/Celestial/) project.**

Mercurys is a Rust Mercury-system simulation core.

It computes state, evolves that state over time, and exposes simulation-ready data for downstream consumers. It is meant to sit behind endpoints, IPC, or another orchestrating runtime. It is not a UI crate, not a viewer, and not a frontend.

## Scope

Mercurys currently ships as:

- a Cargo package named `mercurys`
- a Rust library crate imported as `mercurys`
- a runtime binary named `mercurys`

The project combines scientific subsystems for:

- atmosphere
- biosphere
- geodata
- geology
- hydrology
- lighting
- physics
- rendering-oriented physical state
- satellites
- temporal systems
- terrain

The library exposes reusable domain modules. The binary assembles them into a continuously ticking Mercury runtime.

## What This Crate Is For

Use Mercurys when you need one of these:

- a Rust dependency for Mercury-system simulation logic
- a runtime process that advances Mercury state continuously
- a backend core behind REST, gRPC, WebSocket, CLI, or custom IPC endpoints
- an orchestrated Mercury node inside a larger multi-body simulation system
- a downstream consumer of scientific primitives provided by sciforge

## What This Crate Will Not Do

Mercurys does not provide:

- any UI
- any viewer
- any frontend
- any visualization layer
- any render window or presentation loop
- any bundled large datasets
- any hardcoded dependency on sibling repositories

## Key Physical Parameters

| Parameter | Value |
|---|---|
| Mass | 3.30e23 kg |
| Mean radius | 2 440 km |
| Surface gravity | 3.7 m/s² |
| Atmosphere | exosphere only (Na, K, Ca, O, H₂ — no true atmosphere) |

## Key Features

- Exosphere with species column densities and Jeans escape modeling
- 3:2 spin-orbit resonance (solar day = 176 Earth days)
- Extreme temperature range (100 K nightside — 700 K subsolar)
- Giant iron core (> 60 % of planet mass)
- Lobate scarps and tectonic contraction seismicity
- MESSENGER and BepiColombo mission orbital parameters
- Caloris basin impact modeling
- Permanently shadowed crater polar ice deposits

## Current Status

- version: `0.0.1`
- edition: `2024`
- license: `MIT`
- validation gates: `cargo fmt`, `cargo clippy`, `cargo test`

## Architecture

Mercurys is split into domain modules plus a runtime binary.

| Module | Responsibility |
|---|---|
| `atmosphere` | exosphere species densities, CME impacts, solar wind dynamic pressure, thermal extremes |
| `biosphere` | abiotic confirmation (no ecosystems, fauna, or vegetation), UV flux estimates |
| `geodata` | near-spherical coordinates, crater/basin topography, named regions |
| `geology` | lobate scarp seismicity, space weathering erosion, crater rim isostasy, giant iron core, volcanic plains |
| `hydrology` | permanently shadowed region (PSR) polar ice, no oceans/rivers/lakes |
| `lighting` | 3:2 spin-orbit day/night, near-zero seasonal variation, solar position from true anomaly |
| `physics` | highly eccentric orbit (e = 0.2056), GR precession, 3:2 resonance rotation, strong solar tides, Caloris impact |
| `rendering` | null atmospheric scattering, dark regolith PBR materials, no clouds/oceans |
| `satellites` | no natural satellites, MESSENGER/BepiColombo artificial probes |
| `temporal` | 87.97-day year, solar day counting, J2000 epoch, mean longitude polynomials |
| `terrain` | procedural crater/basin DEM, cube-face LOD, spherical mesh, surface type texturing |

## Package Name, Library Name, Binary Name

- Cargo package name: `mercurys`
- Rust library import path: `mercurys`
- binary name: `mercurys`

Dependency declaration:

```toml
[dependencies]
mercurys = "0.0.1"
```

Rust import path:

```rust
use mercurys::physics::orbit;
```

## Runtime Binary

The binary in src/main.rs is a long-running simulation process. It constructs a full Mercury state object, advances simulation time continuously, and keeps running until externally stopped. It does not open a window, draw frames, or embed any visual dashboard.

## Why There Is a `rendering` Module

The `rendering` module provides physically meaningful data structures for atmospheric scattering (null on Mercury), PBR material parameters for the dark regolith surface, and shader-oriented uniforms. It does not make this crate a visual application.

## Examples

- `cargo run --example climate_sim`
- `cargo run --example earthquake_sim`
- `cargo run --example tidal_sim`

## Validation

```sh
cargo fmt --check
cargo clippy
cargo test
```

## sciforge Strategy

Mercurys is intentionally downstream from sciforge. Mercury-specific orchestration belongs here; reusable scientific primitives should move upstream into sciforge when appropriate.

## Related Project Files

- [CHANGELOG.md](ChangeLog.md): current implemented state
- [ComingSoon.md](ComingSoon.md): detailed roadmap and blocked items
- [LICENSE](LICENSE): MIT license text
