API Documentation

Core

exception qalx_orcaflex.core.QalxOrcaFlexError(*args, **kwargs)
exception qalx_orcaflex.core.QalxSmartStaticsError(*args, **kwargs)

Error related to the smart statics utility.

exception qalx_orcaflex.core.QalxSmartStaticsFailed(*args, **kwargs)

We tried to do smart statics and it didn’t work.

class qalx_orcaflex.core.BaseSource(*args, **kwargs)

base class for batch sources.

Any child class must implement a to_jobs method which takes a base_job and temp_folder argument and returns a generator of jobs

the temp_folder will be automatically deleted by the batch manager after the batch has been submitted.

class qalx_orcaflex.core.NewSource(*args, **kwargs)

base class for batch sources with new data files. These also need to support restarts.

Any child class must implement a to_jobs method which takes a base_job and temp_folder argument and returns a generator of jobs

The use_orcfxapi keyword argument can be set false to avoid using an OrcaFlex licence when inspecting the job.

the temp_folder will be automatically deleted by the batch manager after the batch has been submitted.

class qalx_orcaflex.core.DataFileItemsSource(items: Sequence[Item])

an iterable of existing data file items.

This is useful when re-running a batch with some updated info or settings.

Parameters:

items –

class qalx_orcaflex.core.ModelSource(model: Model, name: str)

an OrcFxAPI.Model instance as the source, requires a model name

Parameters:

  • model – an OrcFxAPI.Model instance that you want to add to the batch

  • name – the name of the model, used as the file name to save back later.

class qalx_orcaflex.core.FileSource(path: PathLike, use_orcfxapi: bool = True)

a file source

Parameters:

  • path –

  • use_orcfxapi – if True then will use an OrcaFlex licence to check the data_file_type and get information about restart parents.

class qalx_orcaflex.core.DirectorySource(directory: PathLike | Sequence[PathLike], skip_fails: bool = False, recursive: bool = False, use_orcfxapi: bool = True)

takes a directory of files and adds them all.

Parameters:

  • directory – path to search for data files

  • skip_fails – don’t error if there is a failed path e.g. it is deleted while searching (default=False)

  • recursive – search all subdirectories (default=False)

  • use_orcfxapi – will make sure only OrcaFlex yaml files are added - THIS USES AN ORCAFLEX LICENCE (default=True)

class qalx_orcaflex.core.OrcaFlexBatchManager(temp_folder)

manager class for collecting batch info

instance is returned by :ref:OrcaFlexBatch as context manager

This collects all the sources for the jobs added to the batch.

add(source: BaseSource | NewSource, job_options: OrcaFlexJobOptions = OrcaFlexJobOptions(time_to_wait=0, record_progress=True, killable=False, save_simulation=True, licence_attempts=3600, max_search_attempts=10, max_wait=60, update_interval=5, delete_message_on_load=False), required_results: PathLike | Sequence[RangeGraph | TimeHistory] = (), model_views: Sequence[ModelView] = (), model_videos: Sequence[VideoSpecification] | None = None, load_case_info: LoadCaseInfo = LoadCaseInfo(raw_info=[], model_info=[]))

add data files to a batch based on a source and extra options.

Parameters:

  • source – a child of :ref:BaseSource or :ref:NewSource that implements to_jobs

  • job_options – various options and settings see :ref:data_models.OrcaFlexJobOptions

  • required_results – an iterator containing :ref:data_models.TimeHistory or :ref:data_models.RangeGraph (a mix of both is allowed) or a path to a yaml file with the correct Results structure.

  • model_views – an iterator containing :ref:data_models.ModelView

  • model_videos – An list of VideoSpecification instances

  • load_case_info – information about the load case to be used during presentation of results see :ref:data_models.LoadCaseInfo

Returns:

None

class qalx_orcaflex.core.OrcaFlexBatch(name, session: QalxSession, batch_options: BatchOptions, dry_run: bool = False, meta: Mapping | None = None, verbose: bool = False)

a batch of OrcaFlex data files

Parameters:

  • name – name of the batch

  • session – a QalxSession

  • batch_options – see :ref:data_models.BatchOptions

  • dry_run – if True will not build or submit the batch but will print name of each case

  • meta – additional metadata to add to the group entity

  • verbose – print statements of progress as build is in progress

classmethod get_and_check_progress(batch_name, ofx_session=None)

Given a name of a batch, run the GUI tool for batch progress

check_progress()

Run the check progress GUI in a separate thread

when_complete(interval=15, timeout=None, run_with_gui=True)

Returns a waiter for the batch that is instantiated with the same arguments

Parameters:

  • interval – The interval to use for the waiter

  • timeout – The timeout of the waiter in sec

  • run_with_gui – Flag to run or not the GUI for batch overview apart from the waiter

class qalx_orcaflex.core.Waiter(batch, batch_overview, interval=15, timeout=None, run_with_gui=True)

Implements “freezing” functionality that stops code execution until a batch is complete

Instance attributes
batch: The batch to wait on. The batch should have been added

before the waiter is run

batch_overview: Instance of BatchOverview interval: The interval in seconds to use between checking for

updates on the batch. Defaults to 15 seconds

timeout: The timeout in seconds to use in order to override the

waiting and just exit. This parameter is optional.

run_with_gui: Boolean flag to run or not the batch overview GUI

in addition. Defaults to True

class qalx_orcaflex.core.QalxOrcaFlex(*args, **kwargs)

