Ephemerista User Manual

Table of Contents

  1. Introduction

  2. Installation and Setup

  3. Getting Started

  4. Scenario Configuration

  5. Spacecraft and Ground Station Configuration

  6. Propagation Setup

  7. Visibility Analysis

  8. Communication Systems Configuration

  9. Link Budget Analysis

  10. Constellation Configuration

  11. Coverage Analysis

  12. Navigation Analysis

  13. Visualization and Data Export

  14. Advanced Features

  15. Examples and Tutorials

  16. Troubleshooting and Reference

Introduction

Ephemerista is a comprehensive space mission analysis tool that provides capabilities for satellite constellation design, orbital propagation, visibility analysis, communication link budgets, coverage analysis, and navigation performance evaluation. It offers both a web-based graphical user interface (GUI) and a Python API for programmatic access.

Key Features

  • Interactive 3D visualization of satellites and ground stations

  • Multiple orbital propagation methods (SGP4, numerical, semi-analytical, OEM)

  • Visibility and coverage analysis for satellite constellations

  • RF link budget calculations with interference modeling

  • Navigation dilution of precision (DOP) analysis

  • Constellation design tools (Walker patterns, Streets-of-Coverage)

  • Communication system modeling with antenna patterns

  • Extensible framework for custom analysis workflows

Architecture Overview

Ephemerista is built on several core concepts:

GUI vs Python API

Use the GUI when:

  • Performing interactive mission design

  • Visualizing orbital scenarios in 3D

  • Quick prototyping and what-if analyses

  • Demonstrating concepts to stakeholders

Use the Python API when:

  • Automating complex analysis workflows

  • Performing batch processing or optimization

  • Integrating with other tools

  • Developing custom analysis modules

For complete API documentation, see the API.

Installation and Setup

System Requirements

GUI Requirements

  • Modern web browser with WebGL support

  • Internet connection for initial loading

  • Recommended: Chrome, Firefox, or Safari

Python API Requirements

  • Python 3.12 or higher

  • Required data files: Earth Orientation Parameters (EOP), planetary ephemerides, and Orekit data package

Installation

GUI Access

  1. Navigate to the Ephemerista web interface

  2. The application loads with a default empty scenario

Main application interface

Main application interface showing the three-panel layout with scenario configuration on the left, 3D visualization in the center, and analysis panel on the right

Python API Installation

pip install ephemerista

Data File Setup

Both GUI and Python require data files for high-precision calculations:

Earth Orientation Parameters (EOP)

  • File: finals2000A.all.csv from IERS

  • Purpose: High-precision coordinate transformations

  • Update Frequency: Weekly recommended

Planetary Ephemerides

  • File: DE440s or similar JPL ephemeris file

  • Purpose: Precise planetary positions for perturbation calculations

  • Format: SPICE kernel (.bsp)

Initialization

GUI Initialization

The GUI automatically loads required data files when starting.

Python Initialization

import ephemerista

# Initialize with data directory containing EOP and ephemeris files
ephemerista.init(
    eop_file="path/to/finals2000A.all.csv",
    ephemeris_file="path/to/de440s.bsp",
    orekit_data_dir="path/to/orekit-data"  # Optional
)

[CODE BLOCK PLACEHOLDER: Complete initialization example with error handling]

Getting Started

GUI: Launching the Application

The Ephemerista GUI consists of three main sections:

  • Left Panel: Scenario configuration forms

  • Center Panel: 3D visualization and analysis results (tabbed interface)

  • Right Panel: Analysis controls and results

Interface overview with labeled panels

Interface overview with labeled panels showing the main components of the Ephemerista GUI

Python: Basic Script Structure

#!/usr/bin/env python3
import ephemerista
from ephemerista import Scenario
from ephemerista.time import Epoch, TimeScale
from datetime import datetime, timezone

# Initialize Ephemerista
ephemerista.init(
    eop_file="data/finals2000A.all.csv",
    ephemeris_file="data/de440s.bsp"
)

# Create a scenario
scenario = Scenario(
    name="My First Mission",
    start_time=Epoch.from_datetime(
        datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
        TimeScale.UTC
    ),
    end_time=Epoch.from_datetime(
        datetime(2024, 1, 2, 12, 0, 0, tzinfo=timezone.utc),
        TimeScale.UTC
    ),
    time_step=60.0  # seconds
)

Quick Example: Simple Scenario

GUI Approach

  1. Enter scenario name: “LEO Observation Mission”

  2. Set start and end times using the date/time pickers (see Scenario Configuration)

  3. Click “Add Asset” → “Spacecraft”

  4. Select “SGP4” propagator and paste a TLE (see Spacecraft Configuration)

  5. Click “Add Asset” → “Ground Station”

  6. Enter location coordinates (see Ground Station Configuration)

  7. Navigate to “Analyses” tab and select “Visibility” (see Visibility Analysis)

  8. Click “Run Analysis”

Python Approach

from ephemerista.assets import Spacecraft, GroundStation
from ephemerista.propagators.sgp4 import Sgp4Propagator

