API Reference
Data Structures
ModelConfig
is the main concrete type ofAbstractModelConfig
; used in the examples.PlutoConfig
let's us ingest any Pluto.jl notebook easily viaClimateModels
' Notebooks Methods.
ClimateModels.ModelConfig
— Typestruct 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()
ClimateModels.ModelConfig
— MethodModelConfig(func::Function,inputs::NamedTuple)
Simplified constructor for case when model is a Function.
ClimateModels.PlutoConfig
— Typestruct PlutoConfig <: AbstractModelConfig
Generic data structure for a model configuration based on a Pluto notebook.
General Methods
ClimateModels.setup
— Methodsetup(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)
ClimateModels.build
— Functionbuild(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
ClimateModels.launch
— Functionlaunch(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)
Base.log
— Functionlog(x :: AbstractModelConfig)
Show the record of git
commits that have taken place in the log
folder.
log( x :: AbstractModelConfig, y :: String; fil="", msg="", prm=false)
Show or add a git
commit to the log
folder (i.e., joinpath(x,"log")
).
If no keyword is provided then
y
should be a commit ID fromlog(x)
Keyword arguments are mutually exclusive (i.e., use only one at a time) and work like this:
msg
is a non emptyString
: commitmsg
tolog/README.md
with messagey
.fil
is a non emptyString
: commit changes to filelog/$(fil)
with messagey
. Iflog/$(fil)
is unknown to git (i.e. commit errors out) then try addinglog/$(fil)
first.prm
istrue
: add files found ininput
ortracked_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)
Also provided : pathof
, joinpath
, cd
, readdir
, show
, clean
, and @ModelRun
Notebook Methods
ClimateModels.setup
— Methodsetup(MC::PlutoConfig)
- call
default_ClimateModelSetup
- call
unroll
- add
notebook_launch
to tasks
MC1=PlutoConfig(model="examples/defaults.jl")
setup(MC1)
build(MC1)
launch(MC1)
ClimateModels.notebooks.update
— Methodupdate(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"))
Base.open
— Methodopen(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"))
setup
and update
use unroll
and reroll
internally to process notebooks.
More
Simplified API
ClimateModels.ModelRun
— FunctionModelRun(x :: AbstractModelConfig)
Shorthand for x |> setup |> build |> launch
Returns AbstractModelConfig
as output.
ClimateModels.@ModelRun
— Macro@ModelRun(func)
Macro equivalent for run(ModelConfig(model=func))
.
Utility Functions
Base.pathof
— Functionpathof(x::AbstractModelConfig)
Returns the run directory path for x ; i.e. joinpath(x.folder,string(x.ID))
pathof(x::AbstractModelConfig,subfolder::String)
Same as pathof(joinpath(x,subfolder))
or joinpath(pathof(x),subfolder)
Base.Filesystem.joinpath
— Functionjoinpath(x::AbstractModelConfig,y...)
Same as joinpath(pathof(x),y...)
Base.Filesystem.cd
— Functioncd(x::AbstractModelConfig)
Temporarily change the current working directory to x.folder
.
Base.Filesystem.readdir
— Functionreaddir(x::AbstractModelConfig)
Same as readdir(pathof(x)).
readdir(x::AbstractModelConfig,subfolder...)
Same as readdir(joinpath(pathof(x),subfolder...)).
Base.show
— Functionshow(io::IO, z::AbstractModelConfig)
tmp=ModelConfig(model=ClimateModels.RandomWalker)
setup(tmp)
show(tmp)
ClimateModels.clean
— Functionclean(x :: AbstractModelConfig)
Cancel any remaining task (x.channel) and rm the run directory (pathof(x))
tmp=ModelConfig(model=ClimateModels.RandomWalker)
setup(tmp)
clean(tmp)
JuliaClimate/Notebooks
Convenience functions for notebooks documented in the JuliaClimate/Notebooks
webpage.
ClimateModels.notebooks.list
— Functionnotebooks.list()
List downloadable notebooks based on the JuliaClimate/Notebooks
webpage.
Returns a DataFrame
with columns folder, file, and url.
ClimateModels.notebooks.download
— Functionnotebooks.download(path,nbs)
Download notebooks/files listed in nbs
to path
.
- If
nbs.file[i]
is found atnbs.url[i]
then download it topath
/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)
PkgDevConfig
In the package development mode, model
is specified as a PackageSpec
.
ClimateModels.PkgDevConfig
— FunctionPkgDevConfig(url::String,func::Function,inputs::NamedTuple)
Simplified constructor for case when model is a url (PackageSpec).
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:
- if
configuration
is left undefined thenlaunch
will run the package test suite usingPkg.test
as in this example (code link) - if
configuration
is provided as aFunction
thenlaunch
will call it as illustrated in the ShallowWaters.jl example (code link)
As an exercise, can you turn ShallowWaters.jl example into a normal user mode example?