# `Sidereon.Collision`
[🔗](https://github.com/neilberkman/sidereon-ex/blob/main/lib/sidereon/collision.ex#L1)

Collision probability calculation for close approaches.

Computes `Pc` from relative state, covariance, and hard-body radius
using encounter-plane methods such as Foster 2D.

This module is intended for operational conjunction screening and
standards-based workflows such as CCSDS CDM ingestion.

The encounter geometry and `Pc` integration are implemented in the
`sidereon-core` core; this module validates the covariance inputs, selects
the method, marshals across the NIF, and packages the `%Result{}`.

# `params`

```elixir
@type params() :: %{
  r1: {float(), float(), float()},
  v1: {float(), float(), float()},
  cov1: [[float()]],
  r2: {float(), float(), float()},
  v2: {float(), float(), float()},
  cov2: [[float()]],
  hard_body_radius_km: float()
}
```

# `probability`

```elixir
@spec probability(
  params(),
  keyword()
) :: {:ok, Sidereon.Collision.Result.t()} | {:error, String.t()}
```

Compute collision probability from two objects' states and covariances.

All positions in km, velocities in km/s, covariances in km².

## Options
  * `:method` - one of:
    * `:equal_area` (default) - Foster 2D equal-area-square approximation
    * `:numerical` - Foster 2D with polar-grid numerical integration
    * `:alfano_2005` - Alfano (2005) 1D Simpson's rule with analytical
      cross-axis integration. Independent cross-check against the Foster
      methods.

Returns `{:ok, %Result{}}` or `{:error, reason}`.

# `probability_alfano_2005`

```elixir
@spec probability_alfano_2005(params()) ::
  {:ok, Sidereon.Collision.Result.t()} | {:error, String.t()}
```

Compute Pc using the Alfano (2005) method.

Uses 1D Simpson's composite rule along the principal x axis of the
encounter-plane covariance, with the cross-axis integration evaluated
analytically as the difference of two error functions. This uses a 1D
scan in place of the 2D quadrature grid used by `probability_numerical/1`
for elongated covariance cases.

Reference: Alfano, S., "A Numerical Implementation of Spherical Object
Collision Probability," Journal of the Astronautical Sciences, Vol. 53,
No. 1, Jan-Mar 2005, pp. 103-109.

# `probability_equal_area`

```elixir
@spec probability_equal_area(params()) ::
  {:ok, Sidereon.Collision.Result.t()} | {:error, String.t()}
```

Compute Pc using the 2D Foster method with equal-area square approximation.

# `probability_numerical`

```elixir
@spec probability_numerical(params()) ::
  {:ok, Sidereon.Collision.Result.t()} | {:error, String.t()}
```

Compute Pc using the 2D Foster method with numerical integration over the circle.

---

*Consult [api-reference.md](api-reference.md) for complete listing*