# Create spacecraft from TLE
tle_line1 = "1 25544U 98067A   21001.00000000  .00000000  00000-0  00000+0 0    06"
tle_line2 = "2 25544  51.6400 000.0000 0000000   0.0000 000.0000 15.50000000000000"

spacecraft = Spacecraft(
    name="ISS",
    propagator=Sgp4Propagator.from_tle(tle_line1, tle_line2)
)

# Create ground station
ground_station = GroundStation(
    name="Mission Control",
    longitude=-95.4,
    latitude=29.6,
    altitude=50.0,
    minimum_elevation=10.0
)

# Add to scenario
scenario.add_asset(spacecraft)
scenario.add_asset(ground_station)

# Run visibility analysis
from ephemerista.analysis.visibility import Visibility
visibility_analyzer = Visibility(scenario)
results = visibility_analyzer.calculate()

Scenario Configuration

Basic Scenario Setup

Scenarios are the central containers for mission analysis. They define the temporal boundaries and coordinate systems for all calculations.

See also

For detailed API documentation, see Scenarios – ephemerista.scenarios and Time – ephemerista.time.

GUI Configuration

  1. Scenario Name: Enter a descriptive name for your scenario

  2. Time Configuration:

    • Start Time: Set the simulation start time (UTC)

    • End Time: Set the simulation end time (UTC)

    • Time Step: Define the temporal resolution in seconds

  3. Reference Frame: Select the coordinate reference frame (typically ICRF)

  4. Origin: Choose the central body (typically Earth)

Scenario configuration form

Scenario configuration form showing time settings, reference frame selection, and origin selection

Python Configuration

from ephemerista import Scenario
from ephemerista.time import Epoch, TimeScale
from ephemerista.frames import ReferenceFrame
from datetime import datetime, timezone

# Create a new scenario
scenario = Scenario(
    name="Mission Analysis Example",
    start_time=Epoch.from_datetime(
        datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
        TimeScale.UTC
    ),
    end_time=Epoch.from_datetime(
        datetime(2024, 1, 2, 12, 0, 0, tzinfo=timezone.utc),
        TimeScale.UTC
    ),
    time_step=60.0  # seconds
)

# Configure reference frame (optional, defaults to ICRF)
scenario.reference_frame = ReferenceFrame.ICRF

Time Scale Management

Ephemerista supports multiple time scales:

  • UTC: Coordinated Universal Time

  • TAI: International Atomic Time

  • TT: Terrestrial Time

  • GPS: GPS Time

GUI Time Scale Selection

Time scale selection dropdown

Time scale selection dropdown with available options (UTC, TAI, TT, GPS)

Python Time Scale Usage

from ephemerista.time import TimeScale

# Available time scales
time_scales = [
    TimeScale.UTC,    # Coordinated Universal Time
    TimeScale.TAI,    # International Atomic Time
    TimeScale.TT,     # Terrestrial Time
    TimeScale.GPS     # GPS Time
]

# Convert between time scales
utc_epoch = Epoch.from_datetime(datetime.now(timezone.utc), TimeScale.UTC)
tai_epoch = utc_epoch.to_time_scale(TimeScale.TAI)

Reference Frames

Configure coordinate reference frames:

See also

For complete reference frame documentation, see Frames – ephemerista.frames.

Common Reference Frames

  • ICRF: International Celestial Reference Frame

  • GCRF: Geocentric Celestial Reference Frame

  • ITRF: International Terrestrial Reference Frame

  • EME2000: Earth Mean Equator 2000

Python Reference Frame Configuration

from ephemerista.frames import ReferenceFrame

# Common reference frames
frames = {
    "ICRF": ReferenceFrame.ICRF,      # International Celestial Reference Frame
    "GCRF": ReferenceFrame.GCRF,      # Geocentric Celestial Reference Frame
    "ITRF": ReferenceFrame.ITRF,      # International Terrestrial Reference Frame
    "EME2000": ReferenceFrame.EME2000  # Earth Mean Equator 2000
}

scenario.reference_frame = ReferenceFrame.ICRF

Spacecraft and Ground Station Configuration

Adding Assets

Assets are the physical entities in your scenario - spacecraft orbiting in space and ground stations on Earth.

See also

For complete asset API documentation, see Assets – ephemerista.assets.

GUI: Adding Assets

  1. Click the “Add Asset” button in the scenario configuration panel

  2. Choose between:

    • Spacecraft: Orbiting vehicles

    • Ground Station: Earth-based facilities

[SCREENSHOT PLACEHOLDER: Asset type selection dialog]

Python: Creating Assets

from ephemerista.assets import Spacecraft, GroundStation

Spacecraft Configuration

Propagator Types

Ephemerista supports multiple propagation methods:

  1. SGP4: For TLE-based propagation

  2. Numerical: High-precision numerical integration

  3. Semi-Analytical: Analytical mean element propagation

  4. OEM: Orbit Ephemeris Message input

See also

For detailed propagator documentation, see Orbit Propagators – ephemerista.propagators.