we define a sublcass of QalxSession so there is no need to import from pyqalx

Warning

There are a load of terrible instance methods defined here just because we needed some way of doing these things. They need to be superseded by a better API

Parameters:

  • profile_name (str) – profile name to get from config_class (default=Config.default)

  • config_class (Config) – The class for the config that will be used for this session

  • skip_ini (bool) – Should loading the config from the inifile be skipped?

  • rest_api_class (PyQalxAPI) – The class to use for the rest api

  • project_name (str) – An optional name of a project. This will be used to tag all data that is created/modified with this session

Models

Models

This is set of dataclass classes that help define elements of the system.

These data_models are used to be able to easily construct data structures that are required for the OrcaFlex simulation processing system to work.

Some of these data_models can be used at the definition stage where you are required to set some options or settings, provide source data or pre-specify some thing that you need to have processed once the simulation is finished.

Other data_models are used by the system to populate data structures during or post processing of the simulation.

qalx_orcaflex.data_models.rehydrate_dataclass(klass, d)

https://stackoverflow.com/a/54769644/11984516 Rehydrates a dictionary into the given dataclass. Handles rehydrating nested dataclasses. :param klass: The dataclasses class that will be rehydrated :param d: The dict to use for the source data

class qalx_orcaflex.data_models.OrcaFlexJobOptions(time_to_wait: int = 0, record_progress: bool = True, killable: bool = False, save_simulation: bool = True, licence_attempts: int = 3600, max_search_attempts: int = 10, max_wait: int = 60, update_interval: int = 5, delete_message_on_load: bool = False)

Options for an OrcaFlex job

Parameters:

  • [int] (update_interval) – jobs will pause for this number of second before starting (default = 0)

  • [bool] (delete_message_on_load) – send updates on simulation progress (default = True)

  • [bool] – can a kill signal be sent to the job? (default = False)

  • [bool] – save the simulation in qalx (default = True)

  • [int] – number of time to try getting a licence before failing (default = 3600)

  • [int] – number or attempts at static search (default = 10)

  • [int] – the longest to wait before trying to (default = 60)

  • [int] – the number of seconds to wait between updating on model progress (default=5)

  • [bool] – will delete the queue message when the simulation bot loads (default=False)

class qalx_orcaflex.data_models.JobState(value)

An enumeration.

class qalx_orcaflex.data_models.OrcaFlexJobState(state: str = 'New', info: str | None = None, error: str | None = None)

the current state of an OrcaFlex job

Parameters:

  • [str] (error) – Current state of the job (default=”New”)

  • [str] – info about the state (default=None)

  • [str] – error text is the state is rror (default=None)

class qalx_orcaflex.data_models.BatchOptions(batch_queue: str, sim_queue: str, wait_between_completion_checks: int = 30, summarise_results: bool = True, build_threads: int = 10, send_sim_to: ~typing.Sequence = <factory>, send_batch_to: ~typing.Sequence = <factory>, notifications: ~qalx_orcaflex.data_models.notifications.Notifications | None = None, timeout: int | None = None)

options for a batch

Parameters:

  • batch_queue[str] – name of the batch queue

  • sim_queue[str] – name of the simulation queue

  • wait_between_completion_checks[int] – how long to wait before checking for completion (default=30)

  • summarise_results[bool] – should we create a results summary automatically (default=True)

  • build_threads[int] – threads to use to build the batch(default=10)

  • [list] (send_batch_to) – queues to send sims to when SimBot is finished

  • [list] – queues to send batches to when BatchBot is finished

  • [~data_models.notifications.Notifications] (notifications) – An instance of Notifications which will detail

which notifications should be automatically sent out by the system. (default=None) :param timeout: How long should this batch be processed for before timing out in seconds

exception qalx_orcaflex.data_models.ValidationError

That ain’t valid yo’

class qalx_orcaflex.data_models.Period(from_time: float | None = None, to_time: float | None = None, stage_number: int | None = None, named_period: str | None = None)

representation of Period for OrcaFlex results

Set the attributes to tell OrcFxAPI what period to extract the results for:

from_time & to_time -> OrcFxAPI.SpecifiedPeriod(self.from_time, self.to_time) named_period = “Whole Simulation” -> OrcFxAPI.Period(OrcFxAPI.pnWholeSimulation) named_period = “Latest Wave” -> OrcFxAPI.Period(OrcFxAPI.pnLatestWave) named_period = “Static State” -> OrcFxAPI.Period(OrcFxAPI.pnStaticState) stage_number -> OrcFxAPI.Period(self.stage_number)

if nothing is set then -> OrcFxAPI.Period(OrcFxAPI.pnWholeSimulation)

to_orcfxapi()

return an OrcFxAPI.Period or similar

class qalx_orcaflex.data_models.Support(supported_line_name: str | None = None, support_index: int = 0)

ObjectExtra specification for a Support

class qalx_orcaflex.data_models.Turbine(blade_arc_length: float | None = None, blade_index: int = 0)

ObjectExtra specification for a Turbine

class qalx_orcaflex.data_models.ResultMeta(name: str | None = None, stat: str | None = None, limit: dict = <factory>, var_details: dict = <factory>)

some metadata for results

Parameters:

  • [str] (stat) – Use if you want a custom name for the result (default=None)

  • [str] – needs to be “min” or “max” for which is the limiting condition (default=None)

  • [dict] (limit) – limit of result (default={})

  • var_details[dict] – details of the result variable from OrcFxAPI (default={})

