Model Drivers¶

class cis_interface.drivers.ModelDriver.ModelDriver(name, args, model_index=0, **kwargs)[source]¶

Base class for Model drivers and for running executable based models.

Parameters:

name (str) – Driver name.
args (str or list) – Argument(s) for running the model on the command line. This should be a complete command including the necessary executable and command line arguments to that executable.
is_server (bool, optional) – If True, the model is assumed to be a server and an instance of cis_interface.drivers.ServerDriver is started. Defaults to False.
client_of (str, list, optional) – The names of ne or more servers that this model is a client of. Defaults to empty list.
with_strace (bool, optional) – If True, the command is run with strace (on Linux) or dtrace (on MacOS). Defaults to False.
strace_flags (list, optional) – Flags to pass to strace (or dtrace). Defaults to [].
with_valgrind (bool, optional) – If True, the command is run with valgrind. Defaults to False.
valgrind_flags (list, optional) – Flags to pass to valgrind. Defaults to [].
model_index (int, optional) – Index of model in list of models being run. Defaults to 0.
**kwargs – Additional keyword arguments are passed to parent class.

args¶

Argument(s) for running the model on the command line.

Type:	list

process¶

Process used to run the model.

Type:	`cis_interface.tools.CisPopen`

is_server¶

If True, the model is assumed to be a server and an instance of cis_interface.drivers.ServerDriver is started.

Type:	bool

client_of¶

The names of server models that this model is a client of.

Type:	list

with_strace¶

If True, the command is run with strace or dtrace.

Type:	bool

strace_flags¶

Flags to pass to strace/dtrace.

Type:	list

with_valgrind¶

If True, the command is run with valgrind.

Type:	bool

valgrind_flags¶

Flags to pass to valgrind.

Type:	list

model_index¶

Index of model in list of models being run.

Type:	int

Raises:	`RuntimeError` – If both with_strace and with_valgrind are True.

after_loop()[source]¶: Actions to perform after run_loop has finished. Mainly checking if there was an error and then handling it.

before_loop()[source]¶: Actions before loop.

before_start()[source]¶: Actions to perform before the run starts.

enqueue_output_loop()[source]¶: Keep passing lines to queue.

graceful_stop()[source]¶: Gracefully stop the driver.

classmethod is_installed()[source]¶

Determine if this model driver is installed on the current machine.

Returns:	Truth of if this model driver can be run on the current machine.
Return type:	bool

kill_process()[source]¶: Kill the process running the model, checking return code.

model_process_complete¶

Has the process finished or not. Returns True if the process has not started.

Type:	bool

run_loop()[source]¶: Loop to check if model is still running and forward output.

wait_process(timeout=None, key=None, key_suffix=None)[source]¶

Wait for some amount of time for the process to finish.

Parameters:	timeout (float, optional) – Time (in seconds) that should be waited. Defaults to None and is infinite. key (str, optional) – Key that should be used to register the timeout. Defaults to None and set based on the stack trace.
Returns:	True if the process completed. False otherwise.
Return type:	bool

class cis_interface.drivers.PythonModelDriver.PythonModelDriver(name, args, **kwargs)[source]¶

Class for running Python models.

Parameters:	name (str) – Driver name. args (str or list) – Argument(s) for running the model on the command after the call to python. **kwargs – Additional keyword arguments are passed to parent class’s __init__ method.

classmethod is_installed()[source]¶

Determine if this model driver is installed on the current machine.

Returns:	Truth of if this model driver can be run on the current machine.
Return type:	bool

class cis_interface.drivers.MatlabModelDriver.MatlabModelDriver(name, args, **kwargs)[source]¶

Base class for running Matlab models.

Parameters:	name (str) – Driver name. args (str or list) – Argument(s) for running the model in matlab. Generally, this should be the full path to a Matlab script. **kwargs – Additional keyword arguments are passed to parent class’s __init__ method.

started_matlab¶

True if the driver had to start a new matlab engine. False otherwise.

