cometsfactory 0.0.3

Comet factory — classify, build and catalogue comets of any type: short-period, long-period, Halley-type, sungrazer, interstellar, main-belt comet, centaur-transition, and extinct.
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
89
90
91
92

# CometsFactory

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

Procedural comet generator for the **Celestial Bodies** ecosystem.  
Build, classify, and catalogue comets of every dynamical family — from Jupiter-family short-period comets to interstellar visitors.

---

## Architecture

| Module | File(s) | Purpose |
|---|---|---|
| **config** | `parameters.rs` | Physical constants, orbital helpers, sublimation constants |
| **types** | `short_period.rs`, `long_period.rs`, `halley_type.rs`, `sungrazer.rs`, `interstellar.rs`, `main_belt_comet.rs`, `centaur_transition.rs`, `extinct.rs` | 8 comet types with builder pattern |
| **physics** | `gravity.rs`, `sublimation.rs` | Binding energy, tides, Roche limit, sublimation rates, gas production, non-grav acceleration |
| **engine** | `orbits.rs`, `evolution.rs`, `coma.rs` | Keplerian propagation, mantle growth, spin-up, coma/tail modelling |
| **observables** | `photometry.rs`, `tail.rs` | Total/nuclear magnitudes, Afρ, dust/ion tail orientation, disconnection events |
| **utils** | `helpers.rs`, `io.rs` | Angle conversions, summary lines for all 8 types |

---

## Comet Types

| # | Type | Key Features |
|---|---|---|
| 1 | **ShortPeriod** | Jupiter-family comets, P < 20 yr, 2 < T_J < 3 |
| 2 | **LongPeriod** | Oort Cloud origin, P > 200 yr, dynamically new flag |
| 3 | **HalleyType** | 20 < P < 200 yr, T_J < 2, retrograde detection |
| 4 | **Sungrazer** | Kreutz/Marsden/Kracht/Meyer groups, tidal disruption |
| 5 | **Interstellar** | Hyperbolic orbits (e > 1), excess velocity |
| 6 | **MainBeltComet** | Asteroid-like orbits (T_J > 3), sublimation-driven activity |
| 7 | **CentaurTransition** | CO-driven outbursts, giant-planet region, dynamical lifetime |
| 8 | **Extinct** | Dormant/extinct states, mantle thickness, reactivation potential |

All types expose a **builder pattern**: `new()` → `with_*()` chainable methods.

---

## Usage

```rust
use cometsfactory::types::*;

let jfc = ShortPeriod::new(500.0, 3.5, 0.6)
    .with_density(600.0)
    .with_inclination(10.0)
    .with_active_fraction(0.03);

assert!(jfc.is_jupiter_family());
assert!(jfc.perihelion() < jfc.semi_major_axis);
```

```rust
use cometsfactory::physics::sublimation;

let q = sublimation::gas_production_rate(1000.0, 0.05, 1.0, 0.04);
assert!(q > 1.0e20);
```

---

## Tests

73 tests across 3 test suites:
- **types_tests** — 38 tests (builders, orbital properties, classifications)
- **physics_tests** — 14 tests (gravity, sublimation, thermal)
- **engine_tests** — 21 tests (orbits, evolution, coma)

```bash
cargo test --all-targets
```

## Examples

| Example | Description |
|---|---|
| `generation` | Creates all 8 comet types, exercises enum dispatch |
| `physics` | Gravity + sublimation computations on a Jupiter-family comet |
| `observables` | Photometry, Afρ, dust/ion tails, disconnection events |

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

---

## License

MIT — Copyright (c) 2026 Rayan Morel