Lab-0015: Difference between revisions

Latest revision as of 15:36, 19 April 2022

CSDMS Workbench: Basic Model Interface (BMI)

Model
Heat

Duration
1.0 hrs

Updated
2022-04-14

Download
download

Run online using:

Jupyter
Lab

Contributor(s)

Eric Hutton at INSTAAR - University of Colorado Boulder.

Mark Piper at INSTAAR - University of Colorado Boulder.

Greg Tucker at Geological Sciences - University of Colorado Boulder.

Irina Overeem at INSTAAR - University of Colorado Boulder.

Introduction

The Basic Model Interface (BMI) is a set of standard control and query functions that, when added to a model code, make that model both easier to learn and easier to couple with other software elements. Detailed information about BMI can be found at https://bmi.readthedocs.io.

BMI is an element of the CSDMS Workbench, an integrated system of software tools, technologies, and standards for building and coupling models. Learn more at https://csdms.colorado.edu/wiki/Workbench.

Classroom organization
In this lab we explore what BMI is and how to use it through a pair of Jupyter Notebooks. The first notebook presents a simple "Heat" model which simulates the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. The second notebook demonstrates how to run the "Heat" model through its BMI.

Learning objectives
Skills

View model source code and model BMI source code
Learn to set up and run the Heat model
Learn to set up and run the Heat model through its BMI

Key concepts

Diffusion of temperature
Software interface

Lab notes

This lab can be run on the lab (for educators) and jupyter (for general use) instances of the OpenEarthscape JupyterHub: just click one of the links under the Run online using heading at the top of this page, then run the notebook in the "CSDMS" kernel.

If you don't already have a JupyterHub account, follow the instructions to sign up at https://csdms.colorado.edu/wiki/JupyterHub. If you're an educator, you can get JupyterHub accounts for students--please contact us through the CSDMS Help Desk: https://csdms.github.io/help-desk.