Type:	bool

screen_session¶

Screen session that Matlab was started in.

Type:	str

mlengine¶

Matlab engine used to run script.

Type:	object

mlsession¶

Name of the Matlab session that was started.

Type:	str

Raises:	`RuntimeError` – If Matlab is not installed.

Note

Matlab models that call exit will shut down the shared engine.

after_loop()[source]¶: Actions to perform after run_loop has finished. Mainly checking if there was an error and then handling it.

before_start()[source]¶: Actions to perform before the run loop.

check_exits()[source]¶

Check to make sure the program dosn’t contain any exits as exits will shut down the Matlab engine as well as the program.

Raises:	`RuntimeError` – If there are any exit calls in the file.

cleanup()[source]¶: Close the Matlab session and engine.

classmethod is_installed()[source]¶

Determine if this model driver is installed on the current machine.

Returns:	Truth of if this model driver can be run on the current machine.
Return type:	bool

run_loop()[source]¶: Loop to check if model is still running and forward output.

start_matlab()[source]¶: Start matlab session and connect to it.

class cis_interface.drivers.GCCModelDriver.GCCModelDriver(name, args, **kwargs)[source]¶

Class for running gcc compiled drivers.

Parameters:

name (str) – Driver name.
args (str or list) – Argument(s) for running the model on the command line. If the first element ends with ‘.c’, the driver attempts to compile the code with the necessary interface include directories. Additional arguments that start with ‘-I’ are included in the compile command. Others are assumed to be runtime arguments.
cc (str, optional) – C/C++ Compiler that should be used. Defaults to gcc/clang for ‘.c’ files, and g++/clang++ for ‘.cpp’ or ‘.cc’ files on Linux/MacOS. Defaults to cl on Windows.
overwrite (bool, optional) – If True, any existing object or executable files for the model are overwritten, otherwise they will only be compiled if they do not exist. Defaults to True. Setting this to False can be done to improve performance after debugging is complete, but this dosn’t check if the source files should be changed, so users should make sure they recompile after any changes. The value of this keyword also determines whether or not any compilation products are cleaned up after a run.
**kwargs – Additional keyword arguments are passed to parent class.

Attributes (in additon to parent class’s):

overwrite (bool): If True, any existing compilation products will be: overwritten by compilation and cleaned up following the run. Otherwise, existing products will be used and will remain after the run.

products (list): File created by the compilation. compiled (bool): True if the compilation was succesful. False otherwise. cfile (str): Source file. cc (str): C/C++ Compiler that should be used. flags (list): List of compiler flags. efile (str): Compiled executable file.

Raises:	`RuntimeError` – If neither the IPC or ZMQ C libraries are available. `RuntimeError` – If the compilation fails.

cleanup()[source]¶: Remove compile executable.

classmethod is_installed()[source]¶

Determine if this model driver is installed on the current machine.

Returns:	Truth of if this model driver can be run on the current machine.
Return type:	bool

parse_arguments(args)[source]¶

Sort arguments based on their syntax. Arguments ending with ‘.c’ or ‘.cpp’ are considered source and the first one will be compiled to an executable. Arguments starting with ‘-L’ or ‘-l’ are treated as linker flags. Arguments starting with ‘-‘ are treated as compiler flags. Any arguments that do not fall into one of the categories will be treated as command line arguments for the compiled executable.

Parameters:	args (list) – List of arguments provided.
Raises:	`RuntimeError` – If there is not a valid source file in the argument list.

remove_products()[source]¶: Delete products produced during the compilation process.

class cis_interface.drivers.MakeModelDriver.MakeModelDriver(name, args, **kwargs)[source]¶

Class for running make file compiled drivers. Before running the make command, the necessary compiler & linker flags for the interface’s C/C++ library are stored the environment variables CISCCFLAGS and CISLDFLAGS respectively. These should be used in the make file to correctly compile with the interface’s C/C++ libraries.

Parameters:

