Simulation Scripts

HAL’s MD package is configured and steered with customisable simulation scripts written in Lua 5.

Structure

A simulation script must define a global method main, which sets up and runs the simulation. Optionally, a global method define_args can be defined to specify custom command line arguments, see Program Options.

halmd

Predefined global that holds the Modules.

main(args)

Main simulation entry point (defined by the simulation script).

Parameters:args (table) – command line arguments as returned from parser

define_args(parser)

Optional entry point (defined by the simulation script) that, if present, is called prior to main() and can be used to define command line arguments.

Parameters:parser – instance of halmd.utility.program_options.argument_parser

Examples

Complete examples of simulation scripts can be found in share/doc/halmd/examples in the installation directory. A minimal simulation script is of the following form:

-- grab module namespaces
local log = halmd.io.log

function main(args)
    -- some output to logger
    log.info("Write 'Hello World!' to " .. args.output .. ".log")

    -- here: setup system and run simulation
end

function define_args(parser)
    parser:add_argument("output,o", {type = "string", action = parser.substitute_date_time_action,
        default = "project_%Y%m%d_%H%M%S", help = "prefix of output files"})

    parser:add_argument("random-seed", {type = "integer", action = parser.random_seed_action,
        help = "seed for random number generator"})

    return parser
end

Advanced

The main and define_args functions are called from the internal lua script run.lua, which is found in share/halmd/lua in the installation directory. This script defines a few standard command line arguments, calls the custom method define_args if present, executes the argument parser, and performs some initial setup, e.g., of the logger. Advanced users may modify this script to change the predefined behaviour.

Backwards compatibility with versions 0.3 < x < 1.0 of HAL´s MD package is achieved by replacing the script run.lua with an empty script. In this case, the simulation script is run directly and all initial setup is in the responsibility of the user.