API Reference

Data Structures

  • ModelConfig is the main concrete type of AbstractModelConfig; used in the examples.
  • PlutoConfig let's us ingest any Pluto.jl notebook easily via ClimateModels' Notebooks Methods.
ClimateModels.ModelConfigType
struct ModelConfig <: AbstractModelConfig

Generic data structure for a model configuration. This serves as :

  • default concrete type for AbstractModelConfig
  • keyword constructor for AbstractModelConfig
model :: Union{Function,String,Pkg.Types.PackageSpec} = "anonymous"
configuration :: Union{Function,String} = "anonymous"
inputs :: OrderedDict{Any,Any} = OrderedDict{Any,Any}()
outputs :: OrderedDict{Any,Any} = OrderedDict{Any,Any}()
channel :: Channel{Any} = Channel{Any}(10) 
folder :: String = tempdir()
ID :: UUID = UUIDs.uuid4()
source
ClimateModels.PlutoConfigType
struct PlutoConfig <: AbstractModelConfig

Generic data structure for a model configuration based on a Pluto notebook.

source

General Methods

ClimateModels.setupMethod
setup(x::AbstractModelConfig)

Defaults to default_ClimateModelSetup(x). Can be expected to be specialized for most concrete types of AbstractModelConfig

f=ClimateModels.RandomWalker
tmp=ModelConfig(model=f)
setup(tmp)
source
ClimateModels.buildFunction
build(x)

Defaults to default_ClimateModelBuild(x). Can be expected to be specialized for most concrete types of AbstractModelConfig

using ClimateModels
tmp=ModelConfig(model=ClimateModels.RandomWalker)
setup(tmp)
build(tmp)

isa(tmp,AbstractModelConfig) # hide
source
ClimateModels.launchFunction
launch(x)

Defaults to default_ClimateModelLaunch(x) which consists in take!(x) for AbstractModelConfig. Can be expected to be specialized for most concrete types of AbstractModelConfig

f=ClimateModels.RandomWalker
tmp=ModelConfig(model=f)
setup(tmp)
build(tmp)
launch(tmp)
source
Base.logFunction
log(x :: AbstractModelConfig)

Show the record of git commits that have taken place in the log folder.

source
log( x :: AbstractModelConfig, y :: String; fil="", msg="", prm=false)

Show or add a git commit to the log folder (i.e., joinpath(x,"log")).

  1. If no keyword is provided then y should be a commit ID from log(x)

  2. Keyword arguments are mutually exclusive (i.e., use only one at a time) and work like this:

  • msg is a non empty String : commit msg to log/README.md with message y.
  • fil is a non empty String : commit changes to file log/$(fil) with message y. If log/$(fil) is unknown to git (i.e. commit errors out) then try adding log/$(fil) first.
  • prm is true : add files found in input or tracked_parameters/ (if any) to git log.

Example:

MC=run(ModelConfig(ClimateModels.RandomWalker,(NS=100,)))
MC.inputs[:NS]=200
msg="update tracked_parameters.toml (or skip if up to date)"
log(MC,msg,prm=true)
log(MC)
source

Also provided : pathof, joinpath, cd, readdir, show, clean, and @ModelRun

Notebook Methods

ClimateModels.setupMethod
setup(MC::PlutoConfig)
  • call default_ClimateModelSetup
  • call unroll
  • add notebook_launch to tasks
MC1=PlutoConfig(model="examples/defaults.jl")
setup(MC1)
build(MC1)
launch(MC1)
source
ClimateModels.notebooks.updateMethod
update(MC::PlutoConfig)

Update notebook dependencies (via unroll & reroll) and replace initial notebook file.

update(PlutoConfig(model="examples/defaults.jl"))
run(PlutoConfig(model="examples/defaults.jl"))
source
Base.openMethod
open(MC::PlutoConfig))

Open notebook in web-browser via Pluto.

Important note: this assumes that the Pluto server is already running, e.g. from Pluto.run(), at URL pluto_url (by default, "http://localhost:1234/", should work on a laptop or desktop).

notebooks.open(PlutoConfig(model="examples/defaults.jl"))
source
Note

setup and update use unroll and reroll internally to process notebooks.

More

Simplified API

ClimateModels.ModelRunFunction
ModelRun(x :: AbstractModelConfig)

Shorthand for x |> setup |> build |> launch

Returns AbstractModelConfig as output.

source

Utility Functions

Base.pathofFunction
pathof(x::AbstractModelConfig)

Returns the run directory path for x ; i.e. joinpath(x.folder,string(x.ID))

source
pathof(x::AbstractModelConfig,subfolder::String)

Same as pathof(joinpath(x,subfolder)) or joinpath(pathof(x),subfolder)

source
Base.Filesystem.cdFunction
cd(x::AbstractModelConfig)

Temporarily change the current working directory to x.folder.

source
Base.Filesystem.readdirFunction
readdir(x::AbstractModelConfig)

Same as readdir(pathof(x)).

source
readdir(x::AbstractModelConfig,subfolder...)

Same as readdir(joinpath(pathof(x),subfolder...)).

source
Base.showFunction
show(io::IO, z::AbstractModelConfig)
tmp=ModelConfig(model=ClimateModels.RandomWalker)
setup(tmp)
show(tmp)
source
ClimateModels.cleanFunction
clean(x :: AbstractModelConfig)

Cancel any remaining task (x.channel) and rm the run directory (pathof(x))

tmp=ModelConfig(model=ClimateModels.RandomWalker)
setup(tmp)
clean(tmp)
source

JuliaClimate/Notebooks

Convenience functions for notebooks documented in the JuliaClimate/Notebooks webpage.

ClimateModels.notebooks.listFunction
notebooks.list()

List downloadable notebooks based on the JuliaClimate/Notebooks webpage.

Returns a DataFrame with columns folder, file, and url.

source
ClimateModels.notebooks.downloadFunction
notebooks.download(path,nbs)

Download notebooks/files listed in nbs to path.

  • If nbs.file[i] is found at nbs.url[i] then download it to path/nbs.folder[i].
  • If a second file is found at nbs.url[i][1:end-3]*"_module.jl" then we download it too.
nbs=notebooks.list()
notebooks.download(tempdir(),nbs)
source

PkgDevConfig

In the package development mode, model is specified as a PackageSpec.

ClimateModels.PkgDevConfigFunction
PkgDevConfig(url::String,func::Function,inputs::NamedTuple)

Simplified constructor for case when model is a url (PackageSpec).

source

This leads setup to install the chosen package using Pkg.develop. This can be useful for developing a package or using an unregistered package in the context of ClimateModels.jl.

There are two common cases:

Note

As an exercise, can you turn ShallowWaters.jl example into a normal user mode example?