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"))

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)

notebooks.list()

List downloadable notebooks based on the JuliaClimate/Notebooks webpage.

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

reroll(p,f; PlutoFile="notebook.jl")

The reroll function can be used to reassemble as a Pluto notebook that was previously unroll'ed.

See unroll documentation for a use case example.

unroll(PlutoFile::String; EnvPath="", ModuleFile="")

Split up Pluto notebook file (PlutoFile) into main program (main.jl), Project.toml, Manifest.toml, and CellOrder.txt.

• these files are saved to folder p (EnvPath or a temporary folder by default)
• unroll returns output path p and main program file name
• unroll optionally copies companion file mf to p (if file mf exists)
• default mf is PlutoFile[1:end-3]*"_module.jl" unless ModuleFile is specified
• the reroll function can be used to reassemble as a Pluto notebook

Use case example: updating notebook dependencies

using Pkg
p,f=notebooks.unroll("CMIP6.jl")
Pkg.activate(p)
Pkg.update()
n=notebooks.reroll(p,f)

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"))

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)

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()

ModelConfig(func::Function,inputs::NamedTuple)

Simplified constructor for case when model is a Function.

struct PlutoConfig <: AbstractModelConfig

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

PlutoConfig(func::Function,inputs::NamedTuple)

Simplified constructor for case when model is a Pluto notebook.

If a folder path is passed in inputs.data then it will get linked to the run folder.

cd(x::AbstractModelConfig)

Temporarily change the current working directory to x.folder.

joinpath(x::AbstractModelConfig,y...)

Same as joinpath(pathof(x),y...)

readdir(x::AbstractModelConfig,subfolder::String)

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

readdir(x::AbstractModelConfig)

Same as readdir(pathof(x)).

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)

log(x :: AbstractModelConfig)

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

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

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

pathof(x::AbstractModelConfig)

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

put!(x :: AbstractModelConfig,v)

Adds v to x.channel (i.e. put!(x.channel,v))

using ClimateModels, Suppressor
tmp=ModelConfig()
setup(tmp)
put!(tmp,ClimateModels.RandomWalker)
ClimateModels.pause(tmp)
@suppress ClimateModels.monitor(tmp)
@suppress ClimateModels.help(tmp)
launch(tmp)

isa(tmp,AbstractModelConfig)

show(io::IO, z::AbstractModelConfig)

tmp=ModelConfig(model=ClimateModels.RandomWalker)
setup(tmp)
show(tmp)

take!(x :: AbstractModelConfig)

Takes command v from x.channel (i.e. take!(x.channel)) and execute v(x) (if a Function) or return v (if not a Function, e.g. a String).

tmp=ModelConfig()
put!(tmp,ClimateModels.RandomWalker)
take!(tmp)

ModelRun(x :: AbstractModelConfig)

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

Returns AbstractModelConfig as output.

PkgDevConfig(url::String,func::Function,inputs::NamedTuple)

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

RandomWalker(x::AbstractModelConfig)

Random Walk in 2D over NS steps (100 by default). Result is provided as an array and a text file.

By default, RandomWalker.csv will be created in pathof(x). That folder itself is created by setup, possibly via run as below.

MC=ModelConfig(ClimateModels.RandomWalker)
run(MC)

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

buildthepkg(x)

Default for building/compiling model when it is a cloned julia package

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)

compile(x)

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

using ClimateModels, Pkg
tmp0=PackageSpec(url="https://github.com/JuliaOcean/AirSeaFluxes.jl")
tmp=ModelConfig(model=tmp0)
setup(tmp)
compile(tmp)

isa(tmp,AbstractModelConfig)

git_log_fil(x :: AbstractModelConfig,fil,commit_msg)

Commit changes to file log/fil with message commit_msg. If log/fil is unknown to git (i.e. commit errors out) then try adding log/fil first.

git_log_init(x :: AbstractModelConfig)

Create log subfolder, initialize git, and commit initial README.md

git_log_msg(x :: AbstractModelConfig,msg,commit_msg)

Add message msg to the log/README.md file and git commit.

git_log_prm(x :: AbstractModelConfig)

Add files found in tracked_parameters/ (if any) to git log.

git_log_show(x :: AbstractModelConfig,y:: String)

Show the record of git commit y from the log folder.

git_log_show(x :: AbstractModelConfig)

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

using ClimateModels
f=ClimateModels.RandomWalker
i=ClimateModels.OrderedDict(); i["NS"]=100
tmp=ModelConfig(model=f,inputs=i)
setup(tmp)
build(tmp)
launch(tmp)
ClimateModels.@suppress log(tmp)
isa(tmp,AbstractModelConfig)

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)

monitor(x)

Show x.status[end] by default.

tmp=ModelConfig(model=ClimateModels.RandomWalker)
setup(tmp)
monitor(tmp)

run_the_tests(x)

Default for launching model when it is a cloned julia package

using ClimateModels, Pkg
tmp0=PackageSpec(url="https://github.com/JuliaOcean/AirSeaFluxes.jl")
tmp1=ModelConfig(model=tmp0)
setup(tmp1)
build(tmp1)
launch(tmp1)

clean(tmp1)=="no task left in pipeline"

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)

@ModelRun(func)

Macro equivalent for run(ModelConfig(model=func)).