.. _results: Results ======= You can specify the results you wish to have processed by the `SimBot `_ before you run them. This has two main advantages: - No need to reload the simulation to post-process it - Result data stored in qalx and available to pass to reporting or other calculation bots Specification ------------- Results must conform the the required results specification outlined below. The attributes should be familiar to anyone who has used the `OrcaFlex Python API `_. .. _range_graph: Range Graph ~~~~~~~~~~~ .. code-block:: yaml RangeGraph: object: Line Name variable: Result Name period: from_time: 0 to_time: 100 stage_number: 0 named_period: Whole Simulation | Latest Wave | Static State object_extra: line_radial_position: Inner | Outer line_theta: 35.0 line_clearance_line_name: Another Line Name external_result_text: External Result Text arc_length_range: from_arc: 0 to_arc: 50.5 from_section: 1 to_section: 2 storm_duration_hours: 3.0 meta: name: My {variable} result for stage {period['stage_number']} stat: Min | Max | Both as_file: True | False .. _time_history: Time History ~~~~~~~~~~~~ .. code-block:: yaml TimeHistory: object: Object Name variable: Result Name period: from_time: 0 to_time: 100 stage_number: 0 named_period: Whole Simulation | Latest Wave | Static State object_extra: position: - 0 # x - 0 # y - 0 # z line_node: 12 line_arc: 33.5 line_named_point: End A | End B | Touchdown line_radial_position: Inner | Outer line_theta: 35.0 line_clearance_line_name: Another Line Name external_result_text: External Result Text wing_name: Another Wing winch_connection: 0.5 support: support_index: 0 supported_line_name: A Line turbine: blade_index: 0 blade_arc_length: 0.5 meta: name: My Result Name stat: Min | Max | Both limit: max: 100 min -100 as_file: True | False The one element of the specification that is specific to ``qalx_orcaflex`` are the ``meta`` options. These are included to help with presentation of the results when they are processed. ``name`` will overwrite the full name of the result produced by OrcaFlex. This is useful when you know what the result means but the output from OrcaFlex would be somewhat opaque. For example "Cable Bend Radius between 0.521m and 5.23m for stage 2" might be better replaced with "Cable Bend Radius in Bend Stiffener during Lay-away". You can also give the limit that is of most concern as the ``stat`` parameter. Following the previous example, maximum bend radius is of very little interest as it will be infinite for a straight line so giving ``stat:"Min"`` allows you to show only results for the minimum value. Usage ----- Results can be specified by building results objects directly in python either using the data model classes or the class method ``from_dict``: .. code-block:: python from qalx_orcaflex import data_models as dm from qalx_orcaflex.core import FileSource range_graph = dm.RangeGraph( object = "Line", variable = "Effective Tension", period = dm.Period( from_time=0, to_time=10 ) ) time_history = dm.TimeHistory( object= "Line" variable = "Bend Moment" period = dm.Period( stage_number= 1 ) object_extra=dm.ObjectExtra( line_named_point= "End A" ) ) another_th = dm.TimeHistory.from_dict( { "meta": {"name": "Water velocity at 5m below surface"}, "object": "Environment", "object_extra": {"position": [0.0, 0.0, -5.0]}, "period": {"stage_number": 1}, "variable": "Velocity", }, ) required_results = (range_graph, time_history, another_th) These are then added with the ``required_results`` argument to ``batch.add``. Results are added per-sim and not per-batch so you can define different results for each simulation in a batch if required. This may make the :ref:`results_summaries` less useful however. .. code-block:: python qfx = QalxOrcaFlex() batch_options = dm.BatchOptions( batch_queue="batch bot", sim_queue="sim bot", ) with OrcaFlexBatch(name="My Batch", session=qfx, batch_options=batch_options) as batch: batch.add( FileSource(r"S:\Project123\OFX\Batch456\MY_MODEL.dat"), required_results=required_results ) Alternately, you can write a yaml file: .. code-block:: yaml # SAVED AS my_results.yaml Results: - RangeGraph: object: Line variable: Effective Tension period: from_time: 0 to_time: 10 - RangeGraph: object: Line variable: Curvature period: from_time: 0 to_time: 10 - RangeGraph: object: Line variable: Curvature period: named_period: Latest Wave arc_length_range: from_arc: 2.5 to_arc: 20.5 meta: name: Bend Stiffener Region Curvature for Line - RangeGraph: object: Line variable: Bend Moment period: named_period: Latest Wave arc_length_range: from_arc: 2.5 to_arc: 20.5 meta: name: Bend Stiffener Region Bend Moment for Line - RangeGraph: object: Line variable: Effective Tension period: from_time: 0 to_time: 10 - TimeHistory: object: Environment variable: Velocity period: stage_number: 1 object_extra: position: [0.0, 0.0, -5.0] meta: name: Water velocity at 5m below surface - TimeHistory: object: Line variable: Bend Moment period: stage_number: 1 object_extra: line_named_point: End A You then only need to pass the path to the yaml file to ``batch.add`` .. code-block:: python from qalx_orcaflex.core import FileSource required_results = r"C:\Users\AnneAlysis\OFX\Project123\my_results.yaml qfx = QalxOrcaFlex() batch_options = dm.BatchOptions( batch_queue="batch bot", sim_queue="sim bot", ) with OrcaFlexBatch(name="My Batch", session=qfx, batch_options=batch_options) as batch: batch.add( FileSource(r"S:\Project123\OFX\Batch456\MY_MODEL.dat"), required_results=required_results ) .. _extracted_results: Extracted results ----------------- The required results above are attached to every :ref:`orcaflex_job` and :ref:`sim_bot` will add an `extracted` field to the results once they are extracted. These are structured as follows: ``ExtractedRangeGraph``: - arc: list of arc lengths that the result applied to - y_min: values of the minimum result - y_mean: values of the mean result - y_max: values of the maximum result - y_static: values of the static result ``ExtractedTimeHistory``: - time: list of the time values the result applies to - y_values: the values of the result at each time value - static_value: the value of the result at statics .. _results_summaries: Results summaries ----------------- One of the main functions of :ref:`batch_bot` is to wait until all the simulations in a batch have run and then summarise the results. Once these are ready then you can use a helper function on ``QalxOrcaFlex`` to view them. .. code-block:: python from qalx_orcaflex.core import QalxOrcaFlex qfx = QalxOrcaFlex() results = qfx.get_batch_results_summary("MY BATCH NAME") This ``results`` variable will contain a mapping that follows the structure below: .. code-block:: javascript {"Range Graphs: {"[#] rg Name of Range Graph Result": { "result_meta": some metadata about the result. Some of this can be pre-specified and some is extracted post-sim "max_value": the maximum value of this result across all sims "arc_max_value": the arc of the max value "max_case_info": the load case info for the maximum case "max_result_guid": the guid of the qalx item for the max result "min_value": the minimum value of this result across all sims "arc_min_value": the arc of the min value "min_case_info": the load case info for the minimum case "min_result_guid": the guid of the qalx item for the min result "static_max_value": the static maximum value of this result across all sims "arc_static_max_value": the arc of the static max value "static_max_case_info": the load case info for the static maximum case "static_max_result_guid": the guid of the qalx item for the static max result "static_min_value": the static minimum value of this result across all sims "arc_static_min_value": the arc of the static min value "static_min_case_info": the load case info for the static minimum case "static_min_result_guid": the guid of the qalx item for the static min result "vs_info": mappings to be able to plot results against loadcase info } } "Time Histories": {"[#] th Name of Time History": { "result_meta": some metadata about the result. SOme of this can be pre-specified and some is extracted post-sim "max_value": the maximum value of this result across all sims "time_max_value": the time of the maximum value "max_case_info": the load case info for the maximum case "max_result_guid": the guid of the qalx item for the max result "min_value": the minimum value of this result across all sims "time_min_value": the time of the minimum value "min_case_info": the load case info for the minimum case "min_result_guid": the guid of the qalx item for the min result "vs_info": mappings to be able to plot results against loadcase info } } }