Executing Models Using Input Files

The run_model function can be used in a script with arguments based on user defined functions or via command line.

EarthBox.run_model — Function
run_model(; kwargs...)

Run EarthBox model using user specified paths.

Keyword arguments

  • make_backup::Bool
    • Whether to make a backup of the model state at each output time step.
  • restart_from_backup::Bool
    • Whether to restart from a backup file.
  • use_mumps::Bool
    • Whether to use MUMPS for solving the linear system of equations.
  • use_mumps_internal::Bool
    • Whether to use the internal MUMPS solver.
  • nprocs::Int
    • Number of MPI processes to use.
  • marker_output_from_user::Union{Dict{String, Bool}, Nothing}
    • Dictionary of marker output keys and values from user input. See list of marker output keys below.
  • model_input_file::String
    • Path to the model input file.
  • materials_input_file::String
    • Path to the materials input file.
  • materials_library_file::String
    • Path to the materials library file.
  • model_output_path::Union{String, Nothing}
    • Path to the model output directory. If not provided, the model output directory is set to "output" and is created in the current working directory.

List of marker output keys

  • marker_x
  • marker_y
  • marker_matid
  • marker_GII
  • markerstrainplastic
  • markerstrainrate_plastic
  • marker_meltfrac
  • markerextractablemeltfrac
  • markerextractedmeltfrac
  • marker_serpentinization
  • marker_pfailure
  • marker_TK
  • marker_xn
  • marker_yn
  • marker_sxx
  • marker_sxy
  • marker_eta
  • marker_exx
  • marker_exy
  • marker_pr
  • markersrratio
  • marker_age
  • markerfricini
  • marker_fric
  • marker_cohesion
  • marker_preexp
  • marker_rho

Returns

  • nothing
source

Execution Using run_model and Command-line Arguments (CLIRun.jl)

A command-line based script, typically named CLIRun.jl, can be developed using the run_model function and functions from the GetArgs:

module CLIRun

using EarthBox

function cl_run()
    run_model(
       make_backup             = GetArgs.get_make_backup_from_args(), 
       restart_from_backup     = GetArgs.get_restart_from_backup_from_args(), 
       use_mumps               = GetArgs.get_use_mumps_from_args(), 
       use_mumps_internal      = GetArgs.get_use_mumps_internal_from_args(), 
       nprocs                  = GetArgs.get_nprocs_from_args(), 
       marker_output_from_user = GetArgs.get_marker_output_dict_from_args(),
       model_input_file        = GetArgs.get_model_input_file_from_args(), 
       materials_input_file    = GetArgs.get_materials_input_file_from_args(), 
       materials_library_file  = GetArgs.get_materials_library_file_from_args(), 
       model_output_path       = GetArgs.get_model_output_path_from_args()
    )
    return nothing
end

function main()::Nothing
    cl_run()
    return nothing
end

end # module

if abspath(PROGRAM_FILE) == @__FILE__
    CLIRun.main()
end

If model.yml and materials.yml are in the same directory as CLRun.jl then the model can be run with the following command:

% julia CLIRun.jl model_input_file="model.yml" materials_input_file="materials.yml" materials_library_file="/path/to/materials_collection_file.yml" model_output_path="path/to/model_output marker_output='{marker_x=false, marker_y=true}'"
`model_output_path`

If you omit the model_output_path argument output will be sent to a directory called output in the current working directory.

material collection files

Material collection files are stored in src/material_library/registries.

marker_output

When defining the marker output flag dictionary via command line ensure that either no spaces exist on either side of the = sign or use a space on both sides of the = sign. For example, the following are valid command-line arguments:

  • marker_output={marker_x=true, marker_y=true}
  • marker_output = {marker_x=true, marker_y=true}

Execution Using run_model and User-defined Functions (ReadRun.jl)

module ReadRun

using EarthBox

const MODEL_PATH = joinpath(@__DIR__, "model.yml")
const MATERIAL_MODEL_PATH = joinpath(@__DIR__, "materials.yml")
const MATERIAL_COLLECTION = MaterialLibrary().lithospheric_deformation.lithospheric_deformation_eb1
const MODEL_OUTPUT_PATH = "/mnt/extradrive1/earthbox_output/extension_to_sfs/sdr_formation_output"

function read_run()::Nothing
    marker_output_from_user = Dict{String, Bool}(
        "marker_age" => true,
        "marker_rho" => true,
        "marker_serpentinization" => true,
        "marker_extractable_meltfrac" => false,
        "marker_extracted_meltfrac" => false,
        "marker_strain_rate_plastic" => true,
    )
    run_model(
        make_backup            = false, 
        restart_from_backup    = false, 
        use_mumps              = false, 
        use_mumps_internal     = true, 
        nprocs                 = 1, 
        marker_output_from_user = marker_output_from_user,
        model_input_file       = MODEL_PATH, 
        materials_input_file   = MATERIAL_MODEL_PATH, 
        materials_library_file = MATERIAL_COLLECTION.path, 
        model_output_path      = MODEL_OUTPUT_PATH
        )
    return nothing
end

function main()::Nothing
    read_run()
    return nothing
end

end # module

if abspath(PROGRAM_FILE) == @__FILE__
    ReadRun.main()
end

The script above can be executed via command line:

%julia ReadRun.jl

or from the REPL,

include("ReadRun.jl")
ReadRun.read_un()