GUI: Spacecraft Setup

  1. Name: Enter a unique identifier for the spacecraft

  2. Propagator Type: Select from dropdown menu

  3. Configure propagator-specific parameters

[SCREENSHOT PLACEHOLDER: Spacecraft configuration form with propagator selection]

Python: Spacecraft Creation

Using SGP4 with TLE
from ephemerista.propagators.sgp4 import Sgp4Propagator

# Create spacecraft from TLE
tle_line1 = "1 25544U 98067A   21001.00000000  .00000000  00000-0  00000+0 0    06"
tle_line2 = "2 25544  51.6400 000.0000 0000000   0.0000 000.0000 15.50000000000000"

spacecraft_tle = Spacecraft(
    name="ISS",
    propagator=Sgp4Propagator.from_tle(tle_line1, tle_line2)
)

scenario.add_asset(spacecraft_tle)
Using Keplerian Elements
from ephemerista.coords.twobody import KeplerianElements
from ephemerista.propagators.sgp4 import Sgp4Propagator

# Define orbital elements
elements = KeplerianElements(
    semi_major_axis=7000.0,    # km
    eccentricity=0.001,
    inclination=98.0,          # degrees
    raan=0.0,                  # Right Ascension of Ascending Node
    argument_of_periapsis=0.0,
    true_anomaly=0.0
)

# Create spacecraft with SGP4 propagator
spacecraft = Spacecraft(
    name="Earth Observer 1",
    propagator=Sgp4Propagator.from_keplerian_elements(
        elements, 
        epoch=scenario.start_time
    )
)

scenario.add_asset(spacecraft)
High-Precision Numerical Propagation
from ephemerista.propagators.orekit.numerical import NumericalPropagator
from ephemerista.coords.trajectories import CartesianState

# Define initial state
initial_state = CartesianState(
    position=[7000.0, 0.0, 0.0],     # km
    velocity=[0.0, 7.5, 0.0],        # km/s
    epoch=scenario.start_time,
    frame=ReferenceFrame.ICRF
)

# Configure numerical propagator with force models
numerical_prop = NumericalPropagator(
    initial_state=initial_state,
    gravity_degree=20,        # Gravity field degree
    gravity_order=20,         # Gravity field order
    include_drag=True,        # Atmospheric drag
    include_srp=True,         # Solar radiation pressure
    include_third_body=True   # Moon/Sun perturbations
)

spacecraft_numerical = Spacecraft(
    name="High Precision Satellite",
    propagator=numerical_prop
)

Ground Station Configuration

Ground stations are fixed locations on Earth’s surface used for communication with spacecraft.

GUI: Ground Station Setup

  1. Name: Enter ground station identifier

  2. Location:

    • Longitude: East longitude in degrees

    • Latitude: North latitude in degrees

    • Altitude: Height above sea level (meters)

  3. Minimum Elevation: Minimum satellite elevation angle for visibility (degrees)

[SCREENSHOT PLACEHOLDER: Ground station configuration form with geographic coordinates]

Python: Ground Station Creation

# Create ground station
ground_station = GroundStation(
    name="Deep Space Network Station",
    longitude=243.11,          # degrees East
    latitude=35.42,           # degrees North
    altitude=1036.0,          # meters above sea level
    minimum_elevation=10.0    # degrees
)

scenario.add_asset(ground_station)

Asset Properties and Metadata

Assets can have custom properties for advanced analysis:

# Add custom properties to assets
spacecraft.properties = {
    "mass": 500.0,           # kg
    "cross_section": 2.5,    # m²
    "drag_coefficient": 2.2,
    "srp_coefficient": 1.8,
    "mission_type": "Earth Observation"
}

# Asset identification and grouping
spacecraft.tags = ["EO", "polar", "sun_synchronous"]
ground_station.tags = ["DSN", "primary", "X_band"]

Propagation Setup

Orbit Types and Quick Setup

GUI: Quick Orbit Setup

Ephemerista provides quick setup options for common orbital regimes:

Low Earth Orbit (LEO)

  • Altitude range: 200-2000 km

  • Quick setup with altitude and inclination

  • Automatic calculation of orbital period

[SCREENSHOT PLACEHOLDER: LEO quick setup form]

Medium Earth Orbit (MEO)

  • Altitude range: 2000-35786 km

  • Common for navigation satellites

  • Semi-synchronous options available

[SCREENSHOT PLACEHOLDER: MEO quick setup form]

Geostationary Earth Orbit (GEO)

  • Fixed altitude at 35,786 km

  • Zero inclination and eccentricity

  • Automatic longitude positioning

[SCREENSHOT PLACEHOLDER: GEO quick setup form]

Sun-Synchronous Orbit (SSO)

  • Maintains consistent solar illumination

  • Automatic inclination calculation based on altitude

  • Ideal for Earth observation missions

[SCREENSHOT PLACEHOLDER: SSO quick setup form]

Python: Orbit Type Configuration

