All Docs

MITgcm_path

Path to a MITgcm folder. MITgcm_path[1] should generally be used. MITgcm_path[2] is mostly meant to facilitate comparisons between e.g. MITgcm releases when needed.

base_configuration

Name of the folder that lives in the /verificaion folder of the MITgcm. This holds the basic configuration for Dar_One, which is a homogenous 1m x 1m x 1m water parcel with air/sea exchange, no mixing, few nuturients, and no biological forcing.

filexe

Path to the file that contains the built MITgcm, normally named "mitgcmuv". The executable should be compiled on whatever machine you're using to run the model, unless using the docker container [TODO: link]

MITgcm_config()

Concrete type of AbstractModelConfig for MITgcm (as part of the ClimateModels.jl interface for MITgcm) which contains

    model :: String = "MITgcm"
    configuration :: String = ""
    options :: OrderedDict{Any,Any} = OrderedDict{Any,Any}()
    inputs :: OrderedDict{Any,Any} = OrderedDict{Any,Any}()
    outputs :: OrderedDict{Any,Any} = OrderedDict{Any,Any}()
    status :: OrderedDict{Any,Any} = OrderedDict{Any,Any}()
    channel :: Channel{Any} = Channel{Any}(10) 
    folder :: String = tempdir()
    ID :: UUID = UUIDs.uuid4()

and can be constructed using keywords as follows

unknown_config=MITgcm_config(configuration="unknown")

MITgcm_namelist(groups,params)

Data structure representing a MITgcm namelist file, such as data.pkg, which contains

    groups :: Array{Symbol,1} = Array{Symbol,1}(undef, 0)
    params :: Array{OrderedDict{Symbol,Any},1} = Array{OrderedDict{Symbol,Any},1}(undef, 0)

with model parameters (params) being organized in groups as done in the files.

using MITgcmTools
fil=joinpath(MITgcm_path[1],"verification","advect_xy","run","data")
nml=read_namelist(fil)
MITgcm_namelist(nml.groups,nml.params)
MITgcm_namelist(groups=nml.groups,params=nml.params)
MITgcm_namelist(groups=nml.groups)

common time steps in seconds

build(config::MITgcm_config,options::String)

Build the model using genmake2, make depend, and make unless otherwise specified via options. The genmake2 and make depend commands link all code files, headers, etc in the build/ folder before make compiles the model.

(part of the climate model interface as specialized for MITgcm)

build(config::MITgcm_config)

Build the model using genmake2, make depend, and make. The first two link all code files, headers, etc in the build/ folder before compiling the model

(part of the climate model interface as specialized for MITgcm)

clean(config::MITgcm_config)

Cancel any remaining task (config.channel) and clean up the run directory (via rm).

(part of the climate model interface as specialized for MITgcm)

compile(config::MITgcm_config)

Compile the model using make in build/ that has already been setup.

(part of the climate model interface as specialized for MITgcm)

setup(config::MITgcm_config)

Create a run/ folder and link everything there as needed to be ready to run model as normally done for most-standard MITgcm configurations (incl. prepare_run and mitgcmuv). Call ClimateModels.git_log_init(config) to setup git tracker and put!(config.channel,MITgcm_launch) to be executed via launch(config) later.

(part of the climate model interface as specialized for MITgcm)

MITgcm_launch(config::MITgcm_config)

Go to run/ folder and effectively call mitgcmuv > output.txt

(part of the climate model interface as specialized for MITgcm)

create_MITgcm_config(config_id)

Arguments:

• configid: unique name for your darone run

Returns

• configobj::MITgcmconfig
• rundir::AbstractString - folder where output will be

ed_id_to_name(id)

Return the string "Ed"+id

es_id_to_name(id)

Return the string "Es"+id

holdnutrientsconstant(param_list)

Takes a vector of length 19, for each of the non-plankton tracers, with values of either 0 or 1. This function modifies darwin_plankton.F, and mulitplies the computed tendencies of the nutrient tracers by the value passed in. 0 = hold constant 1 = allow change

The appropriate vector to pass in to hold all nutrients constant would be zeros(19). To allow all nutrients to vary, the parameter would be ones(19). The indices in the param_list correspond to the following nutrients, in order: [DIC, NO3, NO2, NH4, PO4, SiO2, FeT, DOC, DON, DOP, DOFe, PIC, POC, PON, PIP, PISi, POFe, ALK, O2]

TODO note: made specifically for selecting range of latitudes and times at fixed x and z

TODO note: made specifically for selecting range of latitudes and longitudes at fixed t and z

init_temperature_grid(config_obj, tracer_name, init_list, dim, grid_size=(5,3))

