Run Model Core

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.run_model.ArgInput(line)

Stores the value of a single input line of a LCL model input file. Instances of this class are stored in an InputFile instance’s dict to manage each parameter.

Parameters:line (string) – input line to parse.

__init__(line)

Parses the line for the input key string and value.

__str__()

Allows direct printing of an ArgInput object in output format.

Examples

>>> from apmapflow.run_model.run_model import ArgInput
>>> param = ArgInput('test-param: 123 ft')
>>> print(param)
test-param: 123 ft

See also

line()

__weakref__

list of weak references to the object (if defined)

_parse_line(line)

Parses a line to set attributes of the class instance.

Parameters:line (string) – input line to parse.

keyword

Returns the keyword used to register this instance to an InputFile instance.

line

Return a formatted line meant for use when writing an InputFile isntance to disk. The line is prefixed by ; if the parameter is supposed to be commented out.

Examples

>>> from apmapflow.run_model.run_model import ArgInput
>>> param = ArgInput('test-param: 123 ft')
>>> param.line
'test-param: 123 ft'
>>> param.commented_out = True
>>> param.line
';test-param: 123 ft'

See also

__str__

unit

Returns the given units a value is in or None, and can also be used to set the units of a value.

Parameters:value (string, optional) – If supplied with a value then the units of a instance are set to it.

Examples

>>> from apmapflow.run_model.run_model import ArgInput
>>> param = ArgInput('test-param: 123 ft')
>>> param.unit
'ft'
>>> param.unit = 'mm'
>>> param.unit
'mm'

value

Returns the value of the parameter stored by the class instance or sets the value of the instance. When setting the value if a tuple is passed instead of a scalar the first entry is used to set the value and the second’s truth value sets the .commented out attribute of the instance.

Parameters:value (scalar or tuple, optional) – When value is supplied the property is set

Examples

>>> from apmapflow.run_model.run_model import ArgInput
>>> param = ArgInput('test-param: value-123')
>>> param.value
'value-123'
>>> param.commented_out
False
>>> param.value = 'new-value'
>>> param.value
'new-value'
>>> param.value = ('commented-out', True)
>>> param.value
'commented-out'
>>> param.commented_out
True

class apmapflow.run_model.run_model.AsyncCommunicate(popen_obj)

Allows an executable to be run in a separate thread so it does not block the main Python process.

Parameters:popen_obj (Popen instance) – An instance containing a process that is currently executing.

run()

Calls the communicate method on the Popen object registered to the class which blocks the thread until the process terminates. The total execution time, stdout and stderr of the process are passed back to the Popen object.

class apmapflow.run_model.run_model.InputFile(infile, filename_formats=None)

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.

__setitem__(key, value, new_param=False)

Subclassed to pass the value directly to the value attribute of the ArgInput instance stored on the provided key unless the new_param argument evaluates to True.

Parameters:

• key (string) – The key on the dictionary to update
• value (string or ArgInput instance) – The value to set the given key to
• new_param (boolean, optional) – If True then the value is not passed on to the ArgInput instance and the actual value on the InputFile instance is changed.

Examples

>>> from apmapflow.run_model import InputFile
>>> inp_file = InputFile('input-file-path.inp')
>>> inp_file['parameter'] = '123'
>>> inp_file['parameter']
<apmapflow.run_model.run_model.ArgInput object at #########>
>>> inp_file['parameter'].value
'123'
>>> inp_file.__setitem__('parameter', 'param-value', new_param=True)
>>> inp_file['parameter']
'param-value'

Notes

If new_param is falsy and the key does not already exist a KeyError exeception is raised. The add_parameter method is the standard way to add new ArgInput instances to the InputFile instance

See also

add_parameter()

__str__()

Writes out the input file as if it was being written to disk.

_construct_file_names(make_dirs=False)

This updates the instance’s outfile names to match current arguments.

Parameters:make_dirs (boolean, optional) – If make_dirs evaluates to True then all parent directories for each output file are created as well.

add_parameter(line)

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)

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()

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)

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()

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)

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)

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='.') (>>>) –

apmapflow.run_model.run_model.estimate_req_RAM(input_maps, avail_RAM=inf, suppress=False, **kwargs)

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.run_model(input_file_obj, synchronous=False, show_stdout=False)

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.