# LEO Example
leo_elements = KeplerianElements(
    semi_major_axis=6878.0,    # 500 km altitude
    eccentricity=0.0,
    inclination=97.4,          # Sun-synchronous at this altitude
    raan=0.0,
    argument_of_periapsis=0.0,
    true_anomaly=0.0
)

# GEO Example
geo_elements = KeplerianElements(
    semi_major_axis=42164.0,   # GEO radius
    eccentricity=0.0,
    inclination=0.0,
    raan=0.0,
    argument_of_periapsis=0.0,
    true_anomaly=0.0
)

Propagator Selection Guide

SGP4 Propagator

Best for:

  • TLE-based analysis

  • Large constellation studies

  • Rapid computation requirements

Limitations:

  • Lower accuracy for long-term predictions

  • Not suitable for high-precision maneuver planning

Numerical Propagator

Best for:

  • High-precision mission analysis

  • Maneuver planning

  • Formation flying studies

Configuration:

numerical_prop = NumericalPropagator(
    initial_state=initial_state,
    gravity_degree=50,
    gravity_order=50,
    atmospheric_model="NRLMSISE00",
    solar_activity="STRONG",
    integrator="DormandPrince853",
    min_step=1e-3,
    max_step=300.0
)

Semi-Analytical Propagator

Best for:

  • Long-term evolution studies

  • Constellation maintenance analysis

  • Orbit lifetime predictions

from ephemerista.propagators.orekit.semianalytical import SemiAnalyticalPropagator

semi_analytical_prop = SemiAnalyticalPropagator(
    initial_state=initial_state,
    propagation_type="DSST",    # Draper Semi-analytical Satellite Theory
    mean_elements=True,
    short_period_corrections=True
)

OEM (Orbit Ephemeris Message) Support

For precise ephemeris data:

GUI: OEM Import

  1. Select OEM propagator type

  2. Upload or paste OEM file content

  3. Validate ephemeris data format

  4. Set interpolation parameters

[SCREENSHOT PLACEHOLDER: OEM file upload interface]

Python: OEM Usage

from ephemerista.propagators.oem import OemPropagator

# Load OEM file
oem_prop = OemPropagator.from_file("spacecraft_ephemeris.oem")

# Create spacecraft from OEM
spacecraft_oem = Spacecraft(
    name="Precision Ephemeris Satellite",
    propagator=oem_prop
)

Ensemble Propagation

For efficient analysis of multiple assets:

# Propagate entire scenario
ensemble = scenario.propagate()

# Access individual trajectories
for asset_id, trajectory in ensemble.trajectories.items():
    asset_name = ensemble.get_asset_name(asset_id)
    times = trajectory.times
    positions = trajectory.positions
    velocities = trajectory.velocities

Visibility Analysis

Understanding Visibility

Visibility analysis determines when spacecraft are visible from ground stations, accounting for elevation constraints and Earth obstruction.

See also

For complete visibility analysis API documentation, see Visibility – ephemerista.analysis.visibility.

GUI: Running Visibility Analysis

  1. Navigate to the “Analyses” tab

  2. Select “Visibility” from the analysis type dropdown

  3. Click “Run Analysis”

[SCREENSHOT PLACEHOLDER: Analysis panel with visibility option selected]

Visibility Results Display

The GUI displays visibility results in multiple formats:

  • Pass Summary Table: Shows all visibility windows

  • Pass Timeline: Visual representation of passes

  • Detailed Pass Information: Elevation, azimuth, and range data

[SCREENSHOT PLACEHOLDER: Visibility results table showing pass data]

Python: Visibility Analysis

from ephemerista.analysis.visibility import Visibility

# Create visibility analyzer
visibility_analyzer = Visibility(scenario)

# Compute visibility
visibility_results = visibility_analyzer.calculate()

# Access visibility windows
for observer_id, observer_results in visibility_results.items():
    for target_id, passes in observer_results.items():
        for pass_data in passes:
            print(f"Pass from {pass_data.start_time} to {pass_data.end_time}")
            print(f"Maximum elevation: {pass_data.max_elevation} degrees")

Advanced Visibility Options

Custom Elevation Masks

from ephemerista.analysis.visibility import ElevationMask

# Define complex elevation mask
elevation_mask = ElevationMask({
    0: 10.0,      # 10° minimum at azimuth 0°
    90: 15.0,     # 15° minimum at azimuth 90°
    180: 8.0,     # 8° minimum at azimuth 180°
    270: 12.0     # 12° minimum at azimuth 270°
})

# Apply mask to ground station
ground_station.elevation_mask = elevation_mask

Visibility Constraints

# Configure constraints
visibility_analyzer = Visibility(
    scenario,
    min_elevation=5.0,           # degrees
    max_range=2000.0,           # km
    eclipse_constraint=True,     # Exclude eclipsed satellites
    sun_elevation_limit=-6.0    # Twilight constraint
)

Visualization Options

GUI: 3D Visualization

  • Ground Track: Satellite orbital path projected onto Earth surface

  • Visibility Cones: Ground station coverage areas

  • Real-time Position: Current satellite locations

[SCREENSHOT PLACEHOLDER: 3D visualization showing satellite ground tracks and visibility cones]

