Module Common

File Reader

CommonOceanFileReader class

class commonocean.common.file_reader.CommonOceanFileReader(filename: str)

Class which reads CommonOcean XML-files. The XML-files are composed of (1) a formal representation of the water network, (2) static and dynamic obstacles, (3) the planning problem of the ego vehicle(s).

open() → Tuple[Scenario, PlanningProblemSet]

Reads a CommonOcean XML-file.

Returns:

the scenario containing the water network and the obstacles and the planning problem set containing the planning problems—initial states and goal regions–for all ego vessels.

open_waters_network() → WatersNetwork

Reads the water network of a CommonOcean XML-file. :return: object of class WatersNetwork

File Writer

CommonOceanFileWriter class

class commonocean.common.file_writer.CommonOceanFileWriter(scenario: Scenario, planning_problem_set: PlanningProblemSet, author: Optional[str] = None, affiliation: Optional[str] = None, source: Optional[str] = None, tags: Optional[Set[Tag]] = None, location: Optional[Location] = None, decimal_precision: int = 8)

static check_validity_of_commonocean_file(commonocean_str: str)

Check the validity of a generated xml_string in terms of commonocean with an existing XSD schema. Throw an error if it is not valid.

Args:

commonocean_str: XML formatted string which should be checked.

write_scenario_to_file(filename: Optional[str] = None, overwrite_existing_file: OverwriteExistingFile = OverwriteExistingFile.ASK_USER_INPUT)

Write a scenario without planning-problem. If file already exists, it will be overwritten of skipped.

Parameters:

• filename – filename of the xml output file. If ‘None’, the Benchmark ID is taken

• OverwriteExistingFile – Specify whether an already existing file should be overwritten or skipped

Returns:

None

write_to_file(filename: Optional[str] = None, overwrite_existing_file: OverwriteExistingFile = OverwriteExistingFile.ASK_USER_INPUT, check_validity: bool = False)

Write a scenario including planning-problem. If file already exists, it will be overwritten of skipped

Parameters:

• filename – filename of the xml output file. If ‘None’, the Benchmark ID is taken

• overwrite_existing_file – Specify whether an already existing file should be overwritten or skipped

• check_validity – check xml file against .xsd definition

Returns:

OverwriteExistingFile class

class commonocean.common.file_writer.OverwriteExistingFile(value)

Specifies whether an existing file will be overwritten or skipped

ASK_USER_INPUT = 0

ALWAYS = 1

SKIP = 2

Solution

SolutionException class

class commonocean.common.solution.SolutionException

Main exception class for solution related exceptions.

StateTypeException class

class commonocean.common.solution.StateTypeException

Main exception class for StateType related exceptions.

SolutionReaderException class

class commonocean.common.solution.SolutionReaderException

Main exception class for solution reader related exceptions.

VesselType class

class commonocean.common.solution.VesselType(value)

An enumeration.

VesselModel class

class commonocean.common.solution.VesselModel(value)

An enumeration.

CostFunction class

class commonocean.common.solution.CostFunction(value)

An enumeration.

StateFields class

class commonocean.common.solution.StateFields(value)

State Fields enum class for defining the state fields for vessel models for different trajectory types.

PM | VP | YP | TF -> Corresponding state fields for trajectory states __Name__Input -> Input fields for correspondent vessel models

Note: If you change the order of field names, don’t forget to change the order on the XMLStateFields enum as well, because the indexes have to match.

XMLStateFields class

class commonocean.common.solution.XMLStateFields(value)

XML names of the state fields for vessel models for different trajectory types.

PM | VP | YP | TF -> Corresponding xml names of the state fields for trajectory states __Name__Input -> XML names of the input fields for correspondent vessel models.

Note: If you change the order of xml names, don’t forget to change the order on the StateFields enum as well, because the indexes have to match.

StateType class

class commonocean.common.solution.StateType(value)

State Type enum class.

PM | VP | YP | TF -> Corresponding state type for trajectory states __Name__Input -> Input type correspondent vessel models

classmethod check_state_type(vessel_model: VesselModel) → None

Checks whether vessel model can be supported by trajectory. :param vessel_model: vessel model enum :return: bool

property fields: List[str]

Returns the state fields for the state type.

Returns:

State fields as list

classmethod get_state_type(state: GeneralState, desired_vessel_model: Optional[VesselModel] = None) → StateType

Returns the corresponding StateType for the given State object by matching State object’s attributes to the state fields.

Parameters:

• state – CommonOcean State object

• desired_vessel_model – check if given vessel_model is supported first

Returns:

corresponding StateType

property xml_fields: List[str]

Returns the xml state fields for the state type.

Returns:

XML names of the state fields as list

TrajectoryType class

class commonocean.common.solution.TrajectoryType(value)

Trajectory Type enum class.

PM | VP | YP | TF -> Corresponding trajectory type for the vessel models __Name__Input -> InputVector type for PM, VP, YP and TF vessel models

classmethod get_trajectory_type(trajectory: Trajectory, desired_vessel_model: Optional[VesselModel] = None) → TrajectoryType

Returns the corresponding TrajectoryType for the given Trajectory object based on the StateType of its states.

Parameters:

• trajectory – CommonOcean Trajectory object

• desired_vessel_model – check if given vessel_model is supported first

Returns:

corresponding TrajectoryType

