Access Computation API¶

The access computation module provides comprehensive tools for determining when satellites can observe or communicate with ground locations.

Core Functions¶

location_accesses `builtin` ¶

location_accesses(locations: PointLocation | PolygonLocation | List[PointLocation | PolygonLocation], propagators: SGPPropagator | KeplerianPropagator | List[SGPPropagator | KeplerianPropagator], search_start: Epoch, search_end: Epoch, constraint: Union[ElevationConstraint, OffNadirConstraint, LocalTimeConstraint, LookDirectionConstraint, AscDscConstraint, ElevationMaskConstraint, ConstraintAll, ConstraintAny, ConstraintNot], property_computers: [List[AccessPropertyComputer]] = None, config: [AccessSearchConfig] = None, time_tolerance: [float] = None) -> List[AccessWindow]

Compute access windows for locations and satellites.

This function accepts either single items or lists for both locations and propagators, automatically handling all combinations. All location-satellite pairs are computed and results are returned sorted by window start time.

Parameters:

Name	Type	Description	Default
`locations`	`PointLocation \| PolygonLocation \| List[PointLocation \| PolygonLocation]`	Single location or list of locations	required
`propagators`	`SGPPropagator \| KeplerianPropagator \| List[SGPPropagator \| KeplerianPropagator]`	Single propagator or list of propagators	required
`search_start`	`Epoch`	Start of search window	required
`search_end`	`Epoch`	End of search window	required
`constraint`	`AccessConstraint`	Access constraints to evaluate	required
`property_computers`	`Optional[List[AccessPropertyComputer]]`	Optional property computers	`None`
`config`	`Optional[AccessSearchConfig]`	Search configuration (default: 60s fixed grid, no adaptation)	`None`
`time_tolerance`	`Optional[float]`	Bisection search tolerance in seconds (default: 0.01)	`None`

Returns:

Type	Description
`List[AccessWindow]`	List[AccessWindow]: List of access windows sorted by start time

Example

import brahe as bh
import numpy as np

# Create a ground station
station = bh.PointLocation(-75.0, 40.0, 0.0)  # Philadelphia

# Create satellite propagators
epoch = bh.Epoch(2024, 1, 1, 0, 0, 0.0)
oe = np.array([bh.R_EARTH + 500e3, 0.01, 97.8, 15.0, 30.0, 45.0])
state = bh.state_koe_to_eci(oe, bh.AngleFormat.DEGREES)
prop1 = bh.KeplerianPropagator(epoch, state)

# Define access constraints
constraint = bh.ElevationConstraint(10.0)  # 10 degree minimum elevation

# Single location, single propagator
search_end = epoch + 86400.0  # 1 day
windows = bh.location_accesses(station, prop1, epoch, search_end, constraint)

# Single location, multiple propagators
prop2 = bh.KeplerianPropagator(epoch, state)  # Different satellite
windows = bh.location_accesses(station, [prop1, prop2], epoch, search_end, constraint)

# Multiple locations, single propagator
station2 = bh.PointLocation(-122.0, 37.0, 0.0)  # San Francisco
windows = bh.location_accesses([station, station2], prop1, epoch, search_end, constraint)

# Multiple locations, multiple propagators
windows = bh.location_accesses([station, station2], [prop1, prop2], epoch, search_end, constraint)

# Custom search configuration
config = bh.AccessSearchConfig(initial_time_step=30.0, adaptive_step=True)
windows = bh.location_accesses(station, prop1, epoch, search_end, constraint, config=config)

Configuration¶

AccessSearchConfig ¶

AccessSearchConfig(initial_time_step: float = 60.0, adaptive_step: bool = False, adaptive_fraction: float = 0.75, parallel: Any = True, num_threads: Any = None)

Configuration for access search grid parameters.

Controls the time step and adaptive stepping behavior for access window finding.

Parameters:

Name	Type	Description	Default
`initial_time_step`	`float`	Initial time step in seconds for grid search (default: 60.0)	`60.0`
`adaptive_step`	`bool`	Enable adaptive stepping after first access (default: False)	`False`
`adaptive_fraction`	`float`	Fraction of orbital period to use for adaptive step (default: 0.75)	`0.75`

Example

import brahe as bh

# Create a config with custom parameters
config = bh.AccessSearchConfig(
    initial_time_step=30.0,
    adaptive_step=True,
    adaptive_fraction=0.5
)

# Use config with location_accesses
windows = bh.location_accesses(
    station, prop, search_start, search_end,
    constraint, config=config
)

Initialize instance.

adaptive_fraction `property` ¶

adaptive_fraction: float

Get the adaptive fraction (fraction of orbital period).

Returns:

Name	Type	Description
`float`	`float`	Adaptive fraction

adaptive_step `property` ¶

adaptive_step: bool

Get whether adaptive stepping is enabled.

Returns:

Name	Type	Description
`bool`	`bool`	Adaptive stepping flag

initial_time_step `property` ¶