Python: Plotting Visibility

from ephemerista.plot.visibility import plot_visibility_pass

# Plot individual pass details
pass_plot = plot_visibility_pass(
    pass_data=passes[0],
    show_elevation=True,
    show_azimuth=True,
    show_range=True
)

Communication Systems Configuration

Overview

Communication systems model the RF links between spacecraft and ground stations, including antennas, transmitters, receivers, and channels.

See also

For complete communication systems API documentation, see Comms – ephemerista.comms.

Antenna Configuration

GUI: Adding Antennas

  1. In the asset configuration, expand the “Communication Systems” section

  2. Click “Add Communication System”

  3. Configure antenna parameters

[SCREENSHOT PLACEHOLDER: Communication system configuration section]

Python: Antenna Types

Simple Antenna
from ephemerista.comms.antennas import SimpleAntenna

# Create simple antenna
antenna = SimpleAntenna(
    gain=20.0,              # Peak gain in dB
    beamwidth=10.0,        # Half-power beamwidth in degrees
    design_frequency=2.4e9,    # Hz
    boresight_vector=[0, 0, 1] # Antenna pointing direction
)
Complex Antenna Patterns
from ephemerista.comms.antennas import (
    GaussianPattern, 
    ParabolicPattern,
    DipolePattern
)

# Gaussian pattern antenna
gaussian_antenna = GaussianPattern(
    peak_gain=25.0,
    half_power_beamwidth=3.0,
    design_frequency=8.4e9
)

# Parabolic reflector
parabolic_antenna = ParabolicPattern(
    diameter=2.4,              # meters
    efficiency=0.65,
    design_frequency=8.4e9,
    feed_blockage_ratio=0.1
)

Transmitter and Receiver Configuration

GUI Configuration

  • Transmitter:

    • Power (watts)

    • Frequency (Hz)

    • Line losses (dB)

    • Output back-off (dB)

  • Receiver:

    • Frequency (Hz)

    • System noise temperature (Kelvin)

    • Implementation losses (dB)

[SCREENSHOT PLACEHOLDER: Transmitter and receiver configuration forms]

Python Configuration

from ephemerista.comms.transmitter import Transmitter
from ephemerista.comms.receiver import Receiver

transmitter = Transmitter(
    power=10.0,          # Transmit power in watts
    frequency=8.4e9,        # Operating frequency in Hz
    line_loss=1.5,          # System losses in dB
    output_backoff=3.0,     # Power amplifier backoff in dB
    modulation="QPSK",         # Modulation scheme
    symbol_rate=1e6            # Symbols per second
)

receiver = Receiver(
    frequency=8.4e9,
    system_noise_temperature=150.0,  # System noise temperature in Kelvin
    implementation_loss=1.0,         # Implementation losses in dB
    adc_bits=12,                        # ADC resolution
    bandwidth=2e6                    # Receiver bandwidth in Hz
)

Channel Configuration

Channels define the communication link characteristics:

GUI: Channel Setup

  1. Channel Name: Descriptive identifier

  2. Link Type:

    • Uplink: Ground-to-satellite

    • Downlink: Satellite-to-ground

    • Crosslink: Satellite-to-satellite

  3. Data Rate: Information rate in bits per second

  4. Required Eb/N0: Energy per bit to noise ratio (dB)

  5. Link Margin: Additional margin for link reliability (dB)

[SCREENSHOT PLACEHOLDER: Channel configuration form with all parameters]

Python: Channel Definition

from ephemerista.comms.channels import Channel

# Define communication channel
uplink_channel = Channel(
    name="S-band Uplink",
    link_type="uplink",
    frequency=2.1e9,
    data_rate=1e6,           # bits per second
    required_eb_n0=9.6,       # Required Eb/N0 in dB
    link_margin=3.0,          # Design margin in dB
    modulation="QPSK",
    forward_error_correction=0.5, # Coding rate
    roll_off_factor=0.35
)

Communication System Integration

from ephemerista.comms.systems import CommunicationSystem

# Create integrated communication system
comm_system = CommunicationSystem(
    name="Primary Communication System",
    antenna=gaussian_antenna,
    transmitter=transmitter,
    receiver=receiver,
    channels=[uplink_channel]
)

# Add to spacecraft
spacecraft.add_communication_system(comm_system)

Constellation Configuration

Constellation Design Patterns

Ephemerista supports several constellation architectures:

See also

For complete constellation design API documentation, see Constellations – ephemerista.constellation.

Walker Constellations

GUI: Walker Configuration

  1. Select “Add Constellation” in the scenario panel

  2. Choose constellation type:

    • Walker Star: Symmetric distribution

    • Walker Delta: Phased distribution

[SCREENSHOT PLACEHOLDER: Walker constellation configuration form]

Python: Walker Star

from ephemerista.constellation.design import WalkerStar

walker_star = WalkerStar(
    num_satellites=24,          # Total satellites
    num_planes=4,              # Number of orbital planes
    inclination=55.0,      # Orbital inclination in degrees
    altitude=20200,         # Orbital altitude in km
    phasing_parameter=1        # Inter-plane phasing
)