Requirements
If run locally, this lab requires that the BMI Python example (https://github.com/csdms/bmi-example-python) be installed.

Acknowledgements
This material is based upon work supported by the National Science Foundation under Grant No. 1831623, Community Facility Support: The Community Surface Dynamics Modeling System (CSDMS).

References

Hutton, E.W.H., Piper, M.D., and Tucker, G.E., 2020. The Basic Model Interface 2.0: A standard interface for coupling numerical models in the geosciences. Journal of Open Source Software, 5(51), 2317, https://doi.org/10.21105/joss.02317
Peckham, S.D., Hutton, E.W., and Norris, B., 2013. A component-based approach to integrated modeling in the geosciences: The design of CSDMS. Computers & Geosciences, 53, pp.3-12, http://dx.doi.org/10.1016/j.cageo.2012.04.002.
Tucker, G. E., Hutton, E. W. H., Piper, M. D., Campforts, B., Gan, T., Barnhart, K. R., Kettner, A. J., Overeem, I., Peckham, S. D., McCready, L., and Syvitski, J., 2022: CSDMS: a community platform for numerical modeling of Earth surface processes, Geosci. Model Dev., 15, 1413–1439, https://doi.org/10.5194/gmd-15-1413-2022.

@@ Line 1: / Line 1: @@
 {{Labbasics
-|Labtitle=Introduction to CSDMS Tools - Basic Model Interface (BMI)
+|Labtitle=CSDMS Workbench: Basic Model Interface (BMI)
 |LabCOModule=1 of 1
-|LabDateContributedOrUpdated=2020/06/04
+|LabDateContributedOrUpdated=2022-04-14
-|LabDescriptionShort=Basic Model Interface (BMI) is a set of standard control and query functions that, when added to a model code, make that model both easier to learn and easier to couple with other software elements. This lab illustrates how to run a model through its BMI .
+|LabDescriptionShort=The Basic Model Interface (BMI) is a set of standard control and query functions that, when added to a model code, make that model both easier to learn and easier to couple with other software elements. This lab illustrates how to run a model through its BMI.
 |LabCODuration=1.0 hrs
+|LabModelDocumentation=Heat
 |LabAssociatedLesson=Jupyter Notebook
-|LabURLDownloadNotebook=https://github.com/csdms/csdms-2020/tree/master/notebooks/bmi
+|LabURLDownloadNotebook=https://github.com/csdms/ivy/tree/main/lessons/bmi
-|LabURLStartNotebook=https://csdms.rc.colorado.edu/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2Fcsdms%2Fcsdms-2020&urlpath=tree%2Fcsdms-2020%2Fnotebooks%2Fbmi%2Findex.ipynb&branch=master
+|LabURLStartNotebook=https://jupyter.openearthscape.org/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2Fcsdms%2Fivy&urlpath=tree%2Fivy%2Flessons%2Fbmi%2Findex.ipynb&branch=main
+|LabURL2StartNotebook=https://lab.openearthscape.org/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2Fcsdms%2Fivy&urlpath=tree%2Fivy%2Flessons%2Fbmi%2Findex.ipynb&branch=main
 }}
 {{LabContributorData
@@ Line 26: / Line 28: @@
 }}
 {{LabIntro
-|LabDescription=Basic Model Interface (BMI) is a set of standard control and query functions that, when added to a model code, make that model both easier to learn and easier to couple with other software elements. Detailed information about BMI can be accessed at [https://bmi.readthedocs.io/en/latest/ BMI documentation]
+|LabDescription=<p>The Basic Model Interface (BMI) is a set of standard control and query functions that, when added to a model code, make that model both easier to learn and easier to couple with other software elements. Detailed information about BMI can be found at https://bmi.readthedocs.io.</p>
-|LabPicture=Bmi-logo.png
+<p>BMI is an element of the CSDMS Workbench, an integrated system of software tools, technologies, and standards for building and coupling models. Learn more at https://csdms.colorado.edu/wiki/Workbench.</p>
+|LabPicture=Bmi-logo-below-lowercase.png
 }}
 {{LabClassroomOrganization
-|LabCOIntro=In this lab, we will explore through a pair of Jupyter Notebooks to learn what BMI is and how to use it. This lab will first illustrate an example "Heat" model which simulates the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. Then, the lab will demonstrate how to run "Heat" model through its BMI.
+|LabCOIntro=In this lab we explore what BMI is and how to use it through a pair of Jupyter Notebooks. The first notebook presents a simple "Heat" model which simulates the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. The second notebook demonstrates how to run the "Heat" model through its BMI.
-You can create an account at CSDMS JupyterHub and test the Jupyter Notebook for this lab. Please follow the instruction in the "Lab Notes" section. If you are a faculty at an academic institution, it is possible to work with us to get temporary teaching accounts. Work directly with us by emailing: csdms@colorado.edu.
 }}
 {{LabLearningObjectivesSkills
@@ Line 38: / Line 40: @@
 }}
 {{LabLearningObjectivesSkills
-|LabSkill=Learn to set up and run the heat model
+|LabSkill=Learn to set up and run the Heat model
 }}
 {{LabLearningObjectivesSkills
-|LabSkill=Learn to set up and run the heat model through its BMI
+|LabSkill=Learn to set up and run the Heat model through its BMI
 }}
 {{Headerplaceholder}}
 {{LabTopicalLearningObjectives
 |LabTopicalLearningObjective=Diffusion of temperature
+}}
+{{LabTopicalLearningObjectives
+|LabTopicalLearningObjective=Software interface
 }}
 {{LabNotes
-|LabNotesInstructions=You can follow the steps below to test and run the Jupyter Notebooks on the CSDMS JupyterHub server for this lab.
+|LabNotesInstructions=<p>This lab can be run on the <em>lab</em> (for educators) and <em>jupyter</em> (for general use) instances of the OpenEarthscape JupyterHub: just click one of the links under the <strong>Run online using</strong> heading at the top of this page, then run the notebook in  the "CSDMS" kernel.</p>
-.  [https://csdms.rc.colorado.edu/hub/signup Create a free account] on the CSDMS JupyterHub , providing a username and password -- they can be whatever you like
+<p>If you don't already have a JupyterHub account, follow the instructions to sign up at https://csdms.colorado.edu/wiki/JupyterHub. If you're an educator, you can get JupyterHub accounts for students--please contact us through the CSDMS Help Desk: https://csdms.github.io/help-desk.</p>
+|LabNotesRequirements=If run locally, this lab requires that the BMI Python example (https://github.com/csdms/bmi-example-python) be installed.
-.  [https://github.com/csdms/help-desk/issues/new?assignees=mdpiper&labels=jupyterhub&template=new-csdms-jupyterhub-account.md&title=CSDMS+JupyterHub+account Request authorization] for your new account through the CSDMS Help Desk at   -- if you don't already have a GitHub account, you'll be asked to make one
+|LabAcknowledgements=This material is based upon work supported by the National Science Foundation under Grant No. 1831623, Community Facility Support: The Community Surface Dynamics Modeling System (CSDMS).
+}}
-.  Once approved, run Jupyter Notebooks by clicking on "start" under the "Run online" section (grey table at the top of this lab page).
+{{LabReferences
+|LabReferences=Hutton, E.W.H., Piper, M.D., and Tucker, G.E., 2020. The Basic Model Interface 2.0: A standard interface for coupling numerical models in the geosciences. Journal of Open Source Software, 5(51), 2317, https://doi.org/10.21105/joss.02317
+}}
+{{LabReferences
+|LabReferences=Peckham, S.D., Hutton, E.W., and Norris, B., 2013. A component-based approach to integrated modeling in the geosciences: The design of CSDMS. Computers & Geosciences, 53, pp.3-12, http://dx.doi.org/10.1016/j.cageo.2012.04.002.
+}}
+{{LabReferences
+|LabReferences=Tucker, G. E., Hutton, E. W. H., Piper, M. D., Campforts, B., Gan, T., Barnhart, K. R., Kettner, A. J., Overeem, I., Peckham, S. D., McCready, L., and Syvitski, J., 2022: CSDMS: a community platform for numerical modeling of Earth surface processes, Geosci. Model Dev., 15, 1413–1439, https://doi.org/10.5194/gmd-15-1413-2022.
 }}