Module feasibility
feasibility_checker
- commonocean_dc.feasibility.feasibility_checker.position_orientation_objective(u: array, x0: array, x1: array, dt: float, vessel_dynamics: VesselDynamics, ftol: float = 1e-08, e: array = array([0.02, 0.02, 0.03])) float[source]
Position-Orientation objective function to be minimized for the state transition feasibility.
Simulates the next state using the inputs and calculates the norm of the difference between the simulated next state and actual next state. Position, velocity and orientation state fields will be used for calculation of the norm.
- Parameters:
u – input values
x0 – initial state values
x1 – next state values
dt – delta time
vessel_dynamics – the vessel dynamics model to be used for forward simulation
ftol – ftol parameter used by the optimizer
e – error margin, function will return norm of the error vector multiplied with 100 as cost if the input violates the friction circle constraint or input bounds.
- Returns:
cost
- commonocean_dc.feasibility.feasibility_checker.position_orientation_feasibility_criteria(x: array, x_sim: array, vessel_dynamics: VesselDynamics, e: array = array([0.02, 0.02, 0.03]), d: int = 4) bool[source]
Position-Orientation feasibility criteria to be checked between the real next state and the simulated next state in the state transition feasibility testing after a valid input has been found.
Checks whether the position and orientation difference is within acceptable between actual state and simulated state.
- Parameters:
x – real next state
x_sim – simulated next state
vessel_dynamics – the vessel dynamics model to be used for forward simulation
e – error margin, function will return False if the positional difference between the simulated next state and the actual next state is bigger then error margin.
d – decimal points where the difference values are rounded up to in order to avoid floating point errors set it based on the error margin, i.e e=0.02, d=3
- Returns:
True if the positional difference is below error margin.
- commonocean_dc.feasibility.feasibility_checker.state_transition_feasibility(x0: ~commonocean.scenario.state.GeneralState, x1: ~commonocean.scenario.state.GeneralState, vessel_dynamics: ~commonocean_dc.feasibility.vessel_dynamics.VesselDynamics, dt: float, objective=<function position_orientation_objective>, criteria=<function position_orientation_feasibility_criteria>, ftol: float = 1e-08, e: ~numpy.array = array([0.02, 0.02, 0.03]), d: int = 4, maxiter: int = 100, disp: bool = False) Tuple[bool, GeneralState][source]
Checks if the state transition is feasible between given two state according to the vessel dynamics.
Tries to find a valid input for the state transition by minimizing the objective function, and then checks if the state simulated by using the reconstructed input is feasible.
By default, the trajectory feasibility checker will use position-orientation objective function as the objective and position-orientation feasibility criteria function will be used for feasibility criteria.
Objectives can be changed by passing a function with the signature fun(u: np.array, x0: np.array, x1: np.array, dt: float, vessel_dynamics: VesselDynamics, ftol: float = 1e-8, e: np.array -> float
Feasibility criteria can be changed by passing a function with the signature fun(x: np.array, x_sim: np.array, vessel_dynamics: VesselDynamics, e: np.array = np.array([2e-2, 2e-2, 3e-2]), d: int = 4) -> bool
- Parameters:
x0 – initial state
x1 – next state
vessel_dynamics – the vessel dynamics model to be used for forward simulation
dt – delta time
objective – callable fun(u, x0, x1, dt, vessel_dynamics) -> float, objective function to be minimized in order to find a valid input for state transition
criteria – callable fun(x1, x_sim, vessel_dynamics) -> bool, feasibility criteria to be checked between the real next state and the simulated next state
ftol – ftol passed to the minimizer function
e – error margin passed to the feasibility criteria function
d – decimal points where the difference values are rounded up to in order to avoid floating point errors set it based on the error margin, i.e e=0.02, d=4
maxiter – maxiter passed to the minimizer function
disp – disp passed to the minimizer function
- Returns:
True if feasible, and the constructed input as GeneralState
- commonocean_dc.feasibility.feasibility_checker.trajectory_feasibility(trajectory: ~commonocean.scenario.trajectory.Trajectory, vessel_dynamics: ~commonocean_dc.feasibility.vessel_dynamics.VesselDynamics, dt: float, objective=<function position_orientation_objective>, criteria=<function position_orientation_feasibility_criteria>, ftol: float = 1e-08, e: ~numpy.array = array([0.02, 0.02, 0.03]), d: int = 4, maxiter: int = 100, disp: bool = False) Tuple[bool, Trajectory][source]
Checks if the given trajectory is feasible for the vessel model by checking if the state transition is feasible between each consecutive state of the trajectory.
The state_transition_feasibility function will be applied to consecutive states of a given trajectory, and the reconstructed inputs will be returned as Trajectory object. If the trajectory was not feasible, reconstructed inputs up to infeasible state will be returned.
ATTENTION: Reconstructed inputs are just approximated inputs for the forward simulation between consecutive states n and n+1. Simulating full trajectory from the initial state by using the reconstructed inputs can result in a different (but similar) trajectory compared to the real one. The reason for this is the small differences between the approximate inputs and the real inputs adding up as we simulate further from the initial state.
By default, the trajectory feasibility checker will use position-orientation objective function as the objective and position-orientation feasibility criteria function will be used for feasibility criteria.
Objectives can be changed by passing a function with the signature fun(u: np.array, x0: np.array, x1: np.array, dt: float, vessel_dynamics: VesselDynamics, ftol: float = 1e-8, e: np.array) -> float
Feasibility criteria can be changed by passing a function with the signature fun(x: np.array, x_sim: np.array, vessel_dynamics: VesselDynamics, e: np.array = np.array([2e-2, 2e-2, 3e-2]), d: int = 4) -> bool
- Parameters:
trajectory – trajectory
vessel_dynamics – the vessel dynamics model to be used for forward simulation
dt – delta time
objective – callable fun(u, x0, x1, dt, vessel_dynamics) -> float, objective function to be minimized in order to find a valid input for state transition
criteria – callable fun(x1, x_sim, vessel_dynamics) -> bool, feasibility criteria to be checked between the real next state and the simulated next state
ftol – ftol passed to the minimizer function
e – error margin passed to the feasibility criteria function
d – decimal points where the difference values are rounded up to in order to avoid floating point errors set it based on the error margin, i.e e=0.02, d=4
maxiter – maxiter passed to the minimizer function
disp – disp passed to the minimizer function
- Returns:
True if feasible, and list of constructed inputs as Trajectory object
- commonocean_dc.feasibility.feasibility_checker.input_vector_feasibility(initial_state: GeneralState, input_vector: Trajectory, vessel_dynamics: VesselDynamics, dt: float) Tuple[bool, Trajectory][source]
Checks whether the given input vector (as Trajectory object) is feasible according to the input and state constraints.
The input bounds and friction circle constraint of corresponding vessel model is being used as criteria of validity. During the process of feasibility checking, the trajectory will be simulated for the given initial state and input vector. If there is an infeasible input, all the trajectory states simulated up to that input will be returned instead.
For example, if we have initial state wth time step 0, and valid input vector that contains 20 inputs, the trajectory will be completely simulated and returned together with the feasibility result. If we have an input vector that is valid up to 5th input, then the trajectory will be simulated up to 5th time step, but 6th time step will not be simulated since the input is not feasible.
- Parameters:
initial_state – initial state which the input vector will be applied
input_vector – input vector s Trajectory object
vessel_dynamics – the vessel dynamics model to be used for input constraint checks
dt – delta time
- Returns:
True if feasible, and simulated trajectory.
solution_checker
vessel_dynamics
- class commonocean_dc.feasibility.vessel_dynamics.VesselParameterMapping(value)[source]
Mapping for VesselType name to VesselParameters
- classmethod from_vessel_type(vessel_type: VesselType) vesselmodels.vessel_parameters.VesselParameters[source]
- class commonocean_dc.feasibility.vessel_dynamics.VesselDynamics(vessel_model: VesselModel, vessel_type: VesselType)[source]
VesselDynamics abstract class that encapsulates the common methods of all VesselDynamics classes.
- List of currently implemented vessel models
Point Mass Model (PM)
Velocity-Constrained Point Mass (VP)
Yaw-Constrained Model (YP)
Three Degrees of Freedom Model (TF)
New types of VesselDynamics can be defined by extending this class. If there isn’t any mismatch with the state values, the new VesselDynamics class can be used directly with the feasibility checkers as well.
For detailed documentation of the Vessel Models, please check our Vessel Model Documentation
- classmethod PM(vessel_type: VesselType) PointMassDynamics[source]
Creates a PointMassDynamics model.
- Parameters:
vessel_type – VesselType, i.e. VesselType.Vessel1
- Returns:
PointMassDynamics instance with the given vessel type.
- classmethod VP(vessel_type: VesselType) VelocityConstrainedPointMass[source]
Creates a VelocityConstrainedPointMass model.
- Parameters:
vessel_type – VesselType, i.e. VesselType.Vessel1
- Returns:
VelocityConstrainedPointMass instance with the given vessel type.
- classmethod YP(vessel_type: VesselType) YawConstrained[source]
Creates a YawConstrained model.
- Parameters:
vessel_type – VesselType, i.e. VesselType.Vessel1
- Returns:
YawConstrained instance with the given vessel type.
- classmethod TF(vessel_type: VesselType) ThreeDegreesOfFreedom[source]
Creates a ThreeDegreesOfFreedom VesselDynamics model.
- Parameters:
vessel_type – VesselType, i.e. VesselType.Vessel1
- Returns:
ThreeDegreesOfFreedom instance with the given vessel type.
- classmethod from_model(vessel_model: VesselModel, vessel_type: VesselType) VesselDynamics[source]
Creates a VesselDynamics model for the given vessel model and type.
- Parameters:
vessel_model – VesselModel, i.e. VesselModel.YP
vessel_type – VesselType, i.e. VesselType.Vessel1
- Returns:
VesselDynamics instance with the given vessel type.
- abstract dynamics(t, x, u) List[float][source]
Vessel dynamics function that models the motion of the vessel during forward simulation.
- Parameters:
t – time point which the differentiation is being calculated at.
x – state values
u – input values
- Returns:
next state values
- property input_bounds: Bounds
Returns the bounds on inputs (constraints).
- Bounds are
min steering velocity <= steering_angle_speed <= max steering velocity
-max longitudinal acc <= acceleration <= max longitudinal acc
- Returns:
Bounds
- input_within_bounds(u: Union[GeneralState, array], throw: bool = False) bool[source]
Checks whether the given input is within input constraints of the vessel dynamics model.
- Parameters:
u – input values as np.array or State - Contains 2 values
throw – if set to false, will return bool instead of throwing exception (default=False)
- Returns:
True if within constraints
- forward_simulation(x: array, u: array, dt: float, throw: bool = True) Union[None, array][source]
Simulates the next state using the given state and input values as numpy arrays.
- Parameters:
x – state values.
u – input values
dt – scenario delta time.
throw – if set to false, will return None as next state instead of throwing exception (default=True)
- Returns:
simulated next state values, raises VesselDynamicsException if invalid input.
- simulate_next_state(x: GeneralState, u: GeneralState, dt: float, throw: bool = True) Union[None, GeneralState][source]
Simulates the next state using the given state and input values as State objects.
- Parameters:
x – current state
u – inputs for simulating the next state
dt – scenario delta time.
throw – if set to false, will return None as next state instead of throwing exception (default=True)
- Returns:
simulated next state, raises VesselDynamicsException if invalid input.
- simulate_trajectory(initial_state: GeneralState, input_vector: Trajectory, dt: float, throw: bool = True) Union[None, Trajectory][source]
Creates the trajectory for the given input vector.
- Parameters:
initial_state – initial state of the planning problem
input_vector – input vector as Trajectory object
dt – scenario delta time
throw – if set to false, will return None as trajectory instead of throwing exception (default=True)
- Returns:
simulated trajectory, raises VesselDynamicsException if there is an invalid input.
- state_to_array(state: GeneralState) Tuple[array, int][source]
Converts the given State to numpy array.
- Parameters:
state – GeneralState
- Returns:
state values as numpy array and time step of the state
- array_to_state(x: array, time_step: int) GeneralState[source]
Converts the given numpy array of values to State.
- Parameters:
x – list of state values
time_step – time step of the converted state
- Returns:
GeneralState
- convert_initial_state(initial_state) GeneralState[source]
Converts the given default initial state to VesselModel’s state by setting the state values accordingly.
- Parameters:
initial_state – default initial state
- Returns:
converted initial state
- class commonocean_dc.feasibility.vessel_dynamics.PointMassDynamics(vessel_type: VesselType)[source]
- class commonocean_dc.feasibility.vessel_dynamics.VelocityConstrainedPointMass(vessel_type: VesselType)[source]
- class commonocean_dc.feasibility.vessel_dynamics.YawConstrained(vessel_type: VesselType)[source]
- class commonocean_dc.feasibility.vessel_dynamics.ThreeDegreesOfFreedom(vessel_type: VesselType)[source]