# gfold-core

A Rust implementation of the G-FOLD fuel-optimal powered-descent guidance
algorithm, solved as a second-order cone program with
[Clarabel](https://clarabel.org).

The min-fuel soft-landing problem is posed directly in conic form (no modeling
layer): the trajectory is discretized into `n` nodes with a first-order hold on
the thrust acceleration, lossless convexification turns the non-convex
thrust-magnitude bounds into second-order-cone constraints on a slack variable,
and the spacecraft mass is carried in log space so the dynamics stay linear.

## Modules

| Module | Responsibility |
|--------|----------------|
| `config`   | Problem inputs: spacecraft, environment, horizon (`n`, time of flight). |
| `derive`   | Precomputed log-mass linearization coefficients for the thrust bounds. |
| `assemble` | Builds the Clarabel problem — decision vector, cones, sparse `A`/`b`. |
| `solve`    | Runs Clarabel and unpacks a typed `Trajectory`. |
| `validate` | Independent physics/feasibility checks on a solution. |

## Usage

```rust
use gfold_core::{config::Config, solve::solve};

let cfg = Config::default();            // Mars descent, n = 100
let traj = solve(&cfg).expect("solve");
println!("final mass: {:.1} kg", traj.final_mass);
```

## Testing

```bash
cargo test              # unit + oracle-fixture tests
cargo test --release    # same, optimized
```

Solutions are checked two ways: an independent physics validator (`validate`)
and oracle fixtures generated by the Python CVXPY reference in `generator/`
(committed under `gfold-fixtures/data/`).

## Examples

```bash
cargo run --release --example accuracy   # discretization accuracy vs n
```

`accuracy` reconstructs the first-order-hold control from a solution, integrates
the true continuous dynamics with RK4, and reports the terminal and per-node
error against what the optimizer reported — a check that the discrete nodes lie
on the flown trajectory.
