Run Model

This stores the basic classes and functions needed to the run model
Written By: Matthew Stadelman
Date Written: 2016/06/16
Last Modifed: 2017/04/05
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

InputFile(), clone()

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’s infile 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

start()

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 a case_identifier only the evaluations that matter need to be added to the case_params dictionary. Missing permuatations of the identifer are

start()[source]

Starts the bulk run, first creating the input files and then managing the multiple processes until all input files have been processed. The input file list must have already been generated prior to calling this method.

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.