Earths

Part of the Celestial project.

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.2
• 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.

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:

[dependencies]
earths = "0.0.2"

Rust import path:

use earths::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.

use earths::atmosphere::climate::ClimateState;
use earths::physics::orbit::EarthOrbit;
use earths::satellites::moon::MoonState;
use earths::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 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:

• 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:

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:

cargo fmt --check
cargo clippy
cargo test

The repository includes:

• integration tests in tests
• runnable usage samples in 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: current implemented state
• ComingSoon.md: detailed roadmap and blocked items
• LICENSE: MIT license text

Publishing Notes

• target/ is excluded in 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.