Working with the AdditionalCode class

⚠️ 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.

Working with the AdditionalCode class#

Contents#

  1. Introduction

  2. Working with local code

  3. Working with remote code

1. Introduction#

(return to top)

AdditionalCode instances hold collections of related code, either in a local directory or remote repository. In this guide we will explore the structure and methods of the AdditionalCode class.

2. Working with local code#

(return to top)

If the code you intend to work with already exists on your local system, instantiating an AdditionalCode instance is straightforward: provide a path to a directory containing the code, and a list of files:

[1]:

from cstar.base import AdditionalCode

compile_time_code = AdditionalCode(location = "~/Code/my_ucla_roms/Examples/Rivers_real/",
                                   files=["cppdefs.opt",
                                          "flux_frc.opt",
                                          "ocean_vars.opt",
                                          "param.opt",
                                          "river_frc.opt"])
print(compile_time_code)

AdditionalCode
--------------
Location: ~/Code/my_ucla_roms/Examples/Rivers_real/
Subdirectory:
Working path: None
Exists locally: False (get with AdditionalCode.get())
Files:
    cppdefs.opt
    flux_frc.opt
    ocean_vars.opt
    param.opt
    river_frc.opt

Note

We see that “Exists locally” is False, in this context referring to the existence of a local copy that C-Star can work with. C-Star will not attempt to tamper with the original source of any files, and instead works with local copies. A local copy that C-Star can work with can be established using AdditionalCode.get()

Fetching a working copy of the code with AdditionalCode.get():#

[2]:

compile_time_code.get(local_dir = "~/Code/my_c_star/examples/additional_code_example")

[INFO] • Copying cppdefs.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] • Copying flux_frc.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] • Copying ocean_vars.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] • Copying param.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] • Copying river_frc.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] ✅ All files copied successfully

[3]:

print(compile_time_code)

AdditionalCode
--------------
Location: ~/Code/my_ucla_roms/Examples/Rivers_real/
Subdirectory:
Working path: /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
Exists locally: True
Files:
    cppdefs.opt
    flux_frc.opt
    ocean_vars.opt
    param.opt
    river_frc.opt

… We now see that we have a source location, as before, and a working copy, at the Working path. Exists locally is now also True.

3. Working with remote code#

(return to top)

C-Star can also work with code that is stored in a remote repository, using git. The process of creating an AdditionalCode instance in this case involves a couple of additional parameters:

  • checkout_target: the specific point in the history of the repository to work worth. This can be either a branch, tag, or commit hash.

  • subdir: the subdirectory of the repository containing the files

Let’s create the same AdditionalCode as above, but with a remote source this time:

[4]:

compile_time_code = AdditionalCode(location = "https://github.com/CESR-lab/ucla-roms.git",
                                   files=["cppdefs.opt",
                                          "flux_frc.opt",
                                          "ocean_vars.opt",
                                          "param.opt",
                                          "river_frc.opt"],
                                          subdir = "Examples/Rivers_real",
                                          checkout_target = "main")
print(compile_time_code)

AdditionalCode
--------------
Location: https://github.com/CESR-lab/ucla-roms.git
Subdirectory: Examples/Rivers_real
Checkout target: main
Working path: None
Exists locally: False (get with AdditionalCode.get())
Files:
    cppdefs.opt
    flux_frc.opt
    ocean_vars.opt
    param.opt
    river_frc.opt

Fetching a working copy of the code with AdditionalCode.get().#

For a remote repository, C-Star clones the repository to a temporary directory, then copies the desired files to the local target directory:

[5]:

compile_time_code.get(local_dir = "~/Code/my_c_star/examples/additional_code_example")

[INFO] • Copying cppdefs.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] • Copying flux_frc.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] • Copying ocean_vars.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] • Copying param.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] • Copying river_frc.opt to /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
[INFO] ✅ All files copied successfully

[6]:

print(compile_time_code)

AdditionalCode
--------------
Location: https://github.com/CESR-lab/ucla-roms.git
Subdirectory: Examples/Rivers_real
Checkout target: main
Working path: /Users/dafyddstephenson/Code/my_c_star/examples/additional_code_example
Exists locally: True
Files:
    cppdefs.opt
    flux_frc.opt
    ocean_vars.opt
    param.opt
    river_frc.opt