class qalx_orcaflex.data_models.ArcLengthRange(from_arc: float | None = None, to_arc: float | None = None, from_section: int | None = None, to_section: int | None = None)

representation of ArcLengthRange for OrcaFlex results

from_arc & to_arc -> OrcFxAPI.arSpecifiedArclengths(self.from_arc, self.to_arc) from_section & to_section -> OrcFxAPI.arSpecifiedSections(self.from_section, self.to_section) if nothing is set -> OrcFxAPI.arEntireLine()

to_orcfxapi()

return an OrcFxAPI arc length range type object

class qalx_orcaflex.data_models.ObjectExtra(line_node: int = 0, line_arc: float = 0.0, line_named_point: str | None = None, line_radial_position: str = 'Inner', line_clearance_line_name: str | None = None, line_theta: float = 0.0, external_result_text: str | None = None, wing_name: str | None = None, winch_connection: float = 0.0, support: ~qalx_orcaflex.data_models.Support = Support(supported_line_name=None, support_index=0), turbine: ~qalx_orcaflex.data_models.Turbine = Turbine(blade_arc_length=None, blade_index=0), position: ~typing.List[float] = <factory>)

representation of ObejctExtra for an OrcaFlex result

converts to orcfxapi based on the type of object that the result is called for

For a Line:

line_named_point=’End A’ -> OrcFxAPI.ptEndA line_named_point=’End B’ -> OrcFxAPI.ptEndB line_named_point=’Touchdown’ -> OrcFxAPI.ptTouchdown line_named_point=’NodeNum’ -> OrcFxAPI.ptNodeNum line_named_point=’ArcLength’ -> OrcFxAPI.ptArcLength line_named_point= None -> OrcFxAPI.ptArcLength

defaults:

line_named_point = None line_radial_position = “Inner” line_clearance_line_name = None line_theta = 0.0 external_result_text = None

For other object types:

object_type = Environment -> OrcFxAPI.oeEnvironment(self.position) object_type = Vessel -> OrcFxAPI.oeVessel(self.position) object_type = NdBouy -> OrcFxAPI.oeBuoy(self.position) object_type = WingType -> OrcFxAPI.oeWing(self.wing_name) object_type = Winch -> OrcFxAPI.oeWinch(self.winch_connection)

For Supports and Turbines, use the Support and Turbine data_models provided
object_type = SupportType -> OrcFxAPI.oeSupport(self.support.support_index,

self.support.supported_line_name)

object_type = Turbine -> OrcFxAPI.oeTurbine(self.turbine.blade_index,

self.turbine.blade_arc_length)

to_orcfxapi(object_type)

based on the object_type return an ObjectExtra parameter

class qalx_orcaflex.data_models.ExtractedRangeGraph(arc: List[float] | None = None, y_min: List[float] | None = None, y_mean: List[float] | None = None, y_max: List[float] | None = None, y_limits: List[float] | None = None, y_static: List[float] | None = None)

An extracted range graph

class qalx_orcaflex.data_models.RangeGraph(object: str, variable: str, period: Period = Period(from_time=None, to_time=None, stage_number=None, named_period='Whole Simulation'), arc_length_range: ArcLengthRange = ArcLengthRange(from_arc=None, to_arc=None, from_section=None, to_section=None), extracted: ExtractedRangeGraph = ExtractedRangeGraph(arc=None, y_min=None, y_mean=None, y_max=None, y_limits=None, y_static=None), object_extra: ObjectExtra = ObjectExtra(line_node=0, line_arc=0.0, line_named_point=None, line_radial_position='Inner', line_clearance_line_name=None, line_theta=0.0, external_result_text=None, wing_name=None, winch_connection=0.0, support=Support(supported_line_name=None, support_index=0), turbine=Turbine(blade_arc_length=None, blade_index=0), position=[0.0, 0.0, 0.0]), storm_duration_hours: float = 3.0, meta: ResultMeta = ResultMeta(name=None, stat=None, limit={}, var_details={}), as_file: bool = False, _type: str = 'rg')

representation of a Range Graph OrcaFlex result

To be specified before the simulation:
param object [str]:

the name of the OrcaFlex object

param variable [str]:

the name of the result variable

param period [Period]:

period to extra the result (default=Period(named_period=”Whole Simulation”))

param arc_length_range [ArcLengthRange]:

arc length range to extract (default=ArcLengthRange())

param object_extra [ObjectExtra]:

(default=ObjectExtra())

param storm_duration_hours [float]:

(default=3.0)

param meta [ResultMeta]:

(default=ResultMeta())

param as_file [bool]:

(default=False)

Available after the simulation has been post-processed:
param extracted [ExtractedRangeGraph]:

the extracted (default=ExtractedRangeGraph())

classmethod from_dict(a_dict)

builds a RangeGraph from a dict

class qalx_orcaflex.data_models.ExtractedTimeHistory(time: List[float] | None = None, y_values: List[float] | None = None, y_limits: List[float] | None = None, static_value: float | None = None)

an extracted Time History

class qalx_orcaflex.data_models.TimeHistory(object: str, variable: str, period: Period, extracted: ExtractedTimeHistory = ExtractedTimeHistory(time=None, y_values=None, y_limits=None, static_value=None), object_extra: ObjectExtra = ObjectExtra(line_node=0, line_arc=0.0, line_named_point=None, line_radial_position='Inner', line_clearance_line_name=None, line_theta=0.0, external_result_text=None, wing_name=None, winch_connection=0.0, support=Support(supported_line_name=None, support_index=0), turbine=Turbine(blade_arc_length=None, blade_index=0), position=[0.0, 0.0, 0.0]), meta: ResultMeta = ResultMeta(name=None, stat=None, limit={}, var_details={}), as_file: bool = False, _type: str = 'th')

