Background Command-line Execution

The function EarthBox.run_earthbox enables sequential model running and post-processing via background command-line execution on Linux/Unix systems.

In order to have compatibility with remote model execution scripts the EarthBox.run_earthbox function should be used inside a script called Runit.jl that can be executed via command line and is located in the model directory with Model.jl and Plot.jl scripts.

`Runit.jl`.

Creating a script called Runit.jl in the model directory that calls the function EarthBox.run_earthbox allows the use to run models and post-processing functions sequentially. See EarthBox.run_earthbox for command-line arguments that are used by EarthBox.run_earthbox.

remote and local batch execution

Scripts named Runit.jl in a model directory scripts are executed by remote_model_loop for remote execution and by local_model_loop for local batch execution.

Runit.jl file name

Since remote and local batch processing functions look for a script called Runit.jl in the model directory it is critical to use the name Runit.jl.

local of Runit.jl scripts

Runit.jl scripts must be located in a model directory along with ['Model.jl'] and ['Plot.jl'] scripts.

The following is an example of a Runit.jl script that would enable sequential execution of models and post-processing functions in addition to remote and local batch execution.

module Runit

using EarthBox
include("Model.jl")

# Get the model output root path constants from Model.jl
import .Model: ROOT_PATH_OUTPUT

# Path to the EarthBox project used when running the model and plotting scripts.
const EB_PROJECT_PATH = "/home/$(get_username())/apps/julia/EarthBox"

function main()
    run_earthbox(
        model_dir = "$(abspath(@__DIR__))",
        # If the EarthBox project path is not provided, then it is assumed that 
        # EarthBox is installed in a standard Julia location or the JULIA_PROJECT 
        # environment variable is set equal to the EarthBox project path.
        eb_project_path_from_script = EB_PROJECT_PATH,
        root_path_output_from_script = ROOT_PATH_OUTPUT
        )
end

end # module

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

EarthBox.RunTools.run_earthbox — Function

run_earthbox(;
    model_dir::String,
    eb_project_path_from_script::Union{String, Nothing} = nothing,
    root_path_output_from_script::Union{String, Nothing} = nothing
)

Run the model script Model.jl and/or plotter script Plot.jl from model directory via command-line execution in the background using the function execute_earthbox_script. This function will run both the model and plotting scripts in sequence.

!!! WARNING !!! This function is for Linux/Unix systems only.

Arguments

model_dir::String
- Directory from where the model action is taken and that contains Runit.jl, Model.jl and Plot.jl.
eb_project_path_from_script::Union{String, Nothing} = nothing
- Path to the EarthBox project from the script executing the action. This will be overridden by the EarthBox project path specified via command line arguments.
root_path_output_from_script::Union{String, Nothing} = nothing
- Path to the root output directory from the script executing the action. This will be overridden by the root output directory specified via command line arguments.

Command Line Arguments

case_name=<case_name>
- The name of the model case defined in CaseInputs.jl. The case name is used when running the model to select inputs from the model case collection defined in CaseInputs.jl. The case name is also used to define the output path in customizable path functions in Paths.jl and Plot.jl.
root_path=<path/to/root/output>
- The path to the root output directory. This will be override the root output directory specified via function argument.
eb_path=<path/to/earthbox/project>
- The path to the EarthBox project used when running Model.jl and Plot.jl. If eb_path is not defined it will be assumed that EarthBox is installed in a standard Julia location or the JULIA_PROJECT environment variable is set equal to the EarthBox project path.
model_output_path=<path/to/model/output>
- The path to the model output directory.
istart=<istart>
- The starting time step for plotting.
iend=<iend>
- The ending time step for plotting.
run_model
- Action command for running the model.
plot_markers
- Action command for plotting the markers.
plot_scalars
- Action command for plotting the scalars.

Usage:

Assuming that run_earthbox() is called from a script called Runit.jl from a model directory that contains Model.jl and Plot.jl...

To run model, plot markers, plot scalars and define all paths on command line, run:

julia Runit.jl case_name=<case_name> run_model plot_markers plot_scalars istart=1 iend=10 eb_path=<eb_path> model_output_path=<path/to/model/output>

or to use root_path instead of model_output_path, run:

julia Runit.jl case_name=<case_name> run_model plot_markers plot_scalars istart=1 iend=10 root_path=<path/to/root/output>`

To run model, plot markers and plot scalars and use path definitions in Model.jl and Plot.jl, run:

julia Runit.jl case_name=<case_name> run_model plot_markers plot_scalars istart=1 iend=10

To run model only and use path definitions in Model.jl and Plot.jl, run:

julia Runit.jl case_name=<case_name> run_model

If a case name is not specified, the default case name is "case0".

source

EarthBox.RunTools.execute_earthbox_script — Function

execute_earthbox_script(;
    model_dir::String,
    eb_path::Union{String, Nothing},
    command_type::String,
    model_case_name::String,
    model_logfile_name::String = "model.log",
    model_output_path::Union{String, Nothing} = nothing
    istart::Int64 = 1,
    iend::Int64 = 1,
)

Execute earthbox scripts via command line.

!!! WARNING !!! This function is for Linux/Unix systems only.

Processes are executed via command line using the Julia run function as follows:

run(bash -c <command>, wait = true)

where <command> takes the form of:

julia [--project=<eb_path>] --startup-file=no <model_dir>/Model.jl case_name=<case_name> model_output_path=<model_output_path> > <model_logfile_name>
julia [--project=<eb_path>] --startup-file=no <model_dir>/Plot.jl marker_plots istart=<istart> iend=<iend> model_case_name=<case_name> model_output_path=<model_output_path> > marker_plots_<model_logfile_name>
julia [--project=<eb_path>] --startup-file=no <model_dir>/Plot.jl scalar_plots istart=<istart> iend=<iend> model_case_name=<case_name> model_output_path=<model_output_path> > scalar_plots_<model_logfile_name>

If eb_path is not specified, then it is assumed that EarthBox is installed in a standard Julia location or the JULIA_PROJECT environment variable is set equal to the EarthBox project path. In this case the --project=<eb_path> argument is not included in the command.

If model_output_path is not specified, then it is assumed that the model output path is defined internally within the Model.jl and Plot.jl scripts.

The following scripts are expected to be in the model directory:

Model.jl
- Model script that initializes the model and runs time steps via the EarthBox API. This script must be setup to be executed via command line with the command line arguments case_name=<case_name>.
Plot.jl
- Plot script that plots the model results using the EarthBox API. This script must be setup to be executed via command line with the command line arguments istart=<istart> iend=<iend> model_case_name=<case_name>.