suns 0.0.1

Sun celestial simulation crate for the MilkyWay SolarSystem workspace
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# Suns

A comprehensive Rust crate for modeling the physics, structure, and dynamics of the Sun as a G2V main-sequence star. Part of the **MilkyWay / SolarSystem** engine.

## Scope

This crate provides first-principles solar physics computations covering:

- Internal structure (core, radiative zone, convective zone, tachocline)
- Nuclear fusion (pp chains, CNO cycle, energy generation rates)
- Magnetic fields (differential rotation, dynamo, reconnection)
- Energy transport (radiative transfer, convection, opacity models)
- Atmospheric layers (photosphere, chromosphere, transition region)
- Plasma physics (corona, solar wind, prominences, flares)
- Planetary interactions (tidal forces, radiation pressure, barycenter)
- Solar activity events (flares, CMEs, sunspot cycles)

Uses [sciforge](https://crates.io/crates/sciforge) for fundamental constants and basic astrophysics functions.

## Architecture

| Module | Submodule | Description |
|---|---|---|
| `physics` | `stellar_structure` | Layer model, timescales, gravity, virial theorem |
| `physics` | `nuclear_fusion` | pp/CNO reactions, Gamow window, tunneling |
| `physics` | `magnetic_fields` | B-field regions, rotation, dynamo, Larmor radii |
| `physics` | `energy_transport` | Radiative/convective transfer, opacity, limb darkening |
| `plasma` | `corona` | Coronal regions, loops, X-ray/EUV emission |
| `plasma` | `solar_flare` | GOES classification, reconnection, evaporation |
| `plasma` | `prominences` | Quiescent/active, KS support, eruption dynamics |
| `plasma` | `solar_wind` | Parker solution, spiral, heliosphere |
| `layers` | `photosphere` | Stefan-Boltzmann flux, granulation, Wien peak |
| `layers` | `chromosphere` | Spicules, Hα opacity, transition region |
| `layers` | `convective_zone` | Mixing length, differential rotation, overshoot |
| `layers` | `radiative_zone` | Photon diffusion, tachocline, g-mode periods |
| `interactions` | `tidal_forces` | Planetary tides, Hill spheres, Poynting-Robertson |
| `events` | `solar_flares` | Nanoflare heating, Carrington event, power-law frequency |
| `events` | `coronal_mass_ejections` | CME propagation, drag model, Dst index |
| `events` | `sunspots` | Wolf number, butterfly diagram, TSI variation |

## Constants

The crate root (`lib.rs`) exports ~80 solar physics constants and 6 `LazyLock` computed values:

- Fundamental: `SOLAR_RADIUS`, `SOLAR_LUMINOSITY`, `SOLAR_EFFECTIVE_TEMP`, `SOLAR_MASS` (via sciforge)
- Core: `SOLAR_CORE_TEMP`, `SOLAR_CORE_DENSITY`, `SOLAR_CORE_PRESSURE`
- Layers: `CORE_RADIUS_FRAC`, `RADIATIVE_ZONE_OUTER_FRAC`, `CONVECTIVE_ZONE_BASE_FRAC`
- Flare/CME: `FLARE_CLASS_C_FLUX`, `CME_SPEED_SLOW`, `CME_SPEED_FAST`
- Computed: `SOLAR_ESCAPE_VELOCITY`, `SOLAR_SURFACE_FLUX`, `DEBYE_LENGTH_CORONA`, etc.

## Usage

```rust
use sun::physics::stellar_structure::{core, surface_gravity};
use sun::plasma::corona::quiet_corona;
use sun::events::sunspots::cycle_25;

let solar_core = core();
println!("Core temperature: {:.2e} K", solar_core.mean_temperature());
println!("Surface gravity: {:.1} m/s²", surface_gravity());

let corona = quiet_corona();
println!("Corona β = {:.2e}", corona.plasma_beta());

let mut cycle = cycle_25();
cycle.phase = 0.5;
println!("SSN at solar max: {:.0}", cycle.current_ssn());
```

## Examples

```bash
cargo run --example solar_flare_sim
cargo run --example corona_mapping
cargo run --example energy_transport_demo
```

## Tests

```bash
cargo test
```

Five integration test suites: `physics_tests`, `plasma_tests`, `layers_tests`, `interactions_tests`, `events_tests` (~200 tests total).

## License

See [LICENSE](LICENSE).