keplerian-core/README.md

High-performance TypeScript library for orbital mechanics calculations, providing numerical integration, state propagation, and perturbation modeling for Keplerian orbits.

# Keplerian Core

`keplerian-core` is a foundational npm package that provides the core physics calculations for simulating orbital mechanics, specifically focusing on the two-body problem with various numerical integrators and force models. It is designed to be a robust and extensible library for educational and research purposes in computational physics and astrodynamics.

## Installation

To use `keplerian-core` in your project, you can install it via npm:

```bash
npm install keplerian-core
```

## Usage

The primary function for simulating orbital mechanics is `simulate`, which takes initial conditions and simulation parameters to generate a series of orbital states over time.

### `simulate` Function

```typescript
import { simulate } from './src/simulation';
import { InitialConditions, SimulationParams, OrbitalState } from './src/types/physics';

const initialConditions: InitialConditions = {
  position: { x: 149.6e9, y: 0 }, // Example: Earth's initial position (1 AU)
  velocity: { x: 0, y: 29780 } // Example: Earth's initial velocity
};

const simulationParams: SimulationParams = {
  gravitationalConstant: 6.67430e-11, // Universal Gravitational Constant
  centralMass: 1.989e30, // Mass of the central body (e.g., Sun)
  orbitingMass: 5.972e24, // Mass of the orbiting body (e.g., Earth)
  timeStep: 3600, // Time step for integration in seconds (e.g., 1 hour)
  totalTime: 365 * 24 * 3600, // Total simulation time in seconds (e.g., 1 Earth year)
  integrator: 'rk4', // Numerical integrator to use (e.g., 'rk4', 'euler', 'leapfrog', 'rk2', 'velocity-verlet')
  j2Perturbation: {
    enabled: false,
    radius: 6.371e6, // Radius of the central body (e.g., Earth's radius)
    j2: 0.00108263 // J2 coefficient (e.g., Earth's J2)
  }
};

const orbitalStates: OrbitalState[] = simulate(initialConditions, simulationParams);

console.log(orbitalStates[0]); // Initial state
console.log(orbitalStates[orbitalStates.length - 1]); // Final state
```

### Force Models

The `keplerian-core` package includes functions for calculating various forces acting on an orbiting body. These are primarily used internally by the integrators but can also be used independently for analysis.

```typescript
import { calculateGravitationalForce, calculateJ2PerturbationForce, calculateNetForce } from './src/physics/forces';
import { Vector2D } from './src/utils/vector';

const position: Vector2D = { x: 149.6e9, y: 0 };
const centralMass: number = 1.989e30;
const orbitingMass: number = 5.972e24;
const gravitationalConstant: number = 6.67430e-11;

// Gravitational Force
const gravitationalForce = calculateGravitationalForce(position, centralMass, orbitingMass, gravitationalConstant);
console.log('Gravitational Force:', gravitationalForce);

// J2 Perturbation Force
const j2Radius: number = 6.371e6;
const j2Coefficient: number = 0.00108263;
const j2Force = calculateJ2PerturbationForce(position, centralMass, orbitingMass, gravitationalConstant, j2Radius, j2Coefficient);
console.log('J2 Perturbation Force:', j2Force);

// Net Force (combines all enabled forces)
const netForce = calculateNetForce(position, centralMass, orbitingMass, gravitationalConstant, { enabled: true, radius: j2Radius, j2: j2Coefficient });
console.log('Net Force:', netForce);
```

### Integrators

The package provides several numerical integrators. While the `simulate` function abstracts their usage, you can also use them directly if needed.

```typescript
import { euler } from './src/physics/integrators/euler';
import { rk4 } from './src/physics/integrators/rk4';
import { leapfrog } from './src/physics/integrators/leapfrog';
import { rk2 } from './src/physics/integrators/rk2';
import { velocityVerlet } from './src/physics/integrators/velocity-verlet';
import { OrbitalState, SimulationParams } from './src/types/physics';

// Example of using RK4 integrator directly for a single step
const currentState: OrbitalState = {
  position: { x: 149.6e9, y: 0 },
  velocity: { x: 0, y: 29780 }
};

const params: SimulationParams = {
  gravitationalConstant: 6.67430e-11,
  centralMass: 1.989e30,
  orbitingMass: 5.972e24,
  timeStep: 3600,
  totalTime: 0, // Not relevant for single step
  integrator: 'rk4',
  j2Perturbation: { enabled: false }
};

const nextStateRK4 = rk4(currentState, params);
console.log('Next State (RK4):', nextStateRK4);

// Similar usage for euler, leapfrog, rk2, velocityVerlet
```

## Types

Key types used throughout the package are defined in `src/types/physics.ts`:

- `Vector2D`: Represents a 2D vector with `x` and `y` components.
- `InitialConditions`: Defines the starting position and velocity of the orbiting body.
- `J2PerturbationParams`: Configuration for J2 perturbation, including `enabled`, `radius`, and `j2` coefficient.
- `SimulationParams`: Comprehensive parameters for a simulation, including gravitational constant, masses, time step, total time, chosen integrator, and J2 perturbation settings.
- `OrbitalState`: Represents the state of the orbiting body at a given time, including its position and velocity.

Refer to the source file for detailed type definitions.