name (str) – Driver name.
args (str, list) – Executable that should be created (make target) and any arguments for the executable.
make_command (str, optional) – Command that should be used for make. Defaults to ‘make’ on Linux/MacOS and ‘nmake’ on windows.
makefile (str, optional) – Path to make file either absolute, relative to makedir (if provided), or relative to working_dir. Defaults to Makefile.
makedir (str, optional) – Directory where make should be invoked from if it is not the same as the directory containing the makefile. Defaults to directory containing makefile if provided, otherwise self.working_dir.
**kwargs – Additional keyword arguments are passed to parent class.

compiled¶

True if the compilation was successful, False otherwise.

Type:	bool

target¶

Name of executable that should be created and called.

Type:	str

make_command¶

Command that should be used for make.

Type:	str

makedir¶

Directory where make should be invoked from.

Type:	str

makefile¶

Path to make file either relative to makedir or absolute.

Type:	str

Raises:	`RuntimeError` – If neither the IPC or ZMQ C libraries are available.

cleanup()[source]¶: Remove compile executable.

classmethod is_installed()[source]¶

Determine if this model driver is installed on the current machine.

Returns:	Truth of if this model driver can be run on the current machine.
Return type:	bool

make_target(target)[source]¶

Run the make command to make the target.

Parameters:	target (str) – Target that should be made.
Raises:	`RuntimeError` – If there is an error in running the make.

class cis_interface.drivers.CMakeModelDriver.CMakeModelDriver(name, args, preserve_cache=False, **kwargs)[source]¶

Class for running cmake compiled drivers. Before running the cmake command, the cmake commands for setting the necessary compiler & linker flags for the interface’s C/C++ library are written to a file called ‘cis_cmake.txt’ that should be included in the CMakeLists.txt file (after the target executable has been added).

Parameters:

name (str) – Driver name.
args (str, list) – Executable that should be created (cmake target) and any arguments for the executable.
sourcedir (str, optional) – Source directory to call cmake on. If not provided it is set to self.working_dir. This should be the directory containing the CMakeLists.txt file. It can be relative to self.working_dir or absolute.
builddir (str, optional) – Directory where the build should be saved. Defaults to <sourcedir>/build. It can be relative to self.working_dir or absolute.
cmakeargs (list, optional) – Arguments that should be passed to cmake. Defaults to [].
preserve_cache (bool, optional) – If True the cmake cache will be kept following the run, otherwise all files created by cmake will be cleaned up. Defaults to False.
**kwargs – Additional keyword arguments are passed to parent class.

compiled¶

True if the compilation was successful, False otherwise.

Type:	bool

target¶

Name of executable that should be created and called.

Type:	str

sourcedir¶

Source directory to call cmake on.

Type:	str

builddir¶

Directory where the build should be saved.

Type:	str

cmakeargs¶

Arguments that should be passed to cmake.

Type:	list

preserve_cache¶

If True the cmake cache will be kept following the run, otherwise all files created by cmake will be cleaned up.

Type:	bool

Raises:	`RuntimeError` – If neither the IPC or ZMQ C libraries are available.

cleanup()[source]¶: Remove compile executable.

classmethod is_installed()[source]¶

Determine if this model driver is installed on the current machine.

Returns:	Truth of if this model driver can be run on the current machine.
Return type:	bool

run_cmake(target=None)[source]¶

Run the cmake command on the source.

Parameters:	target (str, optional) – Target to build.
Raises:	`RuntimeError` – If there is an error in running cmake.

class cis_interface.drivers.LPyModelDriver.LPyModelDriver(name, args, **kwargs)[source]¶

Class for running LPy models.

Parameters:	name (str) – Driver name. args (str) – The LPy l-system file. **kwargs – Additional keyword arguments are passed to parent class’s __init__ method.

classmethod is_installed()[source]¶

Determine if this model driver is installed on the current machine.

Returns:	Truth of if this model driver can be run on the current machine.
Return type:	bool