Skip to content

Event Detectors

Core event detector classes for detecting specific conditions during numerical propagation.

TimeEvent 

TimeEvent(target_epoch: Epoch, name: str)

Time-based event detector.

Triggers when simulation time reaches a target epoch. Useful for scheduled maneuvers or discrete events at known times.

Parameters:

Name Type Description Default
target_epoch Epoch

Target time for event detection

 required
name str

Event name for identification

 required
Example 
1
2
3
4
5
import brahe as bh

target = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)
event = bh.TimeEvent(target, "Maneuver Start")
event = event.set_terminal()

Initialize instance.

set_terminal method descriptor 

set_terminal() -> TimeEvent

Mark this event as terminal (stops propagation).

Returns:

Name Type Description
TimeEvent TimeEvent

Self for method chaining
Example 
1
2
3
4
5
import brahe as bh

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
event = bh.TimeEvent(epoch, "End Condition").set_terminal()
# Propagation will stop when this event is detected

with_callback method descriptor 

with_callback(callback: callable) -> TimeEvent

Set event callback.

The callback is called when the event is detected and can modify the state and override the terminal action.

Parameters:

Name Type Description Default
callback callable

Function (epoch, state) -> (Optional[state], EventAction)

 required

Returns:

Name Type Description
TimeEvent TimeEvent

Self for method chaining
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import brahe as bh
import numpy as np

def apply_delta_v(epoch, state):
    '''Apply 10 m/s delta-v in x direction'''
    new_state = state.copy()
    new_state[3] += 10.0  # vx += 10 m/s
    return (new_state, bh.EventAction.CONTINUE)

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
event = bh.TimeEvent(epoch + 1800, "Maneuver").with_callback(apply_delta_v)

with_instance method descriptor 

with_instance(instance: int) -> TimeEvent

Set instance number for display name.

Appends instance number to the base name (e.g., "Maneuver" → "Maneuver 1").

Parameters:

Name Type Description Default
instance int

Instance number to append

 required

Returns:

Name Type Description
TimeEvent TimeEvent

Self for method chaining
Example 
1
2
3
4
5
import brahe as bh

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)
event = bh.TimeEvent(epoch, "Burn").with_instance(2)
# Event name is now "Burn 2"

with_time_tolerance method descriptor 

with_time_tolerance(time_tol: float) -> TimeEvent

Set custom time tolerance for event detection.

Controls the precision of the bisection search algorithm. Smaller values result in more precise event time detection at the cost of more iterations.

Parameters:

Name Type Description Default
time_tol float

Time tolerance in seconds (default: 1e-6)

 required

Returns:

Name Type Description
TimeEvent TimeEvent

Self for method chaining
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import brahe as bh

epoch = bh.Epoch.from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh.TimeSystem.UTC)

# Use tighter tolerance for precise timing
event = bh.TimeEvent(epoch, "Precise Maneuver").with_time_tolerance(1e-9)

# Chain multiple builder methods
event = (bh.TimeEvent(epoch, "Complex")
         .with_time_tolerance(1e-3)
         .with_instance(1)
         .set_terminal())

ValueEvent 

ValueEvent(name: str, value_fn: callable, target_value: float, direction: EventDirection)

Value event detector with custom value function.

Monitors a custom value computed by a Python function and detects when it crosses a specified target value. The value function receives the current epoch and state, and returns a float value to monitor.

Parameters:

Name Type Description Default
name str

Event name for identification

 required
value_fn callable

Function (epoch, state) -> float that computes monitored value

 required
target_value float

Target value for crossing detection

 required
direction EventDirection

Detection direction (INCREASING, DECREASING, or ANY)

 required
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import brahe as bh
import numpy as np

def radial_distance(epoch, state):
    return np.linalg.norm(state[:3])

event = bh.ValueEvent(
    "Altitude Check",
    radial_distance,
    bh.R_EARTH + 500e3,
    bh.EventDirection.DECREASING
)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> ValueEvent

Mark this event as terminal (stops propagation).

Returns:

Name Type Description
ValueEvent ValueEvent

Self for method chaining

with_callback method descriptor 

with_callback(callback: callable) -> ValueEvent

Set event callback.

Parameters:

Name Type Description Default
callback callable

Function (epoch, state) -> (Optional[state], EventAction)

 required

Returns:

Name Type Description
ValueEvent ValueEvent

Self for method chaining

with_instance method descriptor 

with_instance(instance: int) -> ValueEvent

Set instance number for display name.

Parameters:

Name Type Description Default
instance int

Instance number to append

 required

Returns:

Name Type Description
ValueEvent ValueEvent

Self for method chaining

with_tolerances method descriptor 

with_tolerances(time_tol: float, value_tol: float) -> ValueEvent

Set custom tolerances for event detection.

Parameters:

Name Type Description Default
time_tol float

Time tolerance in seconds (default: 1e-6)

 required
value_tol float

Value tolerance (default: 1e-9)

 required

Returns:

Name Type Description
ValueEvent ValueEvent

Self for method chaining
Example 
1
2
3
4
5
6
7
import brahe as bh

def value_fn(epoch, state):
    return state[0]  # Monitor x position

event = (bh.ValueEvent("X Crossing", value_fn, 0.0, bh.EventDirection.ANY)
         .with_tolerances(1e-3, 1e-6))  # Looser tolerances

BinaryEvent 

BinaryEvent(name: str, condition_fn: callable, edge: EdgeType)

Binary event detector with custom condition function.

Detects boolean condition transitions (edges). The condition function receives the current epoch and state, and returns a boolean. The event fires when the condition transitions according to the specified edge type.

Parameters:

Name Type Description Default
name str

Event name for identification

 required
condition_fn callable

Function (epoch, state) -> bool that returns the condition

 required
edge EdgeType

Which edge to detect (RISING_EDGE, FALLING_EDGE, or ANY_EDGE)

 required
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import brahe as bh

def is_sunlit(epoch, state):
    pos = state[:3]
    return pos[0] > 0

event = bh.BinaryEvent(
    "Eclipse Entry",
    is_sunlit,
    bh.EdgeType.FALLING_EDGE
)

Initialize instance.

set_terminal method descriptor 

set_terminal() -> BinaryEvent

Mark this event as terminal (stops propagation).

Returns:

Name Type Description
BinaryEvent BinaryEvent

Self for method chaining

with_callback method descriptor 

with_callback(callback: callable) -> BinaryEvent

Set event callback.

Parameters:

Name Type Description Default
callback callable

Function (epoch, state) -> (Optional[state], EventAction)

 required

Returns:

Name Type Description
BinaryEvent BinaryEvent

Self for method chaining

with_instance method descriptor 

with_instance(instance: int) -> BinaryEvent

Set instance number for display name.

Parameters:

Name Type Description Default
instance int

Instance number to append

 required

Returns:

Name Type Description
BinaryEvent BinaryEvent

Self for method chaining

with_tolerances method descriptor 

with_tolerances(time_tol: float, value_tol: float) -> BinaryEvent

Set custom tolerances for event detection.

Parameters:

Name Type Description Default
time_tol float

Time tolerance in seconds (default: 1e-6)

 required
value_tol float

Value tolerance (default: 1e-9)

 required

Returns:

Name Type Description
BinaryEvent BinaryEvent

Self for method chaining

See Also