representation of a Range Graph OrcaFlex result

To be specified before the simulation:
param object [str]:

param variable [str]:

param period [Period]:

param object_extra [ObjectExtra]:

(default=ObjectExtra())

param meta [ResultMeta]:

(default=ResultMeta())

param as_file [bool]:

(default=False)

Available after the simulation has been post-processed:
param extracted:

ExtractedTimeHistory = ExtractedTimeHistory()

classmethod from_dict(a_dict)

builds a TimeHistory from a dict

class qalx_orcaflex.data_models.ModelInfo(object_name: str | None = None, data_name: str | None = None, item_index: int = 0, alias: str | None = None, value: Any | None = None)

information to extract from a model to aid with results presentation

To be specified before the simulation:
param object_name [str]:

name of the object

param data_name [str]:

data item name

param item_index [int]:

data item index (default=0)

param alias [str]:

an alternate name for this variable

Available after the simulation has been post-processed:
param value [Any]:

the value of the specified info

class qalx_orcaflex.data_models.RawInfo(key: str | None = None, value: Any | None = None)

raw information about the model not tied to any object data.

E.g. a client reference or internal document reference

Parameters:

  • key – info key

  • value – info value

class qalx_orcaflex.data_models.LoadCaseInfo(raw_info: ~typing.List[~qalx_orcaflex.data_models.RawInfo] = <factory>, model_info: ~typing.List[~qalx_orcaflex.data_models.ModelInfo] = <factory>)

all additional information about a laod case

Parameters:

  • raw_info – list of :ref:RawInfo

  • model_info – list of ref:ModelInfo

class qalx_orcaflex.data_models.RangeGraphSummary(result_meta: dict | None = None, max_value: float | None = None, arc_max_value: float | None = None, max_case_info: Mapping | None = None, max_result_guid: str | None = None, min_value: float | None = None, arc_min_value: float | None = None, min_case_info: Mapping | None = None, min_result_guid: str | None = None, static_max_value: float | None = None, arc_static_max_value: float | None = None, static_max_result_guid: str | None = None, static_max_case_info: Mapping | None = None, static_min_value: float | None = None, arc_static_min_value: float | None = None, static_min_case_info: Mapping | None = None, static_min_result_guid: str | None = None, vs_info: Mapping | None = None)

summary of range graph results across a batch

Parameters:

  • [dict] (result_meta) – some metadata about the result. SOme of this can be pre-specified and some is extracted post-sim

  • [float] (arc_static_min_value) – the maximum value of this result across all sims

  • [float] – the arc of the max value

  • [Mapping] (vs_info) – the load case info for the maximum case

  • [str] (static_min_result_guid) – the guid of the qalx item for the max result

  • [float] – the minimum value of this result across all sims

  • [float] – the arc of the min value

  • [Mapping] – the load case info for the minimum case

  • [str] – the guid of the qalx item for the min result

  • [float] – the static maximum value of this result across all sims

  • [float] – the arc of the static max value

  • [Mapping] – the load case info for the static maximum case

  • [str] – the guid of the qalx item for the static max result

  • [float] – the static minimum value of this result across all sims

  • [float] – the arc of the static min value

  • [Mapping] – the load case info for the static minimum case

  • [str] – the guid of the qalx item for the static min result

  • [Mapping] – mappings to be able to plot results against loadcase info

class qalx_orcaflex.data_models.TimeHistorySummary(result_meta: dict | None = None, max_value: float | None = None, time_max_value: float | None = None, max_case_info: Mapping | None = None, max_result_guid: str | None = None, min_value: float | None = None, time_min_value: float | None = None, min_case_info: Mapping | None = None, min_result_guid: str | None = None, vs_info: Mapping | None = None)

summary of time history results across a batch

Parameters:

  • [dict] (result_meta) – some metadata about the result. SOme of this can be pre-specified and some is extracted post-sim

  • [float] (time_min_value) – the maximum value of this result across all sims

  • [float] – the time of the maximum value

  • [Mapping] (vs_info) – the load case info for the maximum case

  • max_result_guid – [str] the guid of the qalx item for the max result

  • [float] – the minimum value of this result across all sims

  • [float] – the time of the minimum value

  • [Mapping] – the load case info for the minimum case

  • min_result_guid – [str] the guid of the qalx item for the min result

  • [Mapping] – mappings to be able to plot results against loadcase info

class qalx_orcaflex.data_models.ModelView(ViewName: str, ViewSize: float | None = None, Size: None = None, ViewAzimuth: float | None = None, ViewElevation: float | None = None, ViewCentre: List[float] | None = None, Height: int | None = None, Width: int | None = None, DrawViewAxes: bool | None = None, DrawScaleBar: bool | None = None, DrawGlobalAxes: bool | None = None, DrawEnvironmentAxes: bool | None = None, DrawLocalAxes: bool | None = None, DrawOutOfBalanceForces: bool | None = None, DrawNodeAxes: bool | None = None, GraphicsMode: str = 'WireFrame', FileFormat: str = 'PNG', BackgroundColour: Tuple[int, int, int] = (0, 0, 0), ViewGamma: float | None = None, RelativeToObjectHandle: str | None = None, DisturbanceVesselHandle: str | None = None, DisturbancePosition: List[float] | None = None, ShadedFillMode: str = 'Mesh', DrawNameLabels: bool | None = None, DrawConnections: bool | None = None, LabelScale: int | None = None, DrawOrigins: bool | None = None, MonochromeOutput: bool | None = None, AddDetailsToOutput: bool | None = None, JpegCompressionQuality: int | None = None)

