# 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
| 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.
| `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