# Marss
Marss is a Rust Mars-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
Marss currently ships as:
- a Cargo package named `marss`
- a Rust library crate imported as `marss`
- a runtime binary named `marss`
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 Mars runtime.
## What This Crate Is For
Use Marss when you need one of these:
- a Rust dependency for Mars-system simulation logic
- a runtime process that advances Mars state continuously
- a backend core behind REST, gRPC, WebSocket, CLI, or custom IPC endpoints
- an orchestrated Mars node inside a larger multi-body simulation system
- a downstream consumer of scientific primitives provided by sciforge
## What This Crate Will Not Do
Marss 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
If you want visual output, that belongs in another crate or another process consuming Marss.
## Key Physical Parameters
| Mass | 6.4171e23 kg |
| Mean radius | 3 389.5 km |
| Surface gravity | 3.72 m/s² |
| Atmosphere | CO₂-dominated (95.3 %), thin (636 Pa surface pressure) |
## Key Features
- CO₂-dominated atmosphere with dust storm modeling
- Olympus Mons (21.9 km) and Tharsis volcanic province
- Phobos and Deimos satellite dynamics
- Polar ice caps (H₂O + CO₂ ice)
- Ancient hydrology (Oceanus Borealis, Kasei Valles, Jezero crater lake)
- Martian sol/year calendar and solar longitude (Ls) tracking
- Butterscotch sky rendering from Rayleigh/dust scattering
## Current Status
- version: `0.0.1`
- edition: `2024`
- license: `MIT`
- validation gates: `cargo fmt`, `cargo clippy`, `cargo test`
## Architecture
Marss is split into domain modules plus a runtime binary.
| `atmosphere` | CO₂ climate, dust storms, saltation winds, barometric pressure, heatwaves |
| `biosphere` | hypothetical habitability scoring, vegetation survival modeling |
| `geodata` | Mars oblate ellipsoid coordinates, Hellas/Argyre basins, DEM elevation, regions |
| `geology` | marsquakes, aeolian erosion, Olympus Mons isostasy, stagnant lid tectonics, volcanism |
| `hydrology` | polar caps, paleolakes (Jezero), ancient oceans, channel discharge estimates |
| `lighting` | solar longitude (Ls) day/night, Martian seasons, solar position |
| `physics` | Keplerian orbit (e = 0.0934), sol/sidereal rotation, Phobos/solar tides, impacts |
| `rendering` | Rayleigh/dust scattering, dust rendering, PBR regolith/basalt materials, sky color |
| `satellites` | Phobos, Deimos, artificial probes |
| `temporal` | Mars sol date, Mars year counting, J2000 epoch, time scaling |
| `terrain` | Olympus Mons / Hellas DEM, cube-face LOD, spherical mesh, biome texturing |
## Package Name, Library Name, Binary Name
- Cargo package name: `marss`
- Rust library import path: `marss`
- binary name: `marss`
Dependency declaration:
```toml
[dependencies]
marss = "0.0.1"
```
Rust import path:
```rust
use marss::physics::orbit;
```
## Runtime Binary
The binary in src/main.rs is a long-running simulation process.
Today it:
- constructs a full Mars state object
- advances simulation time continuously
- updates orbital state, rotation, temporal state, satellite state, climate, hydrology, terrain, clouds, shaders, and observer-local state
- 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 and computations for atmospheric scattering parameters, dust rendering, shader-oriented physical uniforms, and material parameters tied to simulated state. 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
Marss is intentionally downstream from sciforge. Mars-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