a representation of OrcFxAPI.ViewParameters

Despite the use of PascalCase for attributes triggering slight dev OCD this has been done for good reason. The only attribute that we’ve added is ViewName so that you can easily identify it later e.g. “Plan”, “from Starboard”, “Fish view”, etc.

The other attributes here are passed directly to OrcFxAPI.ViewParameters. Read more about that here if you need to:

https://www.orcina.com/webhelp/OrcFxAPI/Content/html/Pythonreference,ViewParameters.htm

This class has some helper methods that should allow you to copy and paste from the “edit view parameters” window in the OrcaFlex GUI.

Basic process for simply defining model view then can be this:

1. Get the view you want in the OrcaFlex GUI 2. Open edit view parameters if it’s not open already (CTRL+W) 3. CTRL+A to select all cells 4. Give a name for the view and paste as a string using one of the following methods depending on what type of view you want:

wire_frame_from_form_str: for wireframe views shaded_solid_from_form_str: for solid shaded views shaded_mesh_from_form_str: for shaded mesh views

Defaults:

GraphicsMode: “WireFrame” FileFormat: “PNG” BackgroundColour: (0, 0, 0) ShadedFillMode: “Mesh”

classmethod wire_frame_from_form_str(view_name, form_str)
make a ModelView from a view name and the string from copying the “edit view

parameters” form in OrcaFlex GUI

Returns:

ModelView

classmethod shaded_solid_from_form_str(view_name, form_str)
make a ModelView from a view name and the string from copying the “edit view

parameters” form in OrcaFlex GUI

Returns:

ModelView

classmethod shaded_mesh_from_form_str(view_name, form_str)

make a ModelView from a view name and the string from copying the “edit view parameters” form in OrcaFlex GUI

Returns:

ModelView

to_orcfxapi(model)

build an OrcFxAPI.ViewParameters from this ModelView instance

class qalx_orcaflex.data_models.VideoSpecification(start_time: float, end_time: float, width: float = 400, height: float = 400, codec: str | None = None, model_views: List[ModelView] | None = None)

Video parameters for extracting a video from an orcaflex model

Parameters:

  • [float] (height) – The start time in the model to start recording

  • [float] – The end time in the model to stop the recording

  • [float] – The width of the video in pixels

  • [float] – The height of the video in pixels

  • [str] (codec) – The codec of the video. Accepted values: “MRLE”, “XVID”

  • [List] (model_views) – list of ref:ModelView

class qalx_orcaflex.data_models.JobProgress(progress: str, start_time: float | None = None, end_time: float | None = None, current_time: float | None = None, time_to_go: float | None = None, percent: float | None = None, pretty_time: str | None = None)

progress of the job

Parameters:

  • [str] (pretty_time) – a summary of the current progress

  • [float] (percent) – time the job started

  • [float] – time the job ended

  • [float] – current time in the job

  • [float] – how long estimated to completion in seconds

  • [float] – progress as a percentage

  • [str] – a nice string of time to go e.g. “3 hours, 4 mins”

class qalx_orcaflex.data_models.OrcaFlexJob(kill_signal: Item | None = None, job_options: OrcaFlexJobOptions = OrcaFlexJobOptions(time_to_wait=0, record_progress=True, killable=False, save_simulation=True, licence_attempts=3600, max_search_attempts=10, max_wait=60, update_interval=5, delete_message_on_load=False), data_file: Item | None = None, data_file_path: Item | None = None, sim_file: Item | None = None, sim_file_path: Item | None = None, results: Item | None = None, additional_files: Item | None = None, model_views: List[ModelView] | None = None, saved_views: List[Item] | None = None, model_videos: List[VideoSpecification] | None = None, saved_videos: List[Item] | None = None, progress: Item | None = None, warnings: Item | None = None, load_case_info: Item | None = None)

contains references to the items that make up a job

Parameters:

  • [Item] (load_case_info) – item with details about any kill_signal being sent to the job

  • [OrcaFlexJobOptions] (job_options) – job options

  • [Item] – information about the source of the binary data for simulation

  • [Item] – path of data file (if not using a data file item)

  • [Item] – details of results required for the simulation

  • [Item] – NOT IMPLEMENTED

  • [List[ModelView]] (model_views) – images to be saved of the completed simulation

  • [List] (saved_videos) – saved image files

  • [List] – NOT S

  • [List] – NOT IMPLEMENTED

  • [Item] – job progress information

  • [Item] – warnings from qalx or OrcaFlex

  • [Item] – load case information

Notifications

class qalx_orcaflex.data_models.notifications.Notification(include_creator: bool = False, to: ~typing.List[str] = <factory>, subject: str = '', template: str = '', cc: ~typing.List[str] = <factory>, bcc: ~typing.List[str] = <factory>)

A notification that can be sent to the specified email addresses. Send the notification using the send() method