property state_type: StateType

Returns the StateType corresponding to the TrajectoryType

Returns:

StateType

valid_vessel_model(vessel_model: VesselModel) → bool

Checks whether given vessel model is valid for the TrajectoryType.

Parameters:

vessel_model – CommonOcean enum for vessel models

Returns:

True if the vessel model is valid for the TrajectoryType

SupportedCostFunctions class

class commonocean.common.solution.SupportedCostFunctions(value)

Enum class for specifying which cost functions are supported for which vessel model

PlanningProblemSolution class

class commonocean.common.solution.PlanningProblemSolution(planning_problem_id: int, vessel_model: VesselModel, vessel_type: VesselType, cost_function: CostFunction, trajectory: Trajectory)

property cost_function: CostFunction

CostFunction of the PlanningProblemSolution

property cost_id: str

Returns cost function id as str.

Example:

CostFunction = JB1 Cost ID = JB1

Returns:

Cost function ID

property trajectory: Trajectory

Trajectory of the PlanningProblemSolution

property trajectory_type: TrajectoryType

TrajectoryType of the PlanningProblemSolution. Dynamically assigned when there is a change of trajectory.

property vessel_id: str

Returns the Vessel id as string.

Example:

VesselModel = VP VesselType = Vessel1 Vessel ID = VP1

Returns:

vessel model ID

property vessel_model: VesselModel

VesselModel of the PlanningProblemSolution

Solution class

class commonocean.common.solution.Solution(scenario_id: ScenarioID, planning_problem_solutions: List[PlanningProblemSolution], date: datetime = datetime.datetime(2023, 10, 20, 9, 28, 29, 409152), computation_time: Optional[float] = None, processor_name: Optional[str] = None)

Stores a solution to a CommonOcean benchmark and additional meta data.

property benchmark_id: str

Returns the benchmark id of the solution as string.

Example:

Scenario ID = TEYP VesselModel = VP VesselType = Vessel1 CostFunction = JB1 Version = 2022a

Benchmark ID = VP1:JB1:TEYP:2022a

Collaborative Solution Example:

Scenario ID = TEYP 1st VesselModel = VP 1st VesselType = Vessel1 1st CostFunction = JB1 2nd VesselModel = PM 2nd VesselType = Vessel3 2nd CostFunction = RC1 Version = 2020a

Benchmark ID = [VP1,PM3]:[JB1,RC1]:TEYP:2020a

Returns:

Benchmark ID

property computation_time: Union[None, float]

Return the computation time [s] for the trajectory.

Returns:

property cost_ids: List[str]

Returns the list of cost ids of all PlanningProblemSolutions of the Solution

Example:

1st PlanningProblemSolution Cost ID = JB1 2nd PlanningProblemSolution Cost ID = RC1

Cost IDS = [JB1, RC1]

Returns:

List of cost function IDs

create_dynamic_obstacle() → Dict[int, DynamicObstacle]

Creates dynamic obstacle(s) from solution(s) for every planning problem. :return:

property planning_problem_ids: List[int]

Returns the list of planning problem ids of all PlanningProblemSolutions of the Solution

Example:

1st PlanningProblemSolution planning_problem_id = 0 2nd PlanningProblemSolution planning_problem_id = 1

planning_problem_ids = [0, 1]

Returns:

List of planning problem ids

property trajectory_types: List[TrajectoryType]

Returns the list of trajectory types of all PlanningProblemSolutions of the Solution

Example:

1st PlanningProblemSolution trajectory_type = TrajectoryType.VP 2nd PlanningProblemSolution trajectory_type = TrajectoryType.TF

trajectory_types = [TrajectoryType.VP, TrajectoryType.TF]

Returns:

List of trajectory types

property vessels_ids: List[str]

Returns the list of vessel ids of all PlanningProblemSolutions of the Solution

Example:

1st PlanningProblemSolution Vessel ID = VP1 2nd PlanningProblemSolution Vessel ID = VP3

Vessel IDS = [VP1, VP3]

Returns:

List of vessel IDs

CommonOceanSolutionReader class

class commonocean.common.solution.CommonOceanSolutionReader

Reads solution xml files created with the CommonOceanSolutionWriter

classmethod fromstring(file: str) → Solution

Parses the given Solution XML string.

Parameters:

file – xml file as string

Returns:

Solution

classmethod open(filepath: str) → Solution

Opens and parses the Solution XML file located on the given path.

Parameters:

filepath – Path to the file.

Returns:

Solution

CommonOceanSolutionWriter class

class commonocean.common.solution.CommonOceanSolutionWriter(solution: Solution)

dump(pretty: bool = True) → str

Dumps the Solution XML as string.

Parameters:

pretty – If set to true, prettifies the xml string.

Returns:

string - Solution XML as string.

write_to_file(output_path: str = './', filename: Optional[str] = None, overwrite: bool = False, pretty: bool = True)

Writes the Solution XML to a file.

Parameters:

• output_path – Output dir where the Solution XML file should be written to. Writes to the same folder where it is called from if not specified.

• filename – Name of the Solution XML file. If not specified, sets the name as ‘solution_BENCHMARKID.xml’ where the BENCHMARKID is the benchmark_id of the solution.

• overwrite – If set to True, overwrites the file if it already exists.

• pretty – If set to True, prettifies the Solution XML string before writing to file.