# Generate constellation
constellation_assets = walker_star.generate_assets(
    base_name="GPS",
    start_epoch=scenario.start_time
)

# Add to scenario
for asset in constellation_assets:
    scenario.add_asset(asset)

Python: Walker Delta

from ephemerista.constellation.design import WalkerDelta

walker_delta = WalkerDelta(
    num_satellites=27,
    num_planes=3,
    inclination=86.4,
    altitude=1414,
    pattern_factor=1           # Delta pattern phasing
)

constellation_assets = walker_delta.generate_assets(
    base_name="Iridium",
    start_epoch=scenario.start_time,
    include_spares=True        # Include spare satellites
)

Streets-of-Coverage

Streets-of-Coverage patterns provide continuous coverage along specific latitudes:

from ephemerista.constellation.design import StreetOfCoverage

street_pattern = StreetOfCoverage(
    latitude_coverage=(-70, 70),    # Coverage latitude bounds
    longitude_spacing=22.5,     # Longitude separation in degrees
    inclination=99.5,           # Sun-synchronous inclination
    altitude=700,                # LEO altitude in km
    local_time_ascending_node=10.5  # LTAN in hours
)

street_constellation = street_pattern.generate_assets(
    base_name="EarthObserver",
    start_epoch=scenario.start_time
)

Custom Constellation Design

from ephemerista.constellation.plane import OrbitalPlane

# Define custom orbital planes
plane_1 = OrbitalPlane(
    inclination=98.7,
    raan=0.0,
    satellites_per_plane=5,
    altitude=600,
    true_anomaly_offset=0.0
)

plane_2 = OrbitalPlane(
    inclination=98.7,
    raan=120.0,
    satellites_per_plane=5,
    altitude=600,
    true_anomaly_offset=72.0  # Phase offset
)

# Combine into custom constellation
custom_constellation = [plane_1, plane_2]

Constellation Visualization

GUI: 3D Constellation Display

The 3D viewer displays:

  • All constellation satellites simultaneously

  • Orbital planes and satellite distribution

  • Ground track patterns

  • Real-time constellation evolution

[SCREENSHOT PLACEHOLDER: 3D visualization of a Walker constellation showing multiple orbital planes]

Coverage Analysis

Overview

Coverage analysis determines how well a satellite constellation covers geographic areas of interest over time.

See also

For complete coverage analysis API documentation, see Coverage – ephemerista.analysis.coverage.

Defining Areas of Interest

GUI: Area Definition

  1. Click “Add Area of Interest” in the scenario configuration

  2. Define the geographic region:

    • GeoJSON Import: Upload polygon definitions

    • Manual Definition: Enter coordinate points

    • Shape Tools: Use built-in drawing tools

[SCREENSHOT PLACEHOLDER: Area of interest definition interface with map view]

Python: Area Definition

See also

For area shapes API documentation, see Orbit Shapes – ephemerista.coords.shapes.

from ephemerista.coords.shapes import CircularArea, RectangularArea

# Circular coverage area
circular_area = CircularArea(
    center_latitude=40.7128,   # New York City
    center_longitude=-74.0060,
    radius=500.0,
    name="NYC Metropolitan Area"
)

# Rectangular coverage area
rectangular_area = RectangularArea(
    southwest_corner=(25.0, -125.0),  # lat, lon
    northeast_corner=(49.0, -66.0),   # Continental US
    name="Continental United States"
)

scenario.add_area_of_interest(circular_area)
scenario.add_area_of_interest(rectangular_area)

Running Coverage Analysis

GUI: Coverage Configuration

  1. Select “Coverage” analysis type

  2. Specify parameters:

    • Temporal Resolution: Time step for coverage calculation

    • Minimum Elevation: Required satellite elevation

    • Minimum Contact Duration: Required visibility time

[SCREENSHOT PLACEHOLDER: Coverage analysis configuration panel]

Python: Coverage Calculation

from ephemerista.analysis.coverage import Coverage

# Create coverage analyzer
coverage_analyzer = Coverage(
    scenario,
    temporal_resolution=300,  # 5-minute intervals
    spatial_resolution=1.0,       # 1-degree grid
    min_elevation=10.0,
    include_eclipse_periods=False
)

# Compute coverage
coverage_results = coverage_analyzer.calculate()

# Access coverage statistics
for area_id, area_results in coverage_results.items():
    area_name = area_results.area_name
    coverage_percentage = area_results.coverage_percentage
    max_gap_hours = area_results.max_gap_duration / 3600
    mean_revisit_time_hours = area_results.mean_revisit_time / 3600
    
    print(f"Area: {area_name}")
    print(f"Coverage: {coverage_percentage:.1f}%")
    print(f"Max gap: {max_gap_hours:.1f} hours")
    print(f"Mean revisit: {mean_revisit_time_hours:.1f} hours")

Understanding Coverage Results

Coverage Metrics

  • Coverage Percentage: Fraction of area covered

  • Maximum Gap: Longest period without coverage

  • Revisit Time: Time between successive coverage events

  • Mean Access Duration: Average contact time

