# Earths
[](https://crates.io/crates/earths)
[](https://docs.rs/earth/)
Earths is a Rust Earth-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
Earths currently ships as:
- a Cargo package named `earths`
- a Rust library crate imported as `earth`
- a runtime binary named `earth`
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 Earth runtime.
## What This Crate Is For
Use Earths when you need one of these:
- a Rust dependency for Earth-system simulation logic
- a runtime process that advances Earth state continuously
- a backend core behind REST, gRPC, WebSocket, CLI, or custom IPC endpoints
- an orchestrated Earth node inside a larger multi-body simulation system
- a downstream consumer of scientific primitives provided by sciforge
## What This Crate Will Not Do
Earths does not provide:
- any UI
- any viewer
- any frontend
- any 2D, 3D, 5D, 8D, or other 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 Earths.
## Current Status
- version: `0.0.1`
- edition: `2024`
- license: `MIT`
- repository: `https://github.com/celestial4498-prog/Earths`
- validation gates: `cargo fmt`, `cargo clippy`, `cargo test`
- current automated test count: `347`
## Architecture
Earths is split into domain modules plus a runtime binary.
| `atmosphere` | atmospheric layers, density, pressure, winds, storms, climate, heatwaves |
| `biosphere` | ecosystems, vegetation, fauna, predator-prey dynamics |
| `geodata` | coordinates, elevation, bathymetry, region lookup |
| `geology` | earthquakes, tectonics, volcanism, mountains, erosion |
| `hydrology` | oceans, rivers, lakes, glaciers |
| `lighting` | solar position, day/night state, seasons |
| `physics` | orbit, rotation, tides, impacts |
| `rendering` | physical scattering, cloud, ocean, shader, and material data only |
| `satellites` | Moon state, artificial satellites, constellations |
| `temporal` | calendar, epochs, Delta-T, time scaling |
| `terrain` | analytic topography, geoid-informed terrain, LOD, mesh, biome texturing |
At the crate root, Earths also exposes Earth-specific derived constants and helpers built on top of sciforge.
## Package Name, Library Name, Binary Name
This matters for consumers.
- Cargo package name: `earths`
- Rust library import path: `earth`
- binary name: `earth`
Dependency declaration:
```toml
[dependencies]
earths = "0.0.1"
```
Rust import path:
```rust
use earth::temporal::calendar::DateTime;
```
## Library Usage
The library is intended to be imported module-by-module. You can use isolated domains, combine them yourself, or rely on the runtime binary to orchestrate them.
```rust
use earth::atmosphere::climate::ClimateState;
use earth::physics::orbit::EarthOrbit;
use earth::satellites::moon::MoonState;
use earth::temporal::calendar::DateTime;
let now = DateTime::new(2026, 4, 1, 12, 0, 0.0);
let climate = ClimateState::current();
let orbit = EarthOrbit::new();
let moon = MoonState::new();
assert!(now.to_julian_date() > 0.0);
assert!(orbit.current_radius() > 0.0);
assert!(climate.global_mean_temp_k > 0.0);
assert!(moon.distance() > 0.0);
```
## Runtime Binary
The binary in [src/main.rs](src/main.rs) is a long-running simulation process.
Today it:
- constructs a full `Earth` state object
- advances simulation time continuously
- updates orbital state, rotation, temporal state, Moon state, artificial satellites, climate, hydrology, biosphere, terrain, clouds, shaders, and observer-local state
- keeps running until externally stopped
It does not:
- open a window
- draw frames to screen
- embed a visual dashboard
- ship a user-facing viewer
Treat it as simulation infrastructure, not as a product UI.
## External Binary Integration
Earths is designed to consume external body binaries when they exist and to fall back internally when they do not.
Current Moon behavior in [src/satellites/moon.rs](src/satellites/moon.rs):
- if `MOON_BINARY` is set, Earths tries that executable first
- otherwise Earths searches `PATH` for `moon`
- if the binary is found and the IPC contract succeeds, Earths uses that external Moon backend
- if the binary is missing or IPC fails, Earths falls back automatically to its internal Moon simulation
This design is intentional:
- Earths does not need Moon source code
- Earths does not hardcode repository paths
- the same pattern can later be applied to Venus, Mars, and additional bodies
## Runtime Configuration
The runtime currently uses these environment variables:
| `EARTH_LAT` | `48.8566` | observer latitude in degrees |
| `EARTH_LON` | `2.3522` | observer longitude in degrees |
| `EARTH_ALT` | `35.0` | observer altitude in meters |
| `EARTH_IMPACT_SEED` | `42` | seed for stochastic impact events |
| `MOON_BINARY` | unset | explicit path to the Moon executable |
If `MOON_BINARY` is not set, binary discovery falls back to `PATH`.
## Why There Is a `rendering` Module
The `rendering` module is often misunderstood.
It exists to provide physically meaningful data structures and computations such as:
- atmospheric scattering parameters
- ocean spectral state
- cloud layers and densities
- shader-oriented physical uniforms
- material parameters tied to simulated state
It does not make this crate a visual application. It only exposes data that an external renderer could consume.
## Examples
The repository includes runnable examples:
- `cargo run --example climate_sim`
- `cargo run --example earthquake_sim`
- `cargo run --example tidal_sim`
- `cargo run --example check_elev`
These are diagnostics and usage samples, not product-facing applications.
## Validation
Recommended checks:
```sh
cargo fmt --check
cargo clippy
cargo test
```
The repository includes:
- integration tests in [tests](tests)
- runnable usage samples in [examples](examples)
## sciforge Strategy
Earths is intentionally downstream from sciforge.
That means:
- Earth-specific orchestration belongs here
- reusable scientific primitives should move upstream into sciforge when appropriate
- some roadmap items intentionally wait for sciforge updates instead of being duplicated locally
This crate should stay focused on Earth-specific composition and runtime behavior, not on re-implementing upstream scientific foundations unnecessarily.
## Limits
Earths intentionally stays within a narrow scope.
- no UI stack
- no viewer code
- no bundled DEM, bathymetry, or imagery payloads
- no requirement that companion body repositories already exist
- no hardcoded filesystem dependency on local sibling projects
Those constraints are part of the design, not missing features.
## Related Project Files
- [CHANGELOG.md](CHANGELOG.md): current implemented state
- [ComingSoon.md](ComingSoon.md): detailed roadmap and blocked items
- [LICENSE](LICENSE): MIT license text
## Publishing Notes
- `target/` is excluded in [Cargo.toml](Cargo.toml)
- the crate remains publishable without companion planet repositories
- external binaries are optional at runtime
## License
This project is licensed under the MIT License. See [LICENSE](LICENSE).