Parameters interface

Our interface builds upon the Configurations.jl package which allows to set defaults and also provide convinient serialization with arbitrary file formats.

Usage

Define parameters struct with Configuartions.jl's @option macro, e.g.

@option "MDA" struct MDA_Model <: AbstractParameters
  "Upper limit on viscosity strength"
  cmax::Float64 = 1.0
  "Lower limit on viscosity strength"
  cmin::Float64 = 1.0
end

The above defines a struct MDA_Model that holds relevant parameters as well as a brief documentation for each one. The string "MDA" before the struct keyword is optional and should be added in case one reuses this struct in another parameter struct as an optional parameter. Additionally, we subtyped MDA_Model to AbstractParameters, because it provides a santization interface. E.g. if we implement the following,

function sanitize(model::MDA_Model)
  # sanitize parameters
end

then we establish a reusable parameter check that can be used as follows:

model = MDA_Model()
sanitize(model)

Ultimately, parameter structs should be reused. E.g. imagine writing a TOV solver where one uses methods from different modules. The TOV parameter struct could look something like this:

@option "TOV" struct TOVParameters <: AbstractParameters
  "Maximum domain extension"
  Rmax::Float64 = 12
  "Mirror simulation domain across origin"
  mirror::Bool = true

  "Time evolution"
  evolution::EvolutionParameters = EvolutionParameters(scheme="LSERK4")
  "Computational grid"
  grid::GridParameters = GridParameters(K=100)
  "High resolution shock capturing technique"
  hrsc::Union{MDA_Model, MDH_Model} = MDA_Model
end

function sanitize(prms::TOVParameters)
  @assert prms.Rmax > 0 "Positive domain length required!"
  sanitize(prms.evolution)
  sanitize(prms.grid)
  sanitize(prms.hrsc)
end

Fields of parameter structs must be of type Int, String, Number or a parameter struct defined using the @option macro (like above).

It is best practice to provide default values for all parameters. Doing so allows one to get an idea of sensible defaults by simply instantiating TOV().

Reading and writing

We recommnd using TOML files as the output format in order to remain consistent among the projects, although other formats could (in principle) also be used with Configurations.jl.

Reading and writing is done with from_toml and to_toml, e.g.

prms = TOVParameters()
# write
to_toml("/path/to/file.toml")
# read
prms = from_toml(TOVParameters, "/path/to/file.toml")

Note that upon reading you have to specify the parameter struct you want to parse the file into, in this case it was TOVParameters.