System Creation and Configuration

This guide covers the fundamental concepts of creating and configuring dynamical systems in HITEN, starting with the most basic operations and building up to more complex configurations.

Basic System Creation

HITEN provides several ways to create CR3BP systems, each suited for different use cases.

From Predefined Bodies

The simplest way to create a system is using predefined celestial bodies:

from hiten import System, Body

# Create Earth-Moon system
system = System.from_bodies("earth", "moon")

# Create Sun-Earth system
system = System.from_bodies("sun", "earth")

# Create Sun-Jupiter system
system = System.from_bodies("sun", "jupiter")

The system automatically computes the mass parameter mu and sets up the appropriate physical constants.

From Mass Parameter

For custom systems or when you only know the mass parameter:

from hiten import System, Body

# Create system directly from mu
system = System.from_mu(0.012150585609624)  # Earth-Moon mu

# Custom mass parameter
system = System.from_mu(0.000953875)  # Sun-Earth mu

Custom Body Creation

For maximum control, create custom bodies:

from hiten import Body, System

# Create custom primary body
primary = Body(
    name="Custom Primary",
    mass=5.972e24,  # kg
    radius=6.371e6,  # m
    color="#4A90E2"
)

# Create secondary body orbiting the primary
secondary = Body(
    name="Custom Secondary",
    mass=7.342e22,  # kg
    radius=1.737e6,  # m
    color="#F5A623",
    parent=primary
)

# Create system with custom bodies
system = System(primary, secondary, 384400e3)  # m

System Properties

Once created, systems provide access to key properties:

# Basic properties
print(f"Mass parameter: {system.mu}")
print(f"Primary: {system.primary.name}")
print(f"Secondary: {system.secondary.name}")
print(f"Distance: {system.distance} m")

# Libration points
l1 = system.get_libration_point(1)
l2 = system.get_libration_point(2)
l3 = system.get_libration_point(3)
l4 = system.get_libration_point(4)
l5 = system.get_libration_point(5)

print(f"L1 position: {l1.position}")
print(f"L2 position: {l2.position}")

Body Configuration

Bodies can be configured with various physical and visual properties:

from hiten import Body

# Earth-like body
earth = Body(
    name="Earth",
    mass=5.972e24,
    radius=6.371e6,
    color="#6B93D6"  # Blue color for plotting
)

# Moon-like body
moon = Body(
    name="Moon",
    mass=7.342e22,
    radius=1.737e6,
    color="#C0C0C0",  # Silver color
    parent=earth
)

Body Properties

Bodies provide access to their physical properties:

print(f"Name: {earth.name}")
print(f"Mass: {earth.mass} kg")
print(f"Radius: {earth.radius} m")
print(f"Color: {earth.color}")
print(f"Parent: {earth.parent}")

System Validation

HITEN performs basic validation on system parameters:

# Valid mass parameter range
try:
    system = System.from_mu(0.51)  # Invalid: mu must be <= 0.5
except ValueError as e:
    print(f"Error: {e}")

# Valid range
system = System.from_mu(0.01215)  # Earth-Moon system

Examples

Here are some commonly used system configurations:

Earth-Moon System

system = System.from_bodies("earth", "moon")
# mu ≈ 0.01215
# Distance ≈ 384,400,000 m

Sun-Earth System

system = System.from_bodies("sun", "earth")
# mu ≈ 3.00e-06
# Distance ≈ 149.6 billion m

Sun-Jupiter System

system = System.from_bodies("sun", "jupiter")
# mu ≈ 0.000953
# Distance ≈ 778.5 billion m

Custom Binary System

# Example: Binary star system
primary_star = Body("Primary Star", 2.0e30, 1.0e9)
secondary_star = Body("Secondary Star", 1.5e30, 8.0e8, parent=primary_star)

system = System(primary_star, secondary_star, 1.0e12)  # 1 AU

Next Steps

Once you have a system configured, you can:

Analyze libration points (see Libration Point Analysis)
Propagate orbits (see Basic Orbit Propagation)
Create periodic orbits (see Periodic Orbit Creation and Analysis)

For more advanced system configurations, see Custom Dynamical Systems.