Bots

One of the core features of qalx is the ability to define Bots. These are chunks of code that are designed to be passed qalx entities for processing.

qalx_orcaflex includes two pre-built bots which manage the simulation of batches of OrcaFlex data files and implement all the features provided by qalx_orcaflex.

Details of the individual bots are provided in Sim Bot and Batch Bot below. However, these should generally only be used for testing Custom Bots or developing the bots themselves.

The best method for deploying these bots (and any other bots you may have built) for production is with a pyqalx factory.

It is worthwhile reading the pyqalx factories documentation to ensure you are familiar with factory plans, sector types and deployment.

`qalx_orcaflex` Factories

A factory plan is a YAML document containing the information qalx needs to get sim_bot and batch_bot running locally or on an AWS server. For more details on how to craft these plans please see Factory Plans.

Sim Bot

The SimBot takes a pyqalx.Set which defines the OrcaFlexJob and processes it with the following steps:

Load the model data - this will only return once it has been able to get a licence or has tried multiple times to get one as defined in OrcaFlexJobOptions
Define progress handlers if required
Calculate the estimated size of the simulation and based on available RAM disable in-memory logging if required.
Attempt statics, use Smart Statics if defined in model tags. If statics fails then none of the follow steps are completed.
Attempt dynamics. If dynamics fails none of the following steps are completed.
Save the simulation file to qalx if required.
Extract results if required.
Extract load case information if required.
Extract model views if required.
Extract model videos if required.
If simulation stopped due to instability then report this in the warnings and update the state
Put the OrcFxAPI.Model instance into the the step result data so a custom post-processing function can play with it
If send_sim_to has been specified on BatchOptions then the sim will be sent to those queues

Video Bot

The VideoBot takes a pyqalx.Set which defines the OrcaFlexJob and extracts the model videos specified on the job.

Note

This bot can be used when the OrcaFlexJob contains a sim file. In the case that you are interested in extracting a video from a model that is not analysed yet, you can do so by using the Sim Bot instead.

State

The state of a job is updated throughout the simulation life cycle, this information is stored on the meta of the pyqalx.Set that represents the OrcaFlexJob.

To quickly view the state of sim in a batch, a helper function is provided:

from qalx_orcaflex.core import QalxOrcaFlex

qfx = QalxOrcaFlex()
qfx.print_batch_state(
        batch_name="My Batch"
    )

If there was an error then this will be displayed here.

Progress

The OrcaFlexJob has a progress item which is updated throughout the life cycle of the simulation. To quickly view the progress of a batch, a helper function is provided:

from qalx_orcaflex.core import QalxOrcaFlex

qfx = QalxOrcaFlex()
qfx.print_batch_progress(
        batch_name="My Batch"
    )

Warnings

OrcaFlex will sometimes issue warnings to the user when running a simulation. These are captured by Sim Bot and saved to qalx. Additionally, there may be some warnings generated by Sim Bot itself, e.g. when a required result has been specified for an object which doesn’t exist in the the model. As above, there is a helper to see these warnings:

from qalx_orcaflex.core import QalxOrcaFlex

qfx = QalxOrcaFlex()
qfx.print_batch_warnings(
        batch_name="My Batch"
    )

Print all the things

If you found the helpers above er… helpful then try this out:

from qalx_orcaflex.core import QalxOrcaFlex

qfx = QalxOrcaFlex()
qfx.print_batch_case_info(
        batch_name="My Batch"
    )

This will print out the state, progress and warnings all in one go.

Batch Bot

The BatchBot takes a pyqalx.Group which defines everything made by Building Batches and processes it with the following steps:

If the cases have not been added to the simulation queue, add them.
Check if all the jobs are complete (this does not mean that all the sims are error-free).
If the sims are not complete, have a little sleep and then put the group back on the queue.
If the sims are complete summarise the results (if set in batch options which it is by default)
If send_batch_to was specified in the options then send the batch on to those queues.

coming soon!

there is currently no (easy) way to cancel jobs once they are on the queue but this is on the Roadmap

Starting bots

Command line

If you have qalx_orcaflex installed on a machine then you can start the bots using the command line interface qalx.

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

This will start the SimBot with 8 workers looking at “example-sim-queue”.

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

The above command starts BatchBot in a single process looking at “example-batch-queue” for jobs.

qalx bot-start --queue-name example-video-queue --processes 1 qalx_orcaflex.bots:video_bot

The above command starts VideoBot in a single process looking at “example-video-queue” for jobs.