Working with the ExternalCodeBase class

Working with the ExternalCodeBase class#

Contents#

  1. Introduction

  2. Default codebase instances

  3. Custom codebase instances

  4. Installing external codebases

1. Introduction#

Advanced users may wish to control the specific version of external codebases to C-Star like model source code that is not specific to a particular simulation. Currently C-Star supports two external codebases: the regional ocean circulation model ROMS and the ocean biogeochemistry library MARBL. These codebases respectively correspond to two subclasses of the ExternalCodeBase class in C-Star, ROMSExternalCodeBase and MARBLExternalCodeBase.

2. Default codebase instances#

When creating a ROMSSimulation instance without providing information about these codebases, C-Star reverts to defaults. We can see these defaults by instantiating the ExternalCodeBase subclasses without any parameters:

[1]:

from cstar.roms import ROMSExternalCodeBase
roms_codebase = ROMSExternalCodeBase()
print(roms_codebase)

ROMSExternalCodeBase
--------------------
source_repo : https://github.com/CESR-lab/ucla-roms.git (default)
checkout_target : main (corresponding to hash 2b0c2508647763b3edaee4c0b2bdfdcde385740e) (default)
local_config_status: 2 (Environment variable ROMS_ROOT is present, points to the correct repository remote, but is checked out at the wrong hash)

This tells us three things about our default ROMS codebase:

  • The source code is maintained by CESR (a lab at UCLA) on GitHub

  • C-Star will use the latest code on the main branch of this repository

  • The codebase has not been installed and configured locally

[2]:

from cstar.marbl import MARBLExternalCodeBase
marbl_codebase = MARBLExternalCodeBase()
print(marbl_codebase)

MARBLExternalCodeBase
---------------------
source_repo : https://github.com/marbl-ecosys/MARBL.git (default)
checkout_target : marbl0.45.0 (corresponding to hash 6e6b2f7c32ac5427e6cf46de4222973b8bcaa3d9) (default)
local_config_status: 0 (Environment variable MARBL_ROOT is present, points to the correct repository remote, and is checked out at the correct hash)

This tells us three things about our default MARBL codebase:

  • The source code is maintained by the marbl-ecosys group on GitHub

  • C-Star will use the specific release 0.45

  • The codebase has not been installed and configured locally

3. Custom codebase instances#

As noted above, advanced users may wish to deviate from these defaults, which can be done quite simply when creating the instance by supplying the parameters source_repo (The location of a git repository) and checkout_target (a target in that repository’s history).

As an example, let’s use a fork of ROMS, checked out to a specific commit hash:

[3]:

my_roms_codebase = ROMSExternalCodeBase(source_repo="https://github.com/dafyddstephenson/ucla-roms",
                                        checkout_target="f71c4e29ff45043bc6ef564da98a16366f9cd19b")
print(my_roms_codebase)

ROMSExternalCodeBase
--------------------
source_repo : https://github.com/dafyddstephenson/ucla-roms
checkout_target : f71c4e29ff45043bc6ef564da98a16366f9cd19b
local_config_status: 1 (Environment variable ROMS_ROOT is present but does not point to the correct repository remote [unresolvable])

4. Installing external codebases#

Note

Most users will not need to use the get() method or manually install codebases: if your ExternalCodeBase is part of a ROMSSimulation instance, then C-Star will call get() automatically as part of any ROMSSimulation.setup() call.

Should you wish to install the codebase you have created, you can use the get() method. This will typically modify your ~/.cstar.env file, which is read by C-Star each time you use it to configure your environment and persist codebase installs between sessions:

[4]:

my_roms_codebase.get(target="~/Code/my_c_star/examples/external_codebase_example/ucla_roms")

[INFO] Updating environment in C-Star configuration file /Users/dafyddstephenson/.cstar.env

[5]:

print(my_roms_codebase)

ROMSExternalCodeBase
--------------------
source_repo : https://github.com/dafyddstephenson/ucla-roms
checkout_target : f71c4e29ff45043bc6ef564da98a16366f9cd19b
local_config_status: 0 (Environment variable ROMS_ROOT is present, points to the correct repository remote, and is checked out at the correct hash)

… We now see the local_config_status has updated to reflect the installation of ROMS.