Event based targeting

[ChristopherRabotin]

Converted from https://gitlab.com/nyx-space/nyx/-/issues/226 with ChatGPT

High level description

Nyx currently supports basic spacecraft targeting, but does not have the ability to target specific events, such as periapses or eclipses. This issue aims to add support for event-based targeting to Nyx, allowing users to specify a target event and search for opportunities to achieve that target within a specified time frame.

Requirements

1. Allow targeting such that specific events are met, e.g. "achieve a periapse radius of X km."
2. Allow targeting using both events and objectives that are not event based

Test plans

1. Test the ability to design missions backwards using event-based targeting by defining a mission objective and verifying that Nyx can find the necessary events to achieve that objective.
2. Test the ability to optimize the timing of maneuvers using event-based targeting by defining a set of events that require a maneuver and verifying that Nyx can find the optimal time to execute the maneuver.

Edge cases to consider when developing test code for event-based targeting in Nyx include:

• Events that occur close to the edge of the specified time frame.
• Events with complex or nested criteria.
• Events that require multiple maneuvers to achieve.

Design

The design for event-based spacecraft targeting in Nyx will involve updating the Objective structure to accept an array of event-based objectives. The Optimizer structure will then use this array to design missions and optimize maneuvers using event-based targeting.

API definition

To support event-based spacecraft targeting in Nyx, the following changes will be made to the Nyx APIs:

• The Objective structure will be updated to accept an Either<Event, StateParameter> value in the target field. This field will define the event-based objective that the Optimizer will use to design missions and optimize maneuvers. If no event is specified, the Objective will target the specified state parameter at all times within the specified duration.
• The Objective structure will also be updated to accept a Duration value in the duration field. This field will define the duration within which the Optimizer will search for events that meet the specified criteria.
• The Optimizer structure will be updated to use the target and duration fields in the Objective to design missions and optimize maneuvers using event-based targeting.

use std::either::Either; // Human: ChatGPT choked here, `Either` is _not_ in std.

/// Defines a state parameter event finder
#[derive(Clone, Debug)]
pub struct Objective {
    /// The event or state parameter to target
    pub target: Either<Event, StateParameter>,
    /// The desired self.desired_value, must be in the same units as the state parameter
    pub desired_value: f64,
    /// The precision on the desired value
    pub tolerance: f64,
    /// A multiplicative factor this parameter's error in the targeting (defaults to 1.0)
    pub multiplicative_factor: f64,
    /// An additive factor to this parameters's error in the targeting (defaults to 0.0)
    pub additive_factor: f64,
    /// The duration within which the event must be achieved
    pub duration: Duration,
}

High level architecture

The high level architecture for event-based spacecraft targeting in Nyx will involve using the updated Objective and Optimizer structures to design missions and optimize maneuvers using event-based targeting.

In the high level architecture, the Optimizer uses the updated Objective structure to design missions and optimize maneuvers using event-based targeting. The Objective structure contains an Either<Event, StateParameter> value in the target field, which defines the event-based objective that the Optimizer will use. The Objective structure also contains a Duration value in the duration field, which defines the duration within which the Optimizer will search for events that meet the specified criteria. The Optimizer uses the Event structure to define the criteria for the event-based objective.

Detailed design

Here are some edge cases to consider when implementing event-based spacecraft targeting in Nyx:

• The Optimizer may not be able to find any events that meet the specified criteria within the specified duration. In this case, the Optimizer should return an error or a warning to indicate that no events were found.
• The Optimizer may find multiple events that meet the specified criteria within the specified duration. In this case, the Optimizer should allow the user to select which event to target, or it should automatically select the event with the highest probability of success or the least fuel consumption.
• The Optimizer may not be able to design a mission or optimize a maneuver to achieve the selected event within the specified duration. In this case, the Optimizer should return an error or a warning to indicate that the mission or maneuver cannot be achieved within the specified duration.
• The user may specify an event with criteria that are impossible to achieve, such as a periapse at a specific altitude in a circular orbit. In this case, the Optimizer should return an error or a warning to indicate that the specified event is impossible to achieve.
• The user may specify a state parameter that is not relevant to the selected event, such as a state parameter for a different spacecraft. In this case, the Optimizer should return an error or a warning to indicate that the specified state parameter is not relevant to the selected event.

[ChristopherRabotin]

Related to #280