Create a bin file of initial values for temperature. For a grid of size (X, Y), the initial conditions for each grid cell are set in a binary file with X*Y number of floats, in big-endian format, with no headers.

Arguments

• config_obj
• tracer_name: String
• init_list: list of values to initialize the temperature to
• dim: "x" or "y" - which dimension to set to the list; values won't change along the other axis
• grid_size: tuple ints, default 2x2

Returns

• the matrix of initial values

init_temperature_grid(config_obj, tracer_name, init_matrix)

Create a bin file of initial values for temperature. For a grid of size (X, Y), the initial conditions for each grid cell are set in a binary file with X*Y number of floats, in big-endian format, with no headers.

Arguments

• config_obj
• init_matrix: 2D list of values to write to the bin file

Returns

• the matrix of initial values

init_tracer_grid(config_obj, tracer_name, init_list, dim, grid_size=(5,3))

Create a bin file of initial values for a tracer. For a grid of size (X, Y), the initial conditions for each grid cell are set in a binary file with X*Y number of floats, in big-endian format, with no headers.

Arguments

• config_obj
• tracer_name: String
• init_list: list of values to initialize the tracer to
• dim: "x" or "y" - which dimension to set to the list; values won't change along the other axis
• grid_size: tuple ints, default 2x2

Returns

• the matrix of initial values

init_tracer_grid(config_obj, tracer_name, init_matrix)

Create a bin file of initial values for a tracer. For a grid of size (X, Y), the initial conditions for each grid cell are set in a binary file with X*Y number of floats, in big-endian format, with no headers.

Arguments

• config_obj
• tracer_name: String
• init_matrix: 2D list of values to write to the bin file

Returns

• the matrix of initial values

parse_param(p1)

Parse namelist parameter and return in corresponding type

read_available_diagnostics(fldname::String; filename="available_diagnostics.log")

Get the information for a particular variable fldname from the available_diagnostics.log text file generated by MITgcm.

read_flt(dirIn::String,prec::DataType)

Read displacements from MITgcm/pkg/flt output file into a DataFrame.

read_mdsio(pth::String,fil::String)

Read a set of MITgcm MDSIO-type files (".data" binary + ".meta" text pair), combine, and return as an Array. Unlike read_mdsio(fil::String) where fil is one complete file name, this method will search within pth for files that start with fil.

p="./hs94.cs-32x32x5/run/"
x=read_mdsio(p,"surfDiag.0000000020")
y=read_mdsio(p,"pickup.ckptA")
z=read_mdsio(p,"T.0000000000")

read_mdsio(fil::String)

Read a single MITgcm MDSIO-type file (".data" binary + ".meta" text pair), and return as an Array

p="./hs94.cs-32x32x5/run/"
x=read_mdsio(p*"surfDiag.0000000020.002.001.data")
y=read_mdsio(p*"pickup.ckptA.002.001.data")
z=read_mdsio(p*"T.0000000000.002.001.data")

read_meta(metafile)

Read a MITgcm metadata file, parse it, and return as a NamedTuple

p="./hs94.cs-32x32x5/run/"
meta=read_meta(p*"surfDiag.0000000020.002.001.meta")
pairs(meta)
meta.dimList

read_meta(pth::String,fil::String)

Read a MITgcm metadata files, parse them, and return as an array of NamedTuple

p="./hs94.cs-32x32x5/run/"
meta=read_meta(p,"surfDiag.0000000020")
pairs(meta[end])
[meta[i].dimList for i in 1:length(meta)]

read_mnc(pth::String,fil::String,var::String)

Read variable var from a set of MITgcm MNC-type files (netcdf files), combine, and return as an Array. This method will search within pth for files that start with fil.

read_namelist(fil)

Read a MITgcm namelist file, parse it, and return as a NamedTuple

• assumes a single variable definition per line

using MITgcmTools
testreport("advect_xy")
fil=joinpath(MITgcm_path[1],"verification","advect_xy","run","data")
namelist=read_namelist(fil)

scan_rundir(pth::String)

Scan a MITgcm run directory and standard output text file ("output.txt" or "STDOUT.0000") and return a NamedTuple of collected information (various formats)

Initially, the output looked like (grid=gr,packages=pac,params_time=par1,params_grid=par2,completed=co)

scan_stdout(filout::String)

Scan a MITgcm standard output text file ("output.txt" or "STDOUT.0000") and return a NamedTuple of collected information (various formats).

• packages : report of packages being compiled and used
• params_time : initial time, model duation, output frequency, etc
• params_grid : type of grid (Curvilinear, Cartesian, ...) and array sizes
• paramsfiles : type of output (usemdsio, use_mnc) and array size (ioSize)
• completed : true / false depending on the end of standard output file (filout)