initial_time_step: float

Get the initial time step in seconds.

Returns:

Name	Type	Description
`float`	`float`	Initial time step

num_threads `property` ¶

num_threads: Optional[int]

Get the number of threads for parallel computation.

Returns:

Type	Description
`Optional[int]`	Optional[int]: Number of threads, or None to use global setting

parallel `property` ¶

parallel: bool

Get whether parallel computation is enabled.

Returns:

Name	Type	Description
`bool`	`bool`	Parallel computation flag (default: True)

Threading Control¶

set_num_threads `builtin` ¶

set_num_threads(n: int) -> Any

Set the number of threads for parallel computation.

Configures the global thread pool used by Brahe for parallel operations such as access computations. This function can be called multiple times to dynamically change the thread pool configuration - each call will reinitialize the pool with the new thread count.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of threads to use. Must be at least 1.	required

Raises:

Type	Description
`ValueError`	If n < 1.
`RuntimeError`	If thread pool fails to build.

Example

import brahe as bh

# Set to 4 threads initially
bh.set_num_threads(4)
print(f"Threads: {bh.get_max_threads()}")  # Output: 4

# Reinitialize with 8 threads - no error!
bh.set_num_threads(8)
print(f"Threads: {bh.get_max_threads()}")  # Output: 8

# All parallel operations (e.g., location_accesses) will now use
# 8 threads unless overridden with AccessSearchConfig.num_threads

Note

Unlike earlier versions, this function no longer raises an error if the thread pool has already been initialized. You can safely call it at any time to reconfigure the thread pool.

set_max_threads `builtin` ¶

set_max_threads() -> Any

Set the thread pool to use all available CPU cores.

This is a convenience function that sets the number of threads to 100% of available CPU cores. Can be called multiple times to reinitialize the thread pool dynamically.

Raises:

Type	Description
`RuntimeError`	If thread pool fails to build.

Example

import brahe as bh

# Use all available CPU cores
bh.set_max_threads()
print(f"Using all {bh.get_max_threads()} cores")

# Switch to 2 threads
bh.set_num_threads(2)

# Switch back to max - no error!
bh.set_max_threads()
print(f"Back to {bh.get_max_threads()} cores")

Note

This function can be called at any time, even after the thread pool has been initialized with a different configuration.

set_ludicrous_speed `builtin` ¶

set_ludicrous_speed() -> Any

LUDICROUS SPEED! GO!

Set the thread pool to use all available CPU cores (alias for set_max_threads).

This is a fun alias for set_max_threads() that sets the number of threads to 100% of available CPU cores for maximum performance. Can be called multiple times to dynamically reinitialize the thread pool.

Raises:

Type	Description
`RuntimeError`	If thread pool fails to build.

Example

import brahe as bh

# MAXIMUM POWER! Use all available CPU cores
bh.set_ludicrous_speed()
print(f"Going ludicrous with {bh.get_max_threads()} threads!")

# Throttle down for testing
bh.set_num_threads(1)

# ENGAGE LUDICROUS SPEED again - no error!
bh.set_ludicrous_speed()

Note

This function can be called at any time to reconfigure the thread pool to use maximum available cores, regardless of previous configuration.

get_max_threads `builtin` ¶

get_max_threads() -> int

Get the current maximum number of threads for parallel computation.

Returns the number of threads configured for the global thread pool. If the thread pool hasn't been initialized yet, this initializes it with the default (90% of available cores) and returns that value.

Returns:

Name	Type	Description
`int`	`int`	Number of threads currently configured.

Example

import brahe as bh

# Get default thread count (90% of cores, initialized on first call)
threads = bh.get_max_threads()
print(f"Default: {threads} threads")

# Set to specific value and verify
bh.set_num_threads(4)
assert bh.get_max_threads() == 4

# Reconfigure and verify again
bh.set_num_threads(8)
assert bh.get_max_threads() == 8

# Switch to max cores
bh.set_max_threads()
print(f"Max cores: {bh.get_max_threads()}")

Note

Calling this function will initialize the thread pool with default settings (90% of cores) if it hasn't been configured yet. After initialization, you can still reconfigure it using set_num_threads() or set_max_threads().

Access Computation API¶

Core Functions¶

location_accesses builtin ¶

Configuration¶

AccessSearchConfig ¶

adaptive_fraction property ¶

adaptive_step property ¶

initial_time_step property ¶

num_threads property ¶

parallel property ¶

Threading Control¶

set_num_threads builtin ¶

set_max_threads builtin ¶

set_ludicrous_speed builtin ¶

get_max_threads builtin ¶

location_accesses `builtin` ¶

adaptive_fraction `property` ¶

adaptive_step `property` ¶

initial_time_step `property` ¶

num_threads `property` ¶

parallel `property` ¶

set_num_threads `builtin` ¶

set_max_threads `builtin` ¶

set_ludicrous_speed `builtin` ¶

get_max_threads `builtin` ¶