Running a simulation
====================

Once you have configured the inputs for the simulator (see :doc:`Configuring the inputs for a
simulation </usage/inputs/inputs_index>`), you can run the simulation.

The simulation can be run interactively via a web interface or programmatically as part of a Python
script or Jupyter notebook. It can also be run on the commandline.

.. contents::
    :local:
    :depth: 2

See also the :doc:`Interpreting simulation outputs </usage/outputs/outputs_index>` section for
information on interpreting the logs and dataframes produced by the simulator.

This page covers running a basic simulation. See the :doc:`Tutorials </tutorials/tutorials_index>`
section for ways to customise the simulation, optimise the hardware configuration, run monte carlo
simulations and run end-to-end experiments.

Using the web interface
-----------------------

To use the web interface, run the application locally using Poetry:

::

    poetry run resource_model

The app will run on localhost at port 8050 by default: http://127.0.0.1:8050/. Use ``Ctrl + C`` in
the terminal to stop the server.

Plots
~~~~~

The web interface provides several interactive example plots on the front-end:

- A tree map of scheduling block metrics read from ``data/config/scheduling_block_types.json``.
- A Gantt-style chart of scheduled block instances read from
  ``data/schedules/observing_schedule.json``.
- A summary of the total run time.
- A line plot of the compute node usage over time.
- A line plot of the capacity storage usage (raw visibilities and data products) over time.
- A line plot of the performance storage usage (pre-processed visibilities) over time.
- A Gantt-style chart showing the start and end of batch processing for each scheduling block
  instance that triggers (where start is defined as the time when performance storage has been
  allocated and end is when all processing has completed and performance storage has been released).
- A strip plot showing individual wait times for each scheduling block instance. This includes
  waiting for capacity storage (either for raw visibilities or data products), performance storage
  and compute nodes.

.. _using-the-cli:

Using the CLI
-------------

To use the CLI, run the application locally using Poetry. You can find more detailed usage
information by running:

.. code-block:: bash

    poetry run resource_usage --help

This will output the following help message:

.. include:: help_text_simulate.txt

Using the API
-------------

The following code snippet demonstrates how to run the simulator in a Python script. This will
output two pandas DataFrames containing resource usage and event logs. You can then use these
DataFrames to generate plots or perform further analysis.

.. code-block:: python

    from ska_sdp_resource_model.simulate.resource_usage import ResourceUsageSimulator
    from ska_sdp_resource_model.simulate.process_inputs import process_inputs

    # Define a path to your observing schedule JSON file
    path_to_observing_schedule = "data/schedules/observing_schedule.json"

    # Process the inputs
    observations_list, hardware_config_data = process_inputs(
        observing_schedule_path=path_to_observing_schedule
    )

    # Create an instance of the simulator
    simulator = ResourceUsageSimulator()

    # Run the simulation
    output = simulator.run_simulation(observations_list, hardware_config_data["50_50"])

Using a Jupyter notebook
------------------------

We have included example Jupyter notebooks in the `notebooks directory
<https://gitlab.com/ska-telescope/sdp/ska-sdp-resource-model/-/tree/main/notebooks>`_ of the
repository.

- ``01-basic-simulation.ipynb`` demonstrates how to run the simulation for multiple hardware
  configurations and generate plots to compare the results.