Parameters:

  • include_creator[bool] – Should the creator of the batch be emailed

  • to[List(str)] – An optional list of emails to send the notification to (default=[])

  • cc[List(str)] – An optional list of users to cc the email to (default=[])

  • bcc[List(str)] – An optional list of users to bcc the email to (default=[])

  • subject[str] – The subject of the email

  • template[str] – An absolute file path or a string that will be rendered with context to form the message of the email

get_context(*args)

Hook for specifying context for a given notification

validate()

Validates the notification :return: True :raises: ValidationError

to_valid_dict()

Ensures the notification is valid before returning the notification as a dict

send(entity, session, extra_context=None)

Sends the notification to the API. :param entity:The entity that should be used when building the template :type entity: QalxEntity :param session:An instance of QalxOrcaFlex :type session: QalxOrcaFlex :param extra_context:An optional dict of extra context to use in the notification :type extra_context: dict

class qalx_orcaflex.data_models.notifications.NotificationSubmitted(include_creator: bool = False, to: ~typing.List[str] = <factory>, subject: str = 'submitted notification subject', template: str = '/opt/build/repo/docs/../qalx_orcaflex/data_models/notifications/templates/notification_submitted.html', cc: ~typing.List[str] = <factory>, bcc: ~typing.List[str] = <factory>)

A notification that can be sent when a batch has been submitted. Send the notification using the send() method

Parameters:

  • include_creator[bool] – Should the creator of the batch be emailed

  • to[List(str)] – An optional list of emails to send the notification to (default=[])

  • cc[List(str)] – An optional list of users to cc the email to (default=[])

  • bcc[List(str)] – An optional list of users to bcc the email to (default=[])

  • subject[str] – The subject of the email

  • template[str] – An absolute file path or a string that will be rendered with context to form the message of the email

get_context(entity)

Constructs the context to be used for sending the notification for the given entity :param entity: The entity that will be used to construct the context

class qalx_orcaflex.data_models.notifications.NotificationCompleted(include_creator: bool = False, to: ~typing.List[str] = <factory>, subject: str = 'completion notification subject', template: str = '/opt/build/repo/docs/../qalx_orcaflex/data_models/notifications/templates/notification_completed.html', cc: ~typing.List[str] = <factory>, bcc: ~typing.List[str] = <factory>)

A notification that can be sent when a batch has been completed. Send the notification using the send() method

Parameters:

  • include_creator[bool] – Should the creator of the batch be emailed

  • to[List(str)] – An optional list of emails to send the notification to (default=[])

  • cc[List(str)] – An optional list of users to cc the email to (default=[])

  • bcc[List(str)] – An optional list of users to bcc the email to (default=[])

  • subject[str] – The subject of the email

  • template[str] – An absolute file path or a string that will be rendered with context to form the message of the email

get_context(entity)

Constructs the context to be used for sending the notification for the given entity :param entity: The entity that will be used to construct the context

class qalx_orcaflex.data_models.notifications.NotificationTimedOut(include_creator: bool = False, to: ~typing.List[str] = <factory>, subject: str = 'timed out subject', template: str = '/opt/build/repo/docs/../qalx_orcaflex/data_models/notifications/templates/notification_timed_out.html', cc: ~typing.List[str] = <factory>, bcc: ~typing.List[str] = <factory>)

A notification that can be sent when a batch has timed out. Send the notification using the send() method

Parameters:

  • include_creator[bool] – Should the creator of the batch be emailed

  • to[List(str)] – An optional list of emails to send the notification to (default=[])

  • cc[List(str)] – An optional list of users to cc the email to (default=[])

  • bcc[List(str)] – An optional list of users to bcc the email to (default=[])

  • subject[str] – The subject of the email

  • template[str] – An absolute file path or a string that will be rendered with context to form the message of the email

get_context(entity)

Constructs the context to be used for sending the notification for the given entity :param entity: The entity that will be used to construct the context

class qalx_orcaflex.data_models.notifications.Notifications(notify_submitted: NotificationSubmitted | None = None, notify_completed: NotificationCompleted | None = None, notify_timed_out: NotificationTimedOut | None = None)

A wrapper for notifications. qalx-orcaflex can send notifications to users at certain points during processing.

Parameters:

  • notify_submitted[NotificationSubmitted] – The details for the notification that should be sent when a batch has been submitted (default=None)

  • notify_completed[NotificationCompleted] – The details for the notification that should be sent when a batch

has completed processing :param notify_timed_out[NotificationTimedOut]: The details for the notification that should be sent when a batch has timed out

validate()

Ensures that all notifications that are specified are valid :raises: ValidationError :return: True

to_valid_dict()

Ensures the notifications are valid before returning the notifications as a dict

Helpers

Smart Statics

Smart statics allows users to add tags to objects in an OrcaFlex model to enable an iterative search for a model that solves in statics.

This is to overcome the common issue where a model that initially solves in statics fails to do so after a small change to the model data. Usually this is fixed in one of a few ways:

  • the user adjusts some damping

  • the user moves a line end around

  • the user changes the statics method

Smart statics gives users the ability to define what they would try in the model and

when the model is run in bots.SimBot the bot will try to find a static solution.

It does this by calling solved_model which is documented below.

class qalx_orcaflex.helpers.smart_statics.SmartStaticsCriterion

Smart statics criterion abstract class. Defines class method that implement the abstract factory pattern to retrieve the correct subclass of abstract criterion

classmethod get_check_type_map()

Defined in a class method as it references the subclasses. This is the map of key to subclass that can be used to identify the correct type

classmethod gather_from_model(model)

Gather all the acceptance criteria from a provided OrcaFlex model

