.. _quickstart:

Quickstart
==========

Build a batch
+++++++++++++

The code below will create a mesh sensitivity batch and highlight some of the key features. The comments in the code should help to clarify the process.

.. code-block:: python

    import OrcFxAPI as ofx  # why so much typing?
    import numpy as np  # need some numpy magic
    from qalx_orcaflex.core import QalxOrcaFlex, OrcaFlexBatch, ModelSource  # core classes
    from qalx_orcaflex import data_models as dm  # get data_models with little typing

    qfx = QalxOrcaFlex()  # initialise a pyqalx session for OrcaFlex

    m = ofx.Model()  # empty model
    line = m.CreateObject(ofx.otLine, "My Line")  # make a line
    line.Length[0] = 200  # make the line long
    line.EndAX = 0  # move end A
    line.EndBX = 150  # move end B
    line.EndAY, line.EndBY, line.EndAZ, line.EndBZ = (0, 0, 0, 0)  # put everything else at 0
    line.TargetSegmentLength[0] = 0.5  # initial segment length

    batch_options = dm.BatchOptions(
        batch_queue="example batch bot",  # queue our batch bot is looking at for jobs
        sim_queue="example sim bot",  # queue our sim bot is looking at for jobs
    )

    ofx_batch = OrcaFlexBatch(
        "Example sensitivity batch",  # name of the batch
        session=qfx,  # qalx session we created earlier
        batch_options=batch_options,  # options for this batch
        meta={"example": "mesh_sensitivity"},  # some metadata (could be anything here)
        verbose=True,  # show some print statements so we can see what's happening
    )

    results = [  # I want some results
        dm.RangeGraph(  # a range graph
            object="My Line",  # of line
            variable="Curvature",  # curvature
            period=dm.Period(named_period="Latest Wave")  # for the latest wave
        ),
        dm.RangeGraph(  # and a range graph
            object="My Line",  # for line
            variable="Effective tension",  # tension
            period=dm.Period(named_period="Latest Wave")  # for the latest wave
        ),

    ]

    with ofx_batch as batch:  # let's build this batch
        for l_seg in np.linspace(0.01, 0.5, 10):  # I want 10 segment lengths equally spaced between 0.01 and 0.5
            line.TargetSegmentLength[0] = l_seg  # set the segment length
            case_info = dm.RawInfo(key="Segment Length", value=l_seg)  # define some load case information
            batch.add(
                source=ModelSource(m, f"seg@{l_seg:2.2}"),  # add the model with a name that shows the segmentation
                load_case_info=dm.LoadCaseInfo(raw_info=[case_info]),  # add the load case info
                required_results=results  # add the results
            )

    # Once the code has exited the above `with` block then the batch has been built and submitted




Start the bots
++++++++++++++

We use the `qalx` command line tool to start the `BatchBot` and `SimBot`

.. code-block::

    qalx bot-start --queue-name "example batch bot" qalx_orcaflex.bots:batch_bot

In a separate command line window

.. code-block::

    qalx bot-start --queue-name "example sim bot" qalx_orcaflex.bots:sim_bot

Read the results
++++++++++++++++

Once your jobs have finished you can get the results summary and references to all the jobs and results:

.. code-block:: python

    from qalx_orcaflex.core import QalxOrcaFlex

    qfx = QalxOrcaFlex()

    mesh_batch_results = qfx.get_batch_results_summary("Example sensitivity batch")

    for result_name, range_graph in mesh_batch_results['Range Graphs'].items():
        print(f"{result_name}: Max {range_graph['max_value']:2.2f} @ {range_graph['arc_max_value']:2.2f}")
        worst_case_info = range_graph['max_case_info']
        print(f"worst segment length={worst_case_info['Segment Length']}m")


Where's a nice pretty user interface?
+++++++++++++++++++++++++++++++++++++

Short answer, there isn't one. There are a few reasons for this:

- User interfaces are hard to get right and we didn't want to just ship a poor one
- We expect a lot of users to already have their own interfaces and systems that they would integrate with
- :ref:`custom_interface` shows how easy it is to create your own