Tracking runs executed locally

⚠️ This project is still in an early phase of development.

The python API is not yet stable, and some aspects of the schema for the blueprint will likely evolve. Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility. We expect to reach a more stable version in 2026.

To see which systems C-Star has been tested on so far, see Supported Systems.

Tracking runs executed locally#

Contents#

Introduction
Importing and setting up an example Simulation to run locally
Running and tracking the Simulation
Cancelling a run
Summary

1. Introduction#

(return to top)

On this page, we will look at how to monitor processes created by C-Star where execution is handled locally in more detail. If you are running C-Star on a supported HPC system with a job scheduler, see the next page. There are many features in common between jobs run locally and those submitted to a job scheduler, but the former is more simple.

2. Importing and setting up an example Simulation to run locally#

(return to top)

We will import and set up the example simulation from our tutorial

[1]:

from cstar.roms import ROMSSimulation

example_simulation_1 = ROMSSimulation.from_blueprint(blueprint  = "../tutorials/roms_marbl_example_simulation.yaml",
                                                     directory   = "../../examples/example_case",
                                                     start_date = "2012-01-03 12:00:00",
                                                     end_date   = "2012-01-06 12:00:00")

We can now set up and run the Simulation as in the tutorial, assigning the LocalProcess instance returned by Simulation.run() to a variable we can keep track of.

[ ]:

example_simulation_1.setup()
example_simulation_1.build()
example_simulation_1.pre_run()
# Cell output cleared for brevity

3. Running and tracking the Simulation#

(return to top)

3i. Beginning the run#

We can start the simulation using the run() command, which creates a LocalProcess instance that we can assign to a variable for tracking:

[3]:

cstar_task = example_simulation_1.run()

3ii. Checking the status#

We can check the run status using the status property. Possible values for a local run are:

UNSUBMITTED: the run has not yet started
RUNNING: the run is underway
COMPLETED: the run finished successfully
CANCELLED: the run was cancelled by the user
FAILED: the run finished unsuccessfully
UNKNOWN: the status cannot be determined

[4]:

cstar_task.status

[4]:

<ExecutionStatus.RUNNING: 3>

3iii. Viewing the output file path#

The output file contains the standard output and error streams returned by the run

[5]:

cstar_task.output_file

[5]:

PosixPath('/Users/dafyddstephenson/Code/my_c_star/examples/example_case/output/cstar_process_20250428_153231.out')

3iv. Receiving live updates from the output file#

While the process is running, we can stream any new lines written to the output file using the updates() method. This method receives a seconds parameter, and will provide live updates for the number of seconds provided by the user (default 10). If the user specifies seconds=0, updates will be provided indefinitely until either the updates are stopped with a keyboard interruption (typically via Ctrl-c) or the process ends.

[6]:

cstar_task.updates(seconds=0.5)

[INFO]  doing BGC with MARBL

[INFO]     207 4383.6437 5.56657654288-03 4.8813609378-03  0.004795433031  0.004294010343      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     208 4383.6444 5.57008061171-03 4.8853947441-03  0.004795468914  0.004289735790      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     209 4383.6451 5.57349072286-03 4.8893689968-03  0.004796358802  0.004285428296      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     210 4383.6458 5.57687254643-03 4.8933149533-03  0.004797979475  0.004281175962      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     211 4383.6465 5.58024026485-03 4.8972639551-03  0.004800026957  0.004276959422      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     212 4383.6472 5.58362453883-03 4.9012471214-03  0.004802119583  0.004272742086      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     213 4383.6479 5.58703114089-03 4.9052801682-03  0.004803821320  0.004268465051      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     214 4383.6486 5.59045325751-03 4.9093625130-03  0.004804690025  0.004264061629      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     215 4383.6493 5.59390604880-03 4.9134798374-03  0.004804333260  0.004259478094      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     216 4383.6500 5.59737601841-03 4.9176068214-03  0.004802438823  0.004254670282      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     217 4383.6506 5.60082596830-03 4.9217189412-03  0.004798807856  0.004249610124      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     218 4383.6513 5.60421597753-03 4.9257967139-03  0.004793373868  0.004244286834      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     219 4383.6520 5.60756946908-03 4.9298296478-03  0.004786201255  0.004238699187      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     220 4383.6527 5.61088235467-03 4.9338215265-03  0.004777540838  0.004232915875      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     221 4383.6534 5.61419815952-03 4.9377906744-03  0.004767687678  0.004226950334      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     222 4383.6541 5.61755195217-03 4.9417660703-03  0.004757046704  0.004220851708      9     21   10

[INFO]  doing BGC with MARBL

[INFO]     223 4383.6548 5.62094445980-03 4.9457813637-03  0.004746079199  0.004214682976      9     21   10

[INFO]  doing BGC with MARBL

4. Cancelling a run#

(return to top)

We can cancel the job using the cancel method:

[7]:

cstar_task.cancel()

[8]:

cstar_task.status

[8]:

<ExecutionStatus.CANCELLED: 5>

5. Summary#

(return to top)

In this guide, we set up and ran the example Simulation that we built in another tutorial, with a particular focus on the LocalProcess instance associated with the run. We looked at tracking the run’s status and output files, and cancelling the run.