testreport(nam::String,ext="")

Run the testreport script for one model config nam (or "all"), with additional options (optional) speficied in ext

using MITgcmTools
testreport(MITgcm_config(configuration="front_relax"),"-norun")
#testreport(MITgcm_config(configuration="all"),"-norun")

tracer_id_to_name(id)

Return the string "TRAC"+id

tracer_name_to_id(name)

Return the int in the tracer name. i.e. tracer_name_to_id("TRAC21") will return 21

update_ALK(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of ALK for the model's initial condition (note: it will equalize through air-sea exchange)

update_CDOM(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of CDOM for the model's initial condition

update_DOC(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of DOC for the model's initial condition

update_DOFe(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of DOFe for the model's initial condition

update_DON(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of DON for the model's initial condition

update_DOP(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of DOP for the model's initial condition

update_FeT(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of FeT for the model's initial condition

update_NH4(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of NH4 for the model's initial condition

update_NO2(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of NO2 for the model's initial condition

update_NO3(config_obj, new_val)

Arguments:

• config_obj`: the MITgcm_config you are working with
• new_val: amount of NO3 for the model's initial condition

update_O2(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of O2 for the model's initial condition (note: it will equalize through air-sea exchange)

update_PIC(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of PIC for the model's initial condition

update_PO4(config_obj, new_val)

Arguments:

• config_obj`: the MITgcm_config you are working with
• new_val: amount of PO4 for the model's initial condition

update_POC(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of POC for the model's initial condition

update_POFe(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of POFe for the model's initial condition

update_PON(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of PON for the model's initial condition

update_POP(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of POP for the model's initial condition

update_POSi(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of POSi for the model's initial condition

update_SiO2(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of SiO2 for the model's initial condition

update_all_diagnostic_freqs(config_obj, frequency)

Speficy a frequency in seconds at which to write all diagnostic files

Arguments:

• configobj: the MITgcmconfig you are working with
• frequency: new frequency at which to write to the files, in seconds

TODO

update_diagnostic_freq(config_obj, diagnostic_num, frequency)

Speficy a frequency in seconds at which to write to a diagnostic file

Arguments:

• diagnostic_num: the integer identifier for the diagnostic file you want to modify
• frequency: new frequency at which to write to that file, in seconds
• configobj: the MITgcmconfig you are working with

TODO: create enums for diagnostic names (and name them better?)

TODO: what should the initial frequency be? - in file

update_end_time(end_time, config_obj)

Set how long the simulation will run, in iterations. Each iteration is 3 hours, or 10800 seconds. One year is 2880 iterations, which is the default.

Arguments:

• end_time: how many iterations to run the model for
• configobj: the MITgcmconfig you are working with

Default grid size is 1 x 1.

update_param(config_obj, file_name, group_name, param_name, new_param_value)

Speficy a parameter to update

Arguments:

• TODO

update_params(config_obj, file_name, group_names, param_names, new_param_values)

Update multiple parameters in the same file.

Arguments:

• TODO

update_pro(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of Prochlorococcus for the model's initial condition

TODO

update_radtrans(config_obj, ds::NCDataset, x, y, z, t)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of Synechococcus for the model's initial condition

TODO

update_syn(config_obj, new_val)

Arguments:

• config_obj: the MITgcm_config you are working with
• new_val: amount of Synechococcus for the model's initial condition

update_temperature(config_obj, new_temp)

Set the temperature (in celcius). This temperature will be constant throughout the run. TODO: how do you set a variable temperature? i.e. seasonal?

Arguments:

• new_temp: new temperature in celsius
• configobj: the MITgcmconfig you are working with

TODO

update_tracer(config_obj, tracer_num::Int64, new_value::Float32)

Arguments

• config_id
• tracer_num
• new_value

update_tracers(config_obj, tracer_ids, ds::NCDataset, x, y, z, t, multiplier=1)

Arguments

• config_obj
• tracer_ids
• ds
• x
• y
• z
• t
• multiplier

takes a list of tracers and list of values - todo

write_namelist(fil)

Save a MITgcm namelist file. In the example below, one is read from file, modified, and then saved to a new file using write_namelist.

using MITgcmTools
fil=joinpath(MITgcm_path[1],"verification","advect_xy","run","data")
nml=read_namelist(fil)
write_namelist(fil*"_new",namelist)

or

nml=read(fil,MITgcm_namelist())
write(fil*"_new",nml)

Update the palatability matrix for grazer preference where PALAT(X,Y) := rate at which predator Y eats prey X