# Jupiters
> **Part of the [Celestial](https://celestial4498-prog.github.io/Celestial/) project.**
Jupiters is a Rust Jupiter-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
Jupiters currently ships as:
- a Cargo package named `jupiters`
- a Rust library crate imported as `jupiters`
- a runtime binary named `jupiters`
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 Jupiter runtime.
## What This Crate Is For
Use Jupiters when you need one of these:
- a Rust dependency for Jupiter-system simulation logic
- a runtime process that advances Jupiter state continuously
- a backend core behind REST, gRPC, WebSocket, CLI, or custom IPC endpoints
- an orchestrated Jupiter node inside a larger multi-body simulation system
- a downstream consumer of scientific primitives provided by sciforge
## What This Crate Will Not Do
Jupiters 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 | 1.8982e27 kg |
| Mean radius | 69 911 km |
| Surface gravity | ~24.8 m/s² (1-bar level) |
| Atmosphere | H₂/He gas giant (89.8 % H₂, 10.2 % He, trace CH₄) |
## Key Features
- H₂/He atmosphere with ammonia/water cloud decks
- Great Red Spot and zonal jet stream modeling
- Galilean moons (Io, Europa, Ganymede, Callisto)
- Metallic hydrogen interior and deep water layer
- Internal heat excess (1.67x received solar)
- Powerful magnetic field and radiation belts
- Diamond rain hypothesis in deep atmosphere
## Current Status
- version: `0.0.1`
- edition: `2024`
- license: `MIT`
- validation gates: `cargo fmt`, `cargo clippy`, `cargo test`
## Architecture
Jupiters is split into domain modules plus a runtime binary.
| `atmosphere` | H₂/He climate, ammonia cloud decks, Great Red Spot storms, zonal jet winds, heatwaves |
| `biosphere` | aerochemistry (H₂/CH₄ photolysis, acetylene haze), hypothetical deep-cloud ecosystems, aeroplankton |
| `geodata` | oblate ellipsoid coordinates (f = 0.0649), cloud-top elevation, atmospheric band regions |
| `geology` | interior icequakes, chemical erosion at depth, metallic hydrogen mantle, core mass fraction, cryovolcanism |
| `hydrology` | deep water layer, interior ammonia-water reservoirs, ionic ocean, convective plume transport |
| `lighting` | fast-rotation day/night (9.92 h), low axial tilt (3.13°), solar position at 5.2 AU |
| `physics` | Keplerian orbit (a = 5.2 AU, e = 0.0489), fast rotation (9.92 h), tidal interaction with Galilean moons, impacts |
| `rendering` | ammonia/CH₄ atmospheric scattering, multi-layer clouds, PBR materials, deep-ocean rendering, band shaders |
| `satellites` | Io, Europa, Ganymede, Callisto (Galilean moons), artificial probes |
| `temporal` | Jupiter day (35 730 s), 11.86-year orbit, J2000 epoch, time scaling |
| `terrain` | cloud-top heightmap, cube-face LOD, oblate spheroid mesh, atmospheric band texturing |
## Package Name, Library Name, Binary Name
- Cargo package name: `jupiters`
- Rust library import path: `jupiters`
- binary name: `jupiters`
Dependency declaration:
```toml
[dependencies]
jupiters = "0.0.1"
```
Rust import path:
```rust
use jupiters::physics::orbit;
```
## Runtime Binary
The binary in src/main.rs is a long-running simulation process. It constructs a full Jupiter 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 ammonia/CH₄ atmospheric scattering, multi-layer cloud parameters, PBR materials, and band shader 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
Jupiters is intentionally downstream from sciforge. Jupiter-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