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) -> 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 (time step, tolerance, subdivisions, etc.)	`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 with time tolerance and subdivisions
config = bh.AccessSearchConfig(initial_time_step=30.0, adaptive_step=True, time_tolerance=0.01)
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: bool = True, num_threads: [int] = None, time_tolerance: float = 0.001, subdivisions: [SubdivisionConfig] = None)

Configuration for access search grid parameters.

Controls the time step, adaptive stepping, boundary refinement tolerance, and optional subdivision 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`
`parallel`	`bool`	Enable parallel computation (default: True)	`True`
`num_threads`	`Optional[int]`	Number of threads for parallel computation (default: None)	`None`
`time_tolerance`	`float`	Boundary refinement tolerance in seconds (default: 0.001)	`0.001`
`subdivisions`	`Optional[SubdivisionConfig]`	Subdivision configuration per window (default: None)	`None`

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
)

# Subdivide each access window into 4 equal-time sub-windows
config = bh.AccessSearchConfig(
    subdivisions=bh.SubdivisionConfig.equal_count(4),
    time_tolerance=0.01
)
sub_windows = bh.location_accesses(
    station, prop, search_start, search_end,
    constraint, config=config
)

# Fixed-duration sub-windows
config = bh.AccessSearchConfig(
    subdivisions=bh.SubdivisionConfig.fixed_duration(30.0, gap=5.0)
)

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)

subdivisions `property` ¶

subdivisions: Optional[SubdivisionConfig]

Get the subdivision configuration per access window.

Returns:

Type	Description
`Optional[SubdivisionConfig]`	Optional[SubdivisionConfig]: Subdivision configuration, or None for no subdivision

time_tolerance `property` ¶

time_tolerance: float

Get the boundary refinement tolerance in seconds.

Returns:

Name	Type	Description
`float`	`float`	Time tolerance in seconds

SubdivisionConfig ¶

SubdivisionConfig(count: [int] = None, duration: [float] = None, offset: float = 0.0, gap: float = 0.0, truncate_partial: bool = False)

Configuration for how access windows are subdivided.

Supports two modes: equal-count (split into N equal parts) and fixed-duration (generate sub-windows with a specific duration at regular intervals).

Can be created using keyword constructor or named class methods:

Parameters:

Name	Type	Description	Default
`count`	`Optional[int]`	Number of equal subdivisions (EqualCount mode)	`None`
`duration`	`Optional[float]`	Duration of each sub-window in seconds (FixedDuration mode)	`None`
`offset`	`float`	Offset from parent window start in seconds (default: 0.0)	`0.0`
`gap`	`float`	Gap between sub-windows in seconds, negative for overlap (default: 0.0)	`0.0`
`truncate_partial`	`bool`	If True, truncate partial sub-windows; if False, drop them (default: False)	`False`

Example

import brahe as bh

# Equal-count mode via keyword constructor
config = bh.SubdivisionConfig(count=4)

# Equal-count mode via named constructor
config = bh.SubdivisionConfig.equal_count(4)

# Fixed-duration mode via keyword constructor
config = bh.SubdivisionConfig(duration=30.0, offset=10.0, gap=5.0)

# Fixed-duration mode via named constructor
config = bh.SubdivisionConfig.fixed_duration(
    duration=30.0, offset=10.0, gap=5.0, truncate_partial=False
)

Initialize instance.

count `property` ¶

count: Optional[int]

Get the count (for EqualCount mode).

Returns:

Type	Description
`Optional[int]`	Optional[int]: Number of subdivisions, or None if FixedDuration mode

duration `property` ¶

duration: Optional[float]

Get the duration (for FixedDuration mode).

Returns:

Type	Description
`Optional[float]`	Optional[float]: Sub-window duration in seconds, or None if EqualCount mode

gap `property` ¶

gap: Optional[float]

Get the gap (for FixedDuration mode).

Returns:

Type	Description
`Optional[float]`	Optional[float]: Gap between sub-windows in seconds, or None if EqualCount mode

offset `property` ¶

offset: Optional[float]

Get the offset (for FixedDuration mode).

Returns:

Type	Description
`Optional[float]`	Optional[float]: Offset from parent window start in seconds, or None if EqualCount mode

truncate_partial `property` ¶

truncate_partial: Optional[bool]

Get the truncate_partial flag (for FixedDuration mode).

Returns:

Type	Description
`Optional[bool]`	Optional[bool]: Truncate partial flag, or None if EqualCount mode

equal_count `staticmethod` ¶

equal_count(count: int) -> SubdivisionConfig

Create an equal-count subdivision configuration.

Splits each access window into N equal-duration sub-windows.

Parameters:

Name	Type	Description	Default
`count`	`int`	Number of equal subdivisions (must be >= 1)	required

Returns:

Name	Type	Description
`SubdivisionConfig`	`SubdivisionConfig`	Equal-count subdivision configuration

Example

import brahe as bh

config = bh.SubdivisionConfig.equal_count(4)

fixed_duration `staticmethod` ¶

fixed_duration(duration: float, offset: float = 0.0, gap: float = 0.0, truncate_partial: bool = False) -> SubdivisionConfig

Create a fixed-duration subdivision configuration.

Generates sub-windows with a specific duration at regular intervals within each parent access window.

Parameters:

Name	Type	Description	Default
`duration`	`float`	Duration of each sub-window in seconds (must be > 0.0)	required
`offset`	`float`	Offset from parent window start in seconds (default: 0.0)	`0.0`
`gap`	`float`	Gap between sub-windows in seconds, negative for overlap (default: 0.0)	`0.0`
`truncate_partial`	`bool`	If True, truncate partial sub-windows; if False, drop them (default: False)	`False`

Returns:

Name	Type	Description
`SubdivisionConfig`	`SubdivisionConfig`	Fixed-duration subdivision configuration

Example

import brahe as bh

config = bh.SubdivisionConfig.fixed_duration(
    duration=30.0, offset=10.0, gap=5.0, truncate_partial=False
)

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 ¶

subdivisions property ¶

time_tolerance property ¶

SubdivisionConfig ¶

count property ¶

duration property ¶

gap property ¶

offset property ¶

truncate_partial property ¶

equal_count staticmethod ¶

fixed_duration staticmethod ¶

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` ¶

subdivisions `property` ¶

time_tolerance `property` ¶

count `property` ¶

duration `property` ¶

gap `property` ¶

offset `property` ¶

truncate_partial `property` ¶

equal_count `staticmethod` ¶

fixed_duration `staticmethod` ¶

set_num_threads `builtin` ¶

set_max_threads `builtin` ¶

set_ludicrous_speed `builtin` ¶

get_max_threads `builtin` ¶