---
# System prepended metadata

title: C-Star

---

# C-Star

C-Star is a Python package that supports deploying geophysical model calculations. 

This document sketches out some of the core objects and functionality of C-Star.

## Install

To install C-Star execute the following 
```bash!
conda install cstar-ocean
```
or just the compute
```bash!
conda install cstar-compute
```

## Programs

### Configure Blueprints
AKA ROMS Tools

### C-Star Compute
Deploy and run a C-Star instance.

### C-Star Analysis
Run analytics on C-Star data, other model data, & observations.


### C-Star Atlas
Visualize & interrogate mCDR datasets; support performant computation of mCDR net carbon removal.


# Compute

## Command line interface
CLI implemented [`cli_cli.py`](##`cstar_cli.py`).

### Model runs
Prepare to run a model by creating a new C-star `instance`. 
```bash!
cstar instance create --blueprint cstar_ccs4km --dir_instances /work/cworthy-ocean 
```

### Model development
Obtain the model code supporting a particular C-Star `blueprint`: 
```bash!
cstar blueprint checkout --name cstar_ccs4km
```

### C-Star development
Develop C-Star:
```bash!
git clone git@github.com:CWorthy-ocean/C-Star.git my_cstar_sandbox
cd my_cstar_sandbox
```


## `deploy.py`

```python=
"""Deploy C-Star on a HPC machine

Each function in this module has a corresponding
CLI in cstar_cli.py.
"""


def blueprint_checkout(name, dir_blueprints=None):
    """Configure the source code supporting 
       C-Star blueprint on a users machine.
       
    Args:
      name (str): 
        The name of a registered C-Star blueprint
        sandbox (path, optional): 
    
      dir_blueprints (path):
        Path to put code; defaults to /.
    """
    

def instance_create(blueprint_name, dir_blueprints=None, dir_instances=None
):
    """Configure an instance to configure, build and run.
       
    Args:
      blueprint_name (str): 
        The name of a registered C-Star domain
      
      dir_blueprints (path, optional): 
        Path to put the blueprint_root; defaults to /.

      dir_instances (path, optional): 
        Path to put the instance_root; defaults to /.
    """    
```



## `core.py`

```python=
"""Instantiate C-Star's core classes.

"""
```

Psuedo-code for object definitions.

### `class instance`
```yaml=
# this is the core executable component of C-Star
instance:
  # attributes set at self.__init__()
  attributes:
    - name: 'cstar_ccs4km.hindcast.19000101-20201231'
    - blueprint: CSTAR_CCS4km # a `blueprint` object
    - machine: 'Perlmutter' # an instance is machine-specific
    
    # paths
    - path_all_instances: '/work/cworthy_ocean'
    - path_scratch: '/scratch/cworthy_ocean/instance_data'
  
  # properties are derived from self
  properties:
    - path_blueprint # path to the blueprint source
    - path_instance_root # self.path_all_instances  + self.name
    - path_run # self.path_scratch + self.name
    - path_self # where I live when I'm on disk
    - registry_id # unique identifier      
    - history # everything that's been done
    - status # the step that we're currently 
             # on in executing this instance
    
  # methods are callable
  methods: 
    - persist # store this object on disk
    - setup # configure the instance on the machine
    - build # build the code 
    - pre_run # do something before submitting
    - run # execute the scipts that run the codes
    - post_run # do something after the run completes
```


What does it look like to set `path_self`?
```python!
@property
def path_self(self):
    """Query the C-Star instance database; 
    return the path where I live on disk.
    
    """
    return registry.instance.get_spec(self)

```

### `class blueprint`
```yaml=
blueprint:
  attributes:
    - registry_data: 
      - name: cstar_ccs4km # registered in blueprint_namespace
      - child_blueprint: None
      - parent_blueprint: dataset_glorys
    - components: # the models that are used
        - ROMS # ROMS's instantiated cstar_component
        - MARBL # same but for MARBL
    - grids:
      - CCS_4km # cstar_grid
    - inputdata:
      - forcing: [forcing_met, forcing_cdr]
      - boundary_conditions: [bc_glorys]
      - initial_conditions: [ic_glorys]
    - model_settings_inputs:
      - ROMS: [settings]
      - MARBL:
    - run_defaults:
methods:
    - create_sandbox
    - create_instance
    - clone_instance
```
### `class component`
```yaml
attributes:
  - name: 'ROMS'
  - source:
    tag: cstar_beta.v2024-04-06.n00
    protocol: git
    repo_url: 'https://github.com/CESR-lab/ucla-roms.git'
    local_path: UCLA-ROMS
    required: True
methods:
  - checkout_source
  - setup
  - build  
  - run
  - finalize  
```

### `class machine`
```yaml=
machine:
  name: Perlmutter
  compiler: intel
  queuing: PBS
  job_script_template:
    - #PBS...
    - #PBS...
  build_environment:
    - module load intel
    - module load netcdf
  paths:
    scratch: /path/to/scratch/space # non persistent
    work: /path/to/work/space # persistent storage

```

## `config.yml`
```yaml=
# store key C-Star configuration details 
# populated on C-Star installation
# CLI tools provided to edit/manage C-Star defaults
machine_name: {{machine_name}}
account_keys: {{account_key_list}}
paths:
  instances: {{path_to_work}}
  scratch: {{path_to_scratch}}
  home: {{path_to_home}}
```

## `execute.py`

```python=
"""Manage the submission of compute jobs 
   via queing systems (or other?)."""
   
def submit():
    """Submit a job
    """
    
def query_job():
    """Query the status of a job
    """
```

## `registry.py`

### `class blueprint`
This is a database function of C-Star that curates the information necessary to instantiatiate a C-Star `blueprint` object.

### `class instance`
The is a database function of C-Star that curates the information necessary to instantiatiate a C-Star `instance` object.

## `catalog.py`

This is function of C-Star that curates access points to defined C-Star datasets. 

C-Star generated data become part of a catalog too. 

The catalog supports publication, including documentation generated from C-Star workflow elements.

## `cstar_cli.py`
```python=
"""Implements the C-Star CLI.

"""

@click
def blueprint_checkout(...):
    """call deploy.blueprint_checkout
    
    Usage:
      cstar blueprint checkout --name ccs_4km
    """

    
@click    
def instance_create(...):
    """call deploy.instance_create
    
    Usage: 
      cstar instance create --blueprint ccs_4km 
    """
    
@click
def config_update(*args):
    """all the user to change key config.yml
    
    Usage:
      cstar config update --home /home/king-neptune
    """
    # unmunge args to get key
    key = unmunge(*args) # multiple key levels possible
    return config_key(key) 
```

# Analysis
[WIP]

# Atlas
[WIP]