[SCREENSHOT PLACEHOLDER: Coverage metrics summary table]

Coverage Visualization

  • Spatial Coverage Maps: Geographic distribution of coverage

  • Temporal Coverage: Coverage availability over time

  • Gap Analysis: Identification of coverage holes

[SCREENSHOT PLACEHOLDER: Coverage map showing colored regions indicating coverage levels]

Visualization and Data Export

GUI: 3D Visualization

Visualization Controls

  • Orbit: Click and drag to rotate view

  • Pan: Right-click and drag to pan

  • Zoom: Mouse wheel or pinch to zoom

  • Reset View: Return to default perspective

[SCREENSHOT PLACEHOLDER: 3D viewer with visible camera control indicators]

Display Elements

  • Earth Model: High-resolution Earth texture

  • Satellite Models: 3D satellite representations

  • Orbital Paths: Historical and predicted trajectories

  • Ground Station Markers: Fixed Earth locations

  • Visibility Cones: Ground station coverage areas

  • Coverage Areas: Color-coded coverage regions

Time Controls

  • Play/Pause: Start/stop time animation

  • Time Slider: Manually control simulation time

  • Speed Control: Adjust animation speed

  • Time Display: Current simulation time

[SCREENSHOT PLACEHOLDER: Time control interface at bottom of 3D viewer]

Python: Plotting and Visualization

See also

For complete plotting API documentation, see Plotting Tools – ephemerista.plot.

from ephemerista.plot.ground_track import plot_ground_track
from ephemerista.plot.visibility import plot_visibility_pass

# Plot ground track with visibility
fig = plot_ground_track(
    scenario=scenario,
    asset_names=["Earth Observer 1"],
    show_ground_stations=True,
    show_visibility_circles=True
)

# Plot individual pass details
pass_plot = plot_visibility_pass(
    pass_data=passes[0],
    show_elevation=True,
    show_azimuth=True,
    show_range=True
)

Data Export

GUI: Export Options

  1. Click the “Export” button

  2. Choose export format:

    • JSON: Native Ephemerista format

    • CSV: Tabular data for spreadsheet analysis

    • CCSDS: Standard space data formats

[SCREENSHOT PLACEHOLDER: Export dialog with format options]

Python: Data Export

# Export scenario
scenario.save("mission_scenario.json")

# Export analysis results to CSV
visibility_results.to_csv("visibility_passes.csv")
coverage_results.to_csv("coverage_statistics.csv")

# Export to CCSDS format
from ephemerista.io.ccsds import export_oem
export_oem(ensemble, "satellite_ephemeris.oem")

Advanced Features

Custom Analysis Modules (Python)

Create custom analysis modules by extending the base class:

from ephemerista.analysis.base import AnalysisModule

class CustomInterferenceAnalysis(AnalysisModule):
    """Custom interference analysis implementation."""
    
    def __init__(self, interference_threshold=-120.0):
        super().__init__()
        self.interference_threshold = interference_threshold
    
    def calculate(self):
        """Perform custom interference analysis."""
        results = {}
        
        for asset in self.scenario.all_assets:
            if hasattr(asset, 'communication_systems'):
                # Analyze interference for each communication system
                interference_data = self._compute_interference(asset)
                results[asset.id] = interference_data
        
        return results
    
    def _compute_interference(self, asset):
        """Compute interference levels."""
        # Implementation details
        pass

# Use custom analysis
custom_analyzer = CustomInterferenceAnalysis(
    interference_threshold=-115.0
)
custom_results = custom_analyzer.calculate()

Parallel Processing

# Configure parallel processing
from ephemerista.parallel import ParallelProcessor
import multiprocessing

processor = ParallelProcessor(
    num_processes=multiprocessing.cpu_count(),
    chunk_size="auto",              # Automatic load balancing
    memory_limit_gb=8.0             # Memory usage limit
)

# Use parallel processing in analysis
visibility_analyzer = Visibility(scenario, parallel=True)

Integration with External Tools

CCSDS Standards Support

from ephemerista.io.ccsds import OemExporter, AemExporter

# Export to CCSDS OEM format
oem_exporter = OemExporter()
oem_file = oem_exporter.export_ensemble(
    ensemble, 
    output_file="satellite_ephemeris.oem"
)

# Export attitude data (AEM)
aem_exporter = AemExporter()
aem_file = aem_exporter.export_attitude(
    attitude_data,
    output_file="satellite_attitude.aem"
)

Examples and Tutorials

Complete Mission Analysis Example

#!/usr/bin/env python3
"""
Complete Earth Observation Mission Analysis Example

This example demonstrates a full mission analysis workflow including:
- Constellation design
- Coverage analysis  
- Communication link budgets
- Navigation performance assessment
"""

import ephemerista
from ephemerista import Scenario
from ephemerista.time import Epoch, TimeScale
from ephemerista.constellation.design import WalkerStar
from ephemerista.assets import GroundStation
from ephemerista.analysis.visibility import Visibility
from ephemerista.analysis.coverage import Coverage
from ephemerista.analysis.link_budget import LinkBudget
from ephemerista.analysis.navigation import Navigation
from datetime import datetime, timezone

# Initialize Ephemerista
ephemerista.init(
    eop_file="data/finals2000A.all.csv",
    ephemeris_file="data/de440s.bsp"
)

# Create scenario
scenario = Scenario(
    name="Earth Observation Mission",
    start_time=Epoch.from_datetime(
        datetime(2024, 6, 1, 0, 0, 0, tzinfo=timezone.utc),
        TimeScale.UTC
    ),
    end_time=Epoch.from_datetime(
        datetime(2024, 6, 8, 0, 0, 0, tzinfo=timezone.utc),
        TimeScale.UTC
    ),
    time_step=300.0  # 5-minute intervals
)

# Design constellation
constellation = WalkerStar(
    num_satellites=12,
    num_planes=3,
    inclination=98.7,  # Sun-synchronous
    altitude=700,
    phasing_parameter=1
)

# Generate constellation assets
satellites = constellation.generate_assets(
    base_name="EarthObs",
    start_epoch=scenario.start_time
)

# Add satellites to scenario
for satellite in satellites:
    scenario.add_asset(satellite)

# Add ground stations
ground_stations = [
    GroundStation(
        name="Alaska Station",
        latitude=64.8,
        longitude=-147.7,
        altitude=200.0,
        minimum_elevation=10.0
    ),
    GroundStation(
        name="Svalbard Station", 
        latitude=78.2,
        longitude=15.4,
        altitude=100.0,
        minimum_elevation=5.0
    )
]

for station in ground_stations:
    scenario.add_asset(station)

# Define coverage areas
from ephemerista.coords.shapes import RectangularArea

arctic_area = RectangularArea(
    southwest_corner=(66.5, -180.0),  # Arctic Circle
    northeast_corner=(90.0, 180.0),
    name="Arctic Region"
)

scenario.add_area_of_interest(arctic_area)

# Perform analyses
print("Running mission analysis...")

# 1. Visibility Analysis
print("Computing visibility...")
visibility_analyzer = Visibility(scenario)
visibility_results = visibility_analyzer.calculate()

# 2. Coverage Analysis  
print("Computing coverage...")
coverage_analyzer = Coverage(scenario)
coverage_results = coverage_analyzer.calculate()

# 3. Link Budget Analysis
print("Computing link budgets...")
link_budget_analyzer = LinkBudget(scenario)
link_budget_results = link_budget_analyzer.calculate()

# 4. Navigation Performance
print("Computing navigation performance...")
nav_analyzer = Navigation(scenario)
nav_results = nav_analyzer.calculate()

# Generate reports
print("\n=== MISSION ANALYSIS RESULTS ===\n")

# Visibility Summary
total_passes = sum(len(passes) for observer_results in visibility_results.values() 
                  for passes in observer_results.values())
print(f"Total visibility passes: {total_passes}")

# Coverage Summary
for area_id, area_results in coverage_results.items():
    print(f"Coverage for {area_results.area_name}: {area_results.coverage_percentage:.1f}%")
    print(f"Maximum gap: {area_results.max_gap_duration/3600:.1f} hours")

# Link Budget Summary
successful_links = sum(1 for link_data in link_budget_results.values() 
                      if link_data.link_margin > 0)
total_links = len(link_budget_results)
print(f"Successful communication links: {successful_links}/{total_links}")

# Navigation Summary
for observer_id, results in nav_results.items():
    mean_gdop = sum(results.gdop) / len(results.gdop)
    print(f"Mean GDOP for {results.observer_name}: {mean_gdop:.2f}")

print("\nMission analysis completed successfully!")

Troubleshooting and Reference

Common Issues

Propagation Errors

Invalid TLE Format

  • Ensure proper two-line element formatting

  • Check TLE epoch dates are appropriate for analysis period

Numerical Integration Issues

  • Verify initial state vectors are realistic

  • Check force model parameters

Visualization Problems

WebGL Support

  • Ensure browser supports WebGL

  • Update graphics drivers if needed

Performance Issues

  • Reduce number of displayed satellites

  • Lower temporal resolution for long analyses

Analysis Failures

Insufficient Data

  • Ensure all required parameters are specified

  • Check that assets have necessary properties

Memory Limitations

  • Reduce analysis duration or temporal resolution

  • Use parallel processing for large scenarios

Performance Optimization

Large Constellations

  • Use temporal sampling to reduce computation

  • Focus analysis on specific time windows

  • Consider constellation subsets for initial analysis

Complex Scenarios

  • Start with simplified configurations

  • Gradually add complexity

  • Use quick setup options when possible

Getting Help

Documentation

Support Resources

  • Issue Reporting: Bug reports and feature requests

  • Community Forums: User discussions and solutions

  • Technical Support: Direct assistance for complex issues

This unified user manual provides comprehensive guidance for using both the Ephemerista GUI and Python API. For the latest updates and additional resources, visit the project repository.