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
ormatrix
(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 byparse_args()
, i.e. the argument handler function has to store a value inargs[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"})
-