Skip to content

Commit

Permalink
Merge branch 'upstream/main' into improve_runtime_code_handling
Browse files Browse the repository at this point in the history
  • Loading branch information
“Dafydd committed Nov 1, 2024
2 parents 940d888 + 1dc4744 commit f5a13bd
Show file tree
Hide file tree
Showing 8 changed files with 1,575 additions and 1,294 deletions.
4 changes: 2 additions & 2 deletions cstar/case.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ class Case:
-------
from_blueprint(blueprint,caseroot,start_date,end_date)
Instantiate a Case from a "blueprint" yaml file
persist(filename)
to_blueprint(filename)
Create a "blueprint" yaml file for this Case object
setup()
Fetch all code and files necessary to run this case in the local caseroot folder
Expand Down Expand Up @@ -449,7 +449,7 @@ def from_blueprint(

return caseinstance

def persist(self, filename: str) -> None:
def to_blueprint(self, filename: str) -> None:
"""Write this case to a yaml 'blueprint' file.
This effectively performs the actions of Case.from_blueprint(), but in reverse,
Expand Down
2 changes: 1 addition & 1 deletion cstar/tests/integration_tests/test_cstar_test_blueprints.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ def test_cstar(
with mock_user_input("y"):
cstar_test_case.setup()

cstar_test_case.persist(tmpdir / "test_blueprint_persistence.yaml")
cstar_test_case.to_blueprint(tmpdir / "test_blueprint_persistence.yaml")
cstar_test_case.build()
cstar_test_case.pre_run()
cstar_test_case.run()
Expand Down
4 changes: 2 additions & 2 deletions docs/1_building_and_exporting_a_case.ipynb → ...ase_and_exporting_it_as_a_blueprint.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"id": "b29d6e47-5fbc-44ea-b5a8-35bbd8a2a596",
"metadata": {},
"source": [
"# Building & exporting a `Case`\n",
"# Building a `Case` and exporting it as a blueprint\n",
"In this notebook, we will create a ROMS-MARBL [C-Star case](https://c-star.readthedocs.io/en/latest/terminology.html#term-Case), by:\n",
"\n",
"* Creating ROMS and MARBL [BaseModel](https://c-star.readthedocs.io/en/latest/terminology.html#term-BaseModel) objects\n",
Expand Down Expand Up @@ -740,7 +740,7 @@
},
"outputs": [],
"source": [
"roms_marbl_case.persist(\"roms_marbl_example_case.yaml\")"
"roms_marbl_case.to_blueprint(\"roms_marbl_example_case.yaml\")"
]
},
{
Expand Down
233 changes: 230 additions & 3 deletions docs/2_importing_and_running_a_case.ipynb → ...and_running_a_case_from_a_blueprint.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"# Importing & running a `Case`\n",
"In this notebook, we will spin up a ROMS-MARBL run using C-Star. In particular, we will:\n",
"\n",
"- Create a [C-Star Case](https://c-star.readthedocs.io/en/latest/terminology.html#term-Case) from a pre-prepared [blueprint](https://c-star.readthedocs.io/en/latest/terminology.html#term-blueprint) (`Case.from_blueprint()`). See [this notebook](https://c-star.readthedocs.io/en/latest/1_building_and_exporting_a_case.html) for instructions on how to assemble a blueprint.\n",
"- Create a [C-Star Case](https://c-star.readthedocs.io/en/latest/terminology.html#term-Case) from a pre-prepared [blueprint](https://c-star.readthedocs.io/en/latest/terminology.html#term-blueprint) (`Case.from_blueprint()`). See [this notebook](https://c-star.readthedocs.io/en/latest/1_building_a_case_and_exporting_it_as_a_blueprint.html) for instructions on how to assemble a blueprint.\n",
"- Examine the contents of the Case object we just created\n",
"- Set up the case locally (`Case.setup()`)\n",
"- Compile any necessary code associated with the case (`Case.build()`)\n",
Expand Down Expand Up @@ -474,11 +474,226 @@
},
{
"cell_type": "code",
"execution_count": 12,
"execution_count": 11,
"id": "a9280f90-fec9-429b-b28d-da7976fea3da",
"metadata": {
"tags": []
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"Setting up MARBLComponent\n",
"--------------------------\n",
"Configuring MARBLComponent\n",
"--------------------------\n",
"#######################################################\n",
"C-STAR: MARBL_ROOT not found in current environment. \n",
"if this is your first time running C-Star with an instance of MARBLBaseModel, you will need to set it up.\n",
"It is recommended that you install this base model in \n",
"/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/externals/MARBL\n",
"This will also modify your `cstar_local_config.py` file.\n",
"#######################################################\n"
]
},
{
"name": "stdin",
"output_type": "stream",
"text": [
"Would you like to do this now? ('y', 'n', or 'custom' to install at a custom path)\n",
" y\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Cloned repository https://github.com/marbl-ecosys/MARBL.git to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/externals/MARBL\n",
"Checked out marbl0.45.0 in git repository /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/externals/MARBL\n",
"Updating environment in C-Star configuration file /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/cstar_local_config.py\n",
"Compiling MARBL...\n",
"MARBL successfully installed at /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/externals/MARBL\n",
"\n",
"Setting up ROMSComponent\n",
"-------------------------\n",
"Configuring ROMSComponent\n",
"-------------------------\n",
"#######################################################\n",
"C-STAR: ROMS_ROOT not found in current environment. \n",
"if this is your first time running C-Star with an instance of ROMSBaseModel, you will need to set it up.\n",
"It is recommended that you install this base model in \n",
"/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/externals/ucla-roms\n",
"This will also modify your `cstar_local_config.py` file.\n",
"#######################################################\n"
]
},
{
"name": "stdin",
"output_type": "stream",
"text": [
"Would you like to do this now? ('y', 'n', or 'custom' to install at a custom path)\n",
" y\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Cloned repository https://github.com/CESR-lab/ucla-roms.git to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/externals/ucla-roms\n",
"Checked out 594ac425e9dbe663ce48ced0915c0007c6cca843 in git repository /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/externals/ucla-roms\n",
"Compiling UCLA ROMS' NHMG library...\n",
"Compiling Tools-Roms package for UCLA ROMS...\n",
"UCLA-ROMS is installed at /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/cstar/externals/ucla-roms\n",
"\n",
"Fetching additional source code...\n",
"----------------------------------\n",
"Cloned repository https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example.git to /tmp/tmpfmnia20c\n",
"Checked out cstar_alpha in git repository /tmp/tmpfmnia20c\n",
"copying bgc.opt to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"copying bulk_frc.opt to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"copying cppdefs.opt to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"copying diagnostics.opt to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"copying ocean_vars.opt to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"copying param.opt to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"copying tracers.opt to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"copying Makefile to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"copying Make.depend to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/additional_source_code/ROMS\n",
"\n",
"Fetching namelists... \n",
"----------------------\n",
"Cloned repository https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example.git to /tmp/tmpl5oi6bb1\n",
"Checked out cstar_alpha in git repository /tmp/tmpl5oi6bb1\n",
"copying roms.in_TEMPLATE to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/namelists/ROMS\n",
"copying template file /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/namelists/ROMS/roms.in_TEMPLATE to editable version /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/namelists/ROMS/roms.in\n",
"copying marbl_in to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/namelists/ROMS\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"Downloading file 'roms_grd.yaml' from 'https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example/raw/cstar_alpha/roms_tools_yaml_files/roms_grd.yaml' to '/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS'.\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"copying marbl_tracer_output_list to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/namelists/ROMS\n",
"copying marbl_diagnostic_output_list to /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/namelists/ROMS\n",
"\n",
"Fetching input datasets...\n",
"--------------------------\n",
"Saving roms-tools dataset created from /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS/roms_grd.yaml...\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"Downloading file 'roms_ini.yaml' from 'https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example/raw/cstar_alpha/roms_tools_yaml_files/roms_ini.yaml' to '/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS'.\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Selected time entry closest to the specified start_time (2012-01-01 12:00:00) within the range [2012-01-01 12:00:00, 2012-01-02 12:00:00]: ['2012-01-01T12:00:00.000000000']\n",
"Saving roms-tools dataset created from /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS/roms_ini.yaml...\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"Downloading file 'roms_tides.yaml' from 'https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example/raw/cstar_alpha/roms_tools_yaml_files/roms_tides.yaml' to '/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS'.\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Saving roms-tools dataset created from /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS/roms_tides.yaml...\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"Downloading file 'roms_bry.yaml' from 'https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example/raw/cstar_alpha/roms_tools_yaml_files/roms_bry.yaml' to '/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS'.\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Saving roms-tools dataset created from /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS/roms_bry.yaml...\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"Downloading file 'roms_bry_bgc.yaml' from 'https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example/raw/cstar_alpha/roms_tools_yaml_files/roms_bry_bgc.yaml' to '/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS'.\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Saving roms-tools dataset created from /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS/roms_bry_bgc.yaml...\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"Downloading file 'roms_frc.yaml' from 'https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example/raw/cstar_alpha/roms_tools_yaml_files/roms_frc.yaml' to '/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS'.\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Saving roms-tools dataset created from /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS/roms_frc.yaml...\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"Downloading file 'roms_frc_bgc.yaml' from 'https://github.com/CWorthy-ocean/cstar_blueprint_roms_marbl_example/raw/cstar_alpha/roms_tools_yaml_files/roms_frc_bgc.yaml' to '/global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS'.\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Saving roms-tools dataset created from /global/cfs/cdirs/m4746/Users/dafydd/my_c_star/examples/alpha_example/example_case/input_datasets/ROMS/roms_frc_bgc.yaml...\n"
]
}
],
"source": [
"example_case_1.setup()"
]
},
{
"cell_type": "markdown",
"id": "22c39c32-edd3-41a8-abfb-c9130790a0f9",
"metadata": {},
"source": [
"If we attempt to run `Case.setup()` again, C-Star identifies that nothing has changed from our previous `setup()` call and we can skip this step:"
]
},
{
"cell_type": "code",
"execution_count": 12,
"id": "e6f3d81d-ce69-404d-86b0-f1ac08a7c9e3",
"metadata": {
"tags": []
},
"outputs": [
{
"name": "stdout",
Expand All @@ -492,6 +707,19 @@
"example_case_1.setup()"
]
},
{
"cell_type": "markdown",
"id": "c61944ce-1fe9-4f5e-92e5-1c95a22a1285",
"metadata": {},
"source": [
"<div class=\"alert alert-info\">\n",
"\n",
"Note\n",
"\n",
"C-Star currently does not maintain the state of Cases between sessions. This means that, if you run `Case.setup()`, exit your python session, start a new one, and create the Case again from the same blueprint, you will have to run `Case.setup()` again to re-establish the working state of the `Case`, even though this `Case` has already been set up. Most setup steps will be skipped the second time, as C-Star will see they are already complete.\n",
"</div>"
]
},
{
"cell_type": "markdown",
"id": "ee973fda-d889-48f1-9400-6ebc27f3337e",
Expand Down Expand Up @@ -767,7 +995,6 @@
"\n",
"- created a C-Star `Case` from a \"blueprint\" file\n",
"- Ran the case for 2 days from 2012-01-01 to 2012-01-03 with a 60 second time-step\n",
"- Restarted the case from 2012-01-03 and ran for a further 3 days with a 6 minute time-step\n",
"- Produced a basic plot to verify the output"
]
}
Expand Down
16 changes: 15 additions & 1 deletion docs/3_restarting_and_continuing_a_case.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"# Restarting & continuing a `Case`\n",
"In this notebook we will:\n",
"\n",
"- Take the Case we ran for two days (2012-01-01 to 2012-01-03) in the [previous notebook](https://c-star.readthedocs.io/en/latest/2_importing_and_running_a_case.html) and create a new Case that picks up where it ends (`Case.restart()`)\n",
"- Take the Case we ran for two days (2012-01-01 to 2012-01-03) in the [previous notebook](https://c-star.readthedocs.io/en/latest/2_importing_and_running_a_case_from_a_blueprint.html) and create a new Case that picks up where it ends (`Case.restart()`)\n",
"- Run this second case with a larger time step for the remainder of the month of January 2012\n",
"- Produce a basic plot of the output\n"
]
Expand All @@ -23,6 +23,20 @@
"To do this, we can use the `Case.restart()` method, which returns a new `Case` whose start date corresponds to the end date of the Case we began with, and whose initial conditions are replaced with a restart file from our previous run."
]
},
{
"cell_type": "markdown",
"id": "5bcbe1d3-030f-4a10-8753-5d714f776ab2",
"metadata": {},
"source": [
"<div class=\"alert alert-info\">\n",
"\n",
"Note\n",
"\n",
"If you are following this interactively, the following cells should be appended to the [previous notebook](https://c-star.readthedocs.io/en/latest/2_importing_and_running_a_case_from_a_blueprint.html) where `example_case_1` is still in the workspace.\n",
"</div>\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 19,
Expand Down
Loading

0 comments on commit f5a13bd

Please sign in to comment.