check_acceptance(model)

Check if the criterion is satisfied in the model. Abstract method

class qalx_orcaflex.helpers.smart_statics.SmartStaticsRGCriterion(criteria_definition)

Range graph acceptance criterion

check_acceptance(model)

The “y_static” result is used for the check

class qalx_orcaflex.helpers.smart_statics.SmartStaticsTHCriterion(criteria_definition)

Time history acceptance criterion

check_acceptance(model)

The “static_value” result is used for the check

qalx_orcaflex.helpers.smart_statics.gather_search_criteria(model: Model) → Sequence[Mapping | None]

parses the object tags to get the search criteria and any sequence.

Parameters:

model – ofx.Model

Returns:

list of; Object -> list of Data Item mappings or None

qalx_orcaflex.helpers.smart_statics.check_acceptance_criteria(model, accept_criteria)

Verifies that each of the provided acceptance criteria is satisfied in the provided model

qalx_orcaflex.helpers.smart_statics.apply_absolute_adjustment(obj, data_name, index, initial_value, adjustment)

sets the data value to a random value between adjustment[‘min’] and adjustment[‘max’].

It uses the initial value either is undefined.

qalx_orcaflex.helpers.smart_statics.apply_nudge(obj, data_name, index, adjustment)

sets the data value in a increment defined by adjustment[‘distance’]

qalx_orcaflex.helpers.smart_statics.apply_choice(obj, data_name, index, choices)

sets the data value by selecting at random from choices.

qalx_orcaflex.helpers.smart_statics.apply_cycle_choices(obj, data_name, index, choice_cycle)

sets the data value by selecting in turn from choice_cycle.

choice_cycle is simply itertools.cycle(adjustment[‘choices’])

qalx_orcaflex.helpers.smart_statics.apply_all_adjustments(model, search, cycles, object_filter=None)

applies adjustments to the model as extracted from tags to search.

Object filter should be a list of Object Name:List[Data Name] mappings to be adjusted. An empty list of data names will adjust all data names. If object_filter is left unspecified, all objects will be adjusted.

qalx_orcaflex.helpers.smart_statics.reset_model(model, search)

resets all adjusted parameters in the search

Parameters:

  • model –

  • search –

Returns:

iterate up to max_attempts to find a model that solved

Parameters:

  • model – ofx.Model

  • search – search params

  • max_attempts – number of attempts

  • object_filter – objects and data items to try

Returns:

tuple of ofx.Model and True or False depending on whether the model solves

qalx_orcaflex.helpers.smart_statics.search_all_sequences(model, max_attempts, save_path, acceptance_criteria)

Collects the smart statics search sequences and tries to find a solution in statics that also satisfies the smart statics acceptance criteria

Parameters:

  • model – OrcFxAPI.Model

  • max_attempts – Number of attempts to make

  • save_path – File path to save the solved model

:param acceptance_criteria Smart statics acceptance criteria list :return An OrcFxAPI.Model that solves in statics. :raises QalxSmartStaticsError If no smart statics search criteria are

found

:raises QalxSmartStaticsFailed If no solution is found after smart statics

that also satisfies the acceptance criteria

qalx_orcaflex.helpers.smart_statics.solved_model(model, max_attempts=10, save_path=None)

tries to solve a model in statics, if it fails a search will be performed for a solution based on object tags.

The search is based on tags placed on objects in the model and optionally a sequence of object filters to apply.

To specify a search, add tags to the object you want to be adjusted. The tag name must start with “ss_” followed by the data name to be adjusted then optionally a double underscore (“__”) and the index. If no index is given then the first row (zero index) will be adjusted.

The value of the tag must be a json string containing the type of adjustment from

one of the following options:

  • “type”: “absolute”
    the data value will be set to a random absolute value between

    “min” and “max” if only one is specified then the initial model value is assumed to be the other limit.

  • “type”: “nudge”

    the data value will be changed incrementally by “distance” on each attempt

  • “type”: “cycle”

    the data value will be set by cycling through all the “choices” in turn

  • “type”: “choice”

    the data value will be set to a random selection of “choices”

You can restrict the objects and data names that are adjusted in a sequence by adding tags to General. These must start with SEARCH_SEQUENCE__ and then have a number so SEARCH_SEQUENCE__1, SEARCH_SEQUENCE__2 etc. The value of the tag must be either ALL or a string that contains a mappings of objects to data items that should be adjusted. For example

SEARCH_SEQUENCE__1 => {‘General’:[‘StaticsMinDamping’]} SEARCH_SEQUENCE__2 => {‘Line1’:[]} SEARCH_SEQUENCE__3 => {‘General’:[], ‘Line1’:[]} SEARCH_SEQUENCE__4 => ALL

will try to solve by adjusting only StaticsMinDamping in General, then all data names in Line1 and then both General and Line1 at the same time. All will try to adjust all objects.

Some examples:

setting model[‘General’].tags[‘ss_StaticsMinDamping’] to ‘{“type”:”nudge”, “distance”:1}’ will add one to the minimum full model statics damping each attempt.

setting model[‘Line1’].tags[‘ss_FullStaticsMinDamping’] to ‘{“type”:”cycle”, “choices”:[1,3,5]}’ will set the Line1 minimum damping to 1 then 3 then 5 then back to 1 and so on.

setting model[‘Line1’].tags[‘ss_EndBZ’] to ‘{“type”:”absolute”, “max”:-20}’ will set the Line1 z coordinate of End B to a random value between the initial value and -20.

Parameters:

  • model – OrcFxAPI.Model

  • max_attempts – number of attempts to make

  • save_path – filepath to save the solved model

Returns:

an OrcFxAPI.Model that solves in statics.

General Helper Functions

qalx_orcaflex.helpers.append_node(name, dt=False)

adds node string for uniqueness, option to include datetime string

Parameters:

  • name – original name

  • dt (bool) – include datetime

Returns:

str

qalx_orcaflex.helpers.data_file_paths(directory: PathLike | Sequence[PathLike], skip_fails: bool, recursive: bool)

return paths to all QalxOrcaFlex data files in a directory.

Parameters:

  • directory (str, pathlib.Path, list, tuple) – path to search

  • skip_fails – raise a FileNotFound error if path does not exist (default=True)

  • recursive – recursively search subfolders

Returns:

list of pathlib.Path

qalx_orcaflex.helpers.orcaflex_file_type(model, path: PathLike) → ModelType | None

returns the file type of an orcaflex model

qalx_orcaflex.helpers.is_power_of_two(n)

Returns True if n is a power of two. Assumes n > 0.

qalx_orcaflex.helpers.eliminate_subsets(sequence_of_sets)

Return a list of the elements of sequence_of_sets, removing all elements that are subsets of other elements. Assumes that each element is a set or frozenset and that no element is repeated.

Lifted with love from:

https://stackoverflow.com/questions/14106121/efficient-algorithm-for-finding-all-maximal-subsets

qalx_orcaflex.helpers.check_licence()

true if a licence can be found Useful for polling to wait for a free licence.

qalx_orcaflex.helpers.nice_time(s: float) → str

makes a pretty time string from a number of seconds

qalx_orcaflex.helpers.model_simulation_size(model: Model) → float

estimates simulation size in megabytes from a reset model

Parameters:

model (OrcFxAPI.Model) – model to estimate

Returns:

megabytes size

class qalx_orcaflex.helpers.Spreading(value)

An enumeration.

class qalx_orcaflex.helpers.ModelWithLicence(max_attempts: int, wait_lower: int, wait_upper: int | None = None, spreading: Spreading = Spreading.exponential)

context manager to poll for a license if one is not available

If a licence is available then

>>> with ModelWithLicence(max_attempts=10, wait_lower=5) as model:
...     model.RunSimulation()

Will run the simulation immediately. However, suppose that all the licences are being used in that case the above code will not move to model.RunSimulation until it has tried 10 times. The shortest wait will be 5 seconds and the wait will grow exponetially.

There are other options to control how the wait between attempts will spread.

set up a context manager to only return an OrcFxAPI.Model when there is a licence.

The polling interval is controlled by and instance of helpers.Spreading and wait_lower and wait_upper.

There are four options:

  1. Linear; the first wait will be wait_lower seconds and the final attempt will be wait_upper and

    there will be equal increments determined by max_attempts

  2. Exponential; the first wait will be wait_lower seconds and the final attempt will be wait_upper and

    there will be an exponential increase determined by max_attempts. i.e. there will be very frequent attempts at first but these will become far more spaced out

  3. Random; max_attempts will be made at random intervals between wait_lower and wait_upper

  4. Constant; wait wait_lower seconds max_attempts times

Parameters:

  • max_attempts – number of attempts should we make to get a licence

  • wait_lower – the shortest wait time in seconds

  • wait_upper – the longest wait time in seconds

  • spreading – an instance of helpers.Spreading

spread()

generator which yields the time in seconds to wait

qalx_orcaflex.helpers.add_data_files(session, path, skip_fails=False, recursive=False, extra_data=None, meta=None) → Sequence[Item]

adds datafiles to qalx and returns list of qalx items

Returns:

qalx_orcaflex.helpers.load_model_data(orcaflex_job: OrcaFlexJob, job_options: OrcaFlexJobOptions) → Model

take the job and options and return a model using helpers.ModelWithLicence

qalx_orcaflex.helpers.result_name(n: int, ofx_obj: OrcaFlexObject, res_type: int, result_name: str, oe: ObjectExtra) → str

make a unique string for the result, if available will use the FullName given by OrcaFlex

qalx_orcaflex.helpers.result_details(ofx_obj: OrcaFlexObject, res_type: int, result_name: str, oe: ObjectExtra) → None | Mapping

tries to get the details of the result variable from OrcaFlex if not avilable then returns None

qalx_orcaflex.helpers.clean_set_key(dirty_key: str) → str

get a clean key for items in a set ($ and . are disallowed)

Parameters:

dirty_key –

Returns:

str: clean key

qalx_orcaflex.helpers.get_tags(model: ~OrcFxAPI.Model, tag_filter: ~typing.Callable = <function <lambda>>, from_json: bool = False) → Mapping

create mapping of object name to tags in entire model

Parameters:

  • model – model to process

  • tag_filter – callable to be passed tag name, should return True if tag is to be processed

  • from_json – parse the tag value as json

Returns:

dict of ObjectName -> TagNames -> TagValues

qalx_orcaflex.helpers.required_results_from_yaml(filepath: PathLike) → Sequence[RangeGraph | TimeHistory]

make a dict from a results yaml

Parameters:

filepath –

Returns:

list of required results

qalx_orcaflex.helpers.load_model_sim(orcaflex_job, job_options)

Take the job and options and return a model using helpers.ModelWithLicence from the provided sim file

Bots