Run Model¶
-
class
apmapflow.run_model.
InputFile
(infile, filename_formats=None)[source]¶ Used to read and write and manipulate LCL model input files. Each key-value pair stored on an instance of this class is actually an instance of the ArgInput class.
Parameters: - infile (string or InputFile instance) – Either is a filepath to read an input file from or an existing instance to copy.
- filename_formats (dictionary, optional) – A dictionary of filename formats which use Python format strings to dynamically generate names for the LCL model input and output files.
Examples
>>> from apmapflow.run_model import InputFile >>> inp_file = InputFile('input-file-path.inp') >>> fmts = {'VTK-FILE': '{apmap}-data.vtk'} >>> inp_file2 = InputFile(inp_file, filename_formats=fmts)
Notes
Any
filename_formats
defined will overwrite a parameter that was manually defined by directly setting the value. The__setitem__
method of has been subclassed to transparently update the value attribute of the ArgInput instance for the corresponding key instead of the value itself.-
add_parameter
(line)[source]¶ Adds a parameter to the input file by parsing a line into an ArgInput class instance. The line supplied needs to be the same as if it were being manually typed into the actual input file.
Parameters: line (string) – The provided line to parse and append to the InputFile instance. Examples
>>> from apmapflow.run_model import InputFile >>> inp_file = InputFile('input-file-path.inp') >>> inp_file.add_parameter('NEW-PARAM: 1337 ;elite param') >>> inp_file['NEW-PARAM'].value '1337'
Notes
The InputFile inheirits from an OrderedDict so new parameters get added to the bottom of the file.
-
clone
(file_formats=None)[source]¶ Creates a new InputFile instance populated with the current instance data. New ArgInput instances are created to prevent mutation.
Parameters: filename_formats (dictionary, optional) – A dictionary of filename formats which use Python format strings to dynamically generate names for the LCL model input and output files. Returns: input_file – The cloned input file instance Return type: apmapflow.run_model.InputFile Examples
>>> from apmapflow.run_model import InputFile >>> fmts = {'VTK-FILE': '{apmap}-data.vtk'} >>> inp_file = InputFile('input-file-path.inp', filename_formats=fmts) >>> inp_file_copy = inp_file.clone() >>> inp_file_copy.filename_formats {'VTK-FILE': '{apmap}-data.vtk'} >>> inp_file_copy = inp_file.clone(file_formats={}) >>> inp_file_copy.filename_formats {}
Notes
If the
filename_formats
parameter is omitted then the formats from the current instance are copied over.
-
get_uncommented_values
()[source]¶ Generate and return all uncommented parameters as an OrderedDict.
Returns: uncommented_values – An OrderedDict containing all ArgInput instances that were not commented out Return type: OrderedDict
-
parse_input_file
(infile)[source]¶ Populates the InputFile instance with data from a file or copies an existing instance passed in.
Parameters: infile (string or InputFile instance) – Either is a filepath to read an input file from or an existing InputFile instance to copy. See also
-
set_executable
()[source]¶ Sets the path to an LCL model executable based on the
EXE-FILE
parameter for the current InputFile instance. The path is checked relative to the InputFile instance’sinfile
attribute. If no file is found a warning is issued and the executable path defaults to the version packaged with the module.Examples
>>> from apmapflow.run_model import InputFile >>> inp_file = InputFile('./input-file-path.inp') >>> inp_file['EXE-FILE'] = 'my-locally-compiled-model.exe' >>> inp_file.set_executable() >>> inp_file.executable './my-locally-compiled-model.exe'
Notes
This method needs to be called if the
EXE-FILE
parameter is added, changed or removed.
-
update
(*args, **kwargs)[source]¶ Updates the InputFile instance, passing any unknown keys to the filename_format_args dictionary instead of raising a KeyError like in __setitem__
Parameters: **kwargs (*args,) – The resulting dictionary formed internally is used to update the instance Examples
>>> from apmapflow.run_model import InputFile >>> fmts = {'VTK-FILE': '{apmap}-data.vtk'} >>> inp_file = InputFile('input-file-path.inp', filename_formats=fmts) >>> new_vals = {'OUTLET-SIDE': 'LEFT', 'apmap': 'fracture-1'} >>> inp_file.update(new_vals) >>> inp_file['OUTLET-SIDE'].value 'LEFT' >>> inp_file.filename_format_args {'apmap': 'fracture-1'}
-
write_inp_file
(alt_path=None)[source]¶ Writes an input file to the
outfile_name
attribute applying any formats defined based the current parameter values.Parameters: - alt_path (string,) – An alternate path to preappend to the generated filename
- from apmapflow.run_model import InputFile (>>>) –
- inp_file = InputFile('input-file-path.inp') (>>>) –
- inp_file.write_inp_file(alt_path='.') (>>>) –
-
class
apmapflow.run_model.
BulkRun
(init_input_file, num_CPUs=2, sys_RAM=4.0, **kwargs)[source]¶ Handles generating a collection of input files from the provided parameters and then running multiple instances of the LCL model concurrently to produce simulation data for each simulation parameter combination. A comprehensive example of this class and the associated script is avilable under the Usage Examples page.
Parameters: - init_input_file (apmapflow.run_model.InputFile) – An inital InputFile instance to define the static parameters of the bulk run.
- num_CPUs (int, optional) – The maximum number of CPUs to utilize
- sys_RAM (float, optional) – The maximum amount of RAM avilable for use.
- **kwargs (multiple) –
- delim : string
- The expected delimiter in the aperture map files
- spawn_delay : float
- The minimum time between spawning of new LCL instances in seconds
- retest_delay : float
- The time to wait between checking for completed processes.
Examples
>>> from apmapflow import BulkRun, InputFile >>> inp_file = InputFile('./input-file-path.inp') >>> blk_run = BulkRun(inp_file, num_CPUs=16, sys_RAM=32.0, spawn_delay=10.0)
Notes
spawn_delay
is useful to help ensure shared resources are not accessed at the same time.-
dry_run
()[source]¶ Steps through the entire simulation creating directories and input files without actually starting any of the simulations. This Allows the LCL input files to be inspected before actually starting the run.
Examples
>>> from apmapflow import BulkRun, InputFile >>> inp_file = InputFile('./input-file-path.inp') >>> blk_run = BulkRun(inp_file, num_CPUs=16, sys_RAM=32.0, spawn_delay=10.0) >>> blk_run.dry_run()
See also
-
generate_input_files
(default_params, default_name_formats, case_identifer='', case_params=None, append=False)[source]¶ Generates the input file list based on the default parameters and case specific parameters. An InputFile instance is generated for each unique combination of model parameters which is then written to disk to be run by the LCL model.
Parameters: - default_params (dictionary) – A dictionary containing lists of parameter values to use in the simulations.
- default_name_formats (dictionary) – A dictionary containing the infile and outfile name formats to use.
- case_identifer (string, optional) – A format string used to identify cases that need special parameters
- case_params (dictionary, optional) – A dictionary setup where each key is an evaluation of the case_identifer format string and the value is a dictionary containing lists of parameter values used to update the default params for that case.
- append (boolean, optional) – When
True
the BulkRun.input_file_list attribute is appended to instead of reset by this method.
Notes
The
default_name_formats
parameter is passed directly to the InputFile instance initialization and is no modified in any way. When using acase_identifier
only the evaluations that matter need to be added to thecase_params
dictionary. Missing permuatations of the identifer are
-
apmapflow.run_model.
estimate_req_RAM
(input_maps, avail_RAM=inf, suppress=False, **kwargs)[source]¶ Reads in the input maps to estimate the RAM requirement of each map and to make sure the user has alloted enough space. The RAM estimation is a rough estimate based on a linear regression of several simulations of varying aperture map size.
Parameters: - input_maps (list) – A list of filepaths to read in
- avail_RAM (float, optional) – The maximum amount of RAM avilable on the system to be used. When exceeded an EnvironmentError is raised and an error message is generated.
- suppress (boolan, optional) – If it evaluates out to True and a map exceeds the
avail_RAM
the EnvironmentError is suppressed. - **kwargs (optional) – Additional keyword args to pass on to the DataField initialization.
Returns: ram_values – A list of floats with the corresponding RAM estimate for each of the maps passed in.
Return type: list
Examples
>>> from apmapflow.run_model import estimate_req_RAM >>> maps = ['fracture-1.txt', 'fracture-2.txt', 'fracture-3.txt'] >>> estimate_req_RAM(maps, avail_RAM=8.0, suppress=True) [6.7342, 8.1023, 5.7833]
-
apmapflow.run_model.
run_model
(input_file_obj, synchronous=False, show_stdout=False)[source]¶ Runs an instance of the LCL model defined by the InputFile instance passed in.
Parameters: - input_file_obj (apmapflow.run_model.InputFile) – An InputFile instance with the desired simulation parameters to run.
- synchronous (boolean, optional) – If True then run_model will block the main Python execution thread until the simulation is complete.
- show_stdout (boolean, optional) – If True then the stdout and stderr produced during the simulation run are printed to the screen instead of being stored on the Popen instance
Returns: model_popen_obj – The Popen instance that contains the LCL model process, which may or man not be finished executing at upon return.
Return type: Popen
Examples
>>> from apmapflow.run_model import InputFile, run_model >>> inp_file = InputFile('input-file-path.inp') >>> proc = run_model(inp_file) # asynchronous run process isn't completed yet >>> proc.returncode None >>> # process is finished upon return when using synchronous=True >>> proc2 = run_model(inp_file, synchronous=True) >>> proc2.returncode 0
Notes
This writes out the inputfile at the perscribed path, a pre-existing file will be overwritten.