Input
A PDESolver execution is controlled by an options dictonary. The user must supply this dictonary in the form of a Julia source file that declares a Dict{Any, Any} called arg_dict. The file path (relative to the users pwd must be passed to the solver as the the first optional argument. For example, to launch a PDESolver run, execute
julia /path/to/startup.jl "path/to/dictonary"Descriptions of the valid keys and values can be found in the file input_vals.txt. PDESolver supplies default values for all keys for which there is a sane default. Values that might be unused are initialized to -1 or "none".
Conventions
Physics modules generally use the majorIterationCallback function to log important quantities to files. Such logging should be controlled by two keys, "write_outname" where outname is the name of the quantity, which has a boolean value, and "write_outname_fname" that has a string value containing the name of the file to write (including extension). Examples of things that can be logged are entropy and kinetic energy. Both these keys should have default values, and users should generally not need to modify the second one.
Key Validation
After supplying default values, PDESolver checks that all keys in the dictonary are recognized keys. It does this by comparing against the list of keys documented in the input_vals.txt file. A warning of is printed to STDERR if an unrecognized key is found. There is a second file, input_vals_internal.txt, which lists keys that the user should never specify. These keys are completely dependent on other keys from input_vals.txt, and specifying them inconsistently can make the solver seriously misbehave.
The mechanics of the key validation are as follows. The extract_keys.jl script reads the input_vals.txt file (and the input_vals_internal.txt), looking for any string that is surrounded by double quotes and starts in the first character of a line. All keys are written to a dictonary in the file known_keys.jl. This file is included by PDESolver.
The script extract_keys.jl is run as part of PDESolver installation. If new keys are added it must be run again to silence warnings during key validation.
Input.make_input — Method.Make an input file from an options dictionary.
Inputs: dict: the options dictionary fname: the file name (without extension)
Outputs: fname_ex: file name with extension
Input.read_input — Method.PDESolver.read_input
This function read an input file, supplies default values whenever possible, and does sanity checks on the options. A dictionary (referred to as the options dictionary) is returned. See read_input_file for the description of the input file format.
After default values are supplied, the dictionary is printed to arg_dict_output.jl (by MPI rank 0) in the format of an input file. This is useful for rerunning a simulation.
This function prints warnings if keys in the dictionary do not correspond to known options. The file known_keys.jl lists all known keys. See input_vals.txt for the list of keys, possible values, and their meanings.
This function is idempotent; this is essential for using arg_dict_output.jl to rerun a simulation.
Inputs: * fname : name of file to read, can be relative or absolute path.
Outputs: arg_dict: a Dict{Any, Any} containing the option keywords and values
Input.read_input — Method.This method supplies default values to a given dictionary. See the other method for details.
Inputs
arg_dict: a dictionary
Outputs
arg_dict: the same dictionary, with default values supplied
Input.read_input_file — Method.This function reads an input file and turns it into a dictionary. Unlike read_input, this function returns the contents of the input file exactly as a dictionary, without supplying default values.
Inputs
fname: a string containing the file name. If the file name does not start with a . or .. or /, then fname is treated as relative to the pwd, otherwise fname is interpreted as an absolute path
Outputs
arg_dict: the dictionary containing all the options.
Exceptions: if the input file does not contain a dictionary, an exception is thrown.
Notes: currently, the input file format is a literal dictionary that is processed using eval(). This is likely to change to change in the future to support static compilation.
Input.assertKeyPresent — Method.Throws a (descriptive) error if key is not present
Inputs
arg_dict: the options dictionary
key: String
Input.checkBCOptions — Method.Check that a model entity does not have more than one boundary condition applied to it
Input.checkForIllegalOptions_post — Method.Check the user supplied options for errors after supplying default options.
Input.checkForIllegalOptions_pre — Method.Check the user supplied options for errors before supplying default values
Input.checkKeys — Method.PDESolver.checkKeys
This function verifies all the keys in the first argument are also keys of the second argument and prints a warning to STDERR if they are not.
Inputs arg_dict: first dictonary known_keys: second dictonary
Outputs: cnt: number of unrecognized keys
Input.checkPhysicsSpecificOptions — Method.Check that the physics module specified the required options