Program Options

This module allows the use of command-line options in HALMD scripts.

Example:

halmd liquid.lua --lennard-jones epsilon=2 sigma=2 --disable-gpu
class halmd.utility.program_options.argument_parser

Create new command-line parser.

Example:

local options = require("halmd.utility.program_options")
local parser = options.argument_parser()

Note

Typically, the argument parser is not created directly. Instead a simulation script may define a global method define_args, which receives an argument parser as its argument, see Simulation Scripts.

add_argument(name, args)

Add argument to parser.

Parameters:
  • name (string) – long name, and (optionally) short name separated by comma
  • args (table) – keyword arguments
  • args.type (string) – value type of option
  • args.dtype (string) – element type of vector or matrix (optional)
  • args.help (string) – description of option for –help (optional)
  • args.composing (boolean) – allow multiple occurences with single value (default: false)
  • args.multitoken (boolean) – allow multiple occurences with multiple values (default: false)
  • args.required (boolean) – require at minimum one occurence (default: false)
  • args.choices (table) – allowed values with descriptions (optional)
  • args.action (function) – argument handler function (optional)
  • args.default – default option value (optional)
  • args.implicit – implicit option value (optional)

The following value types are supported:

Type Description
boolean Boolean
string String
accumulate Increment integer
vector 1-dimensional array of type dtype
matrix 2-dimensional array of type dtype

These integral and floating-point value types are supported:

Type Description
number Double-precision floating-point
integer Signed 64-bit integer
int32 Signed 32-bit integer
int64 Signed 64-bit integer
uint32 Unsigned 32-bit integer
uint64 Unsigned 64-bit integer
float32 Single-precision floating-point
float64 Double-precision floating-point

Example:

parser:add_argument("disable-gpu", {type = "boolean", help = "disable GPU acceleration"})

An optional table choices may be used to constrain the value of an argument:

parser.add_argument("ensemble", {type = "string", choices = {
    nve = "Constant NVE",
    nvt = "Constant NVT",
    npt = "Constant NPT",
}, help = "statistical ensemble"})

Note that only arguments of type string are supported.

The optional action function receives the following arguments:

Parameters:
  • args (table) – parsed arguments
  • key (string) – args table key of this argument
  • value – parsed value of this argument

Note that if you specify action, the argument value will not be stored in the table returned by parse_args(), i.e. the argument handler function has to store a value in args[key] itself.

Example:

parser:add_argument("output", {type = "string", action = function(args, key, value)
   -- substitute current time
   args[key] = os.date(value)
end, default = "halmd_%Y%m%d_%H%M%S", help = "prefix of output files"})
add_argument_group(name, args)

Add argument group.

Parameters:
  • name – name of argument group
  • args (table) – keyword arguments (optional)
  • args.help (string) – description of argument group for –help (optional)
Returns:

argument group

Example:

local group = parser:add_argument_group("lennard-jones")
group:add_argument("epsilon", {type = "number", help = "potential well depths"})
group:add_argument("sigma", {type = "number", help = "collision diameter"})
set_defaults(defaults)

Set default option values.

Parameters:defaults (table) – argument names with default values

Example:

parser:set_defaults({particles = {9000, 1000}, number_density = 0.8})
parse_args(args)

Parse arguments.

Parameters:args (table) – sequence of arguments (optional)
Returns:parsed arguments

If args is not specified, the command-line arguments are parsed.

Example:

local args = parser:parse_args()
class halmd.utility.program_options.argument_parser.action
substitute_date_time(args, key, value)

Substitute date/time helper action.

Parameters:
  • args (table) – parsed arguments
  • key (string) – args table key of this argument
  • value – parsed value of this argument

Helper function that can be used as action argument for argument_parser:add_argument and substitutes day and time in the parsed value of the argument.

Example:

parser:add_argument("output,o", {type = "string", action = parser.action.substitute_date_time,
    default = "lennard_jones_%Y%m%d_%H%M%S", help = "prefix of output files"})
class halmd.utility.program_options.argument_parser.action
substitute_environment(args, key, value)

Action that substitutes environment variables.

Parameters:
  • args (table) – parsed arguments
  • key (string) – args table key of this argument
  • value – parsed value of this argument

Helper function that can be used as action argument for argument_parser:add_argument and substitutes environment variables in the parsed value of the argument. Variable names must be enclosed by ‘%’ characters and are obtained from os.getenv.

Example:

parser:add_argument("output,o", {type = "string", action = parser.action.substitute_environment,
    default = "%HOME%/halmd_%PID%", help = "prefix of output files"})
random_seed(args, key, value)

Random seed helper action.

Parameters:
  • args (table) – parsed arguments
  • key (string) – args table key of this argument
  • value – parsed value of this argument

Helper function that can be used as action argument for argument_parser:add_argument and initializes the RNG with a given seed.

Example:

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