asteroidsfactory 0.0.3

# AsteroidsFactory

> **Part of the [Celestial](https://celestial4498-prog.github.io/Celestial/) project.**

A comprehensive Rust crate for generating and simulating asteroids across all dynamical families and compositions. From near-Earth objects and main belt residents to trojans, centaurs, binary systems, rubble piles, metallic bodies, and potentially hazardous asteroids. Pure procedural — no hardcoded presets, all parameters explicit. Part of the **celestial** workspace.

## Scope

This crate provides first-principles asteroid physics computations covering:

- Asteroid generation (8 types: near-Earth, main belt, trojan, centaur, binary, rubble pile, metallic, PHA)
- Orbital mechanics (Tisserand parameter, Kirkwood gaps, Hill sphere, Kozai-Lidov)
- Gravitational physics (binding energy, Roche limits, tidal forces, mutual orbits)
- Thermal physics (Yarkovsky drift, YORP torque, equilibrium temperature, thermal inertia)
- Collisional evolution (impact energy, crater scaling, catastrophic disruption threshold)
- Observables (absolute/apparent magnitude, lightcurves, spin barrier, phase functions)
- Impact risk assessment (Torino scale, crater diameter, deflection delta-v)

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

## Architecture

| Module | Submodule | Description |
|---|---|---|
| `config` | `parameters` | Physical constants, orbital helpers, sphere mass/volume |
| `types` | `near_earth` | Apollo/Amor/Aten/Atira NEAs, MOID, Tisserand parameter |
| `types` | `main_belt` | C/S/M/B/D/V/X spectral types, Kirkwood gap detection |
| `types` | `trojan` | L4/L5 Lagrange points, libration period, stability |
| `types` | `centaur` | Tisserand classification, cometary activity, snow line |
| `types` | `binary` | Mutual orbital mechanics, contact binary detection, Roche limit |
| `types` | `rubble_pile` | Porosity, spin barrier, YORP timescale, cohesionless strength |
| `types` | `metallic` | Iron/nickel fractions, differentiation, core radius estimate |
| `types` | `pha` | Impact energy, Torino scale, crater diameter, deflection |
| `physics` | `gravity` | Binding energy, Roche limits, tidal force, angular momentum |
| `physics` | `thermal` | Yarkovsky drift, YORP torque, thermal inertia, skin depth |
| `engine` | `orbits` | Mean motion, synodic period, resonance width, Kozai-Lidov |
| `engine` | `evolution` | Collisional lifetime, space weathering, regolith depth |
| `engine` | `collisions` | Impact velocity, crater scaling, disruption threshold |
| `observables` | `photometry` | Absolute/apparent magnitude, H-albedo diameter, thermal flux |
| `observables` | `lightcurve` | Amplitude, spin barrier, tumbling damping, binary eclipses |
| `utils` | `helpers` | Coordinate transforms, interpolation, angle conversion |
| `utils` | `io` | Summary line formatting for all asteroid types |

## Usage

```rust
use asteroidsfactory::types::near_earth::NearEarthAsteroid;
use asteroidsfactory::types::main_belt::MainBeltAsteroid;
use asteroidsfactory::types::pha::PotentiallyHazardousAsteroid;
use asteroidsfactory::types::binary::BinaryAsteroid;

let apollo = NearEarthAsteroid::new(500.0, 2500.0, 1.5, 0.4)
    .with_inclination(10.0)
    .with_albedo(0.15);

let vesta = MainBeltAsteroid::new(265000.0, 3456.0, 2.362)
    .with_spectral_type(main_belt::SpectralType::V);

let apophis = PotentiallyHazardousAsteroid::new(185.0, 2600.0, 0.922, 0.191, 0.00025)
    .with_albedo(0.3);

let didymos = BinaryAsteroid::new(390.0, 80.0, 2170.0, 1180.0)
    .with_heliocentric_orbit(1.644, 0.384);
```

## Examples

```bash
cargo run --example generation
cargo run --example physics
cargo run --example observables
```

## Tests

```bash
cargo test
```

78 tests across three integration test suites: `types_tests`, `physics_tests`, `engine_tests`.

## License

See [LICENSE](LICENSE).