cis_interface.drivers package¶

Subpackages¶

Submodules¶

cis_interface.drivers.CMakeModelDriver module¶

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

Bases: cis_interface.drivers.ModelDriver.ModelDriver

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.

cis_interface.drivers.CMakeModelDriver.build_regex_win32()[source]¶

Build the regex_win32 library using cmake.

cis_interface.drivers.CMakeModelDriver.create_include(fname, target, compile_flags=None, linker_flags=None)[source]¶

Create CMakeList include file with necessary includes, definitions, and linker flags.

Parameters:	fname (str) – File where the include file should be saved. target (str) – Target that links should be added to. compile_flags (list, optional) – Additional compile flags that should be set. Defaults to []. linker_flags (list, optional) – Additional linker flags that should be set. Defaults to [].

cis_interface.drivers.ClientDriver module¶

class cis_interface.drivers.ClientDriver.ClientDriver(model_request_name, request_name=None, comm=None, comm_address=None, **kwargs)[source]¶

Bases: cis_interface.drivers.ClientRequestDriver.ClientRequestDriver

Alias for ClientRequestDriver.

cis_interface.drivers.ClientRequestDriver module¶

class cis_interface.drivers.ClientRequestDriver.ClientRequestDriver(model_request_name, request_name=None, comm=None, comm_address=None, **kwargs)[source]¶

Bases: cis_interface.drivers.ConnectionDriver.ConnectionDriver

Class for handling client side RPC type communication.

Parameters:

model_request_name (str) – The name of the channel used by the client model to send requests. request_name (str, optional) – The name of the channel used to send requests to the server request driver. Defaults to model_request_name + ‘_SERVER’ if not set. comm (str, optional) – The comm class that should be used to communicate with the server request driver. Defaults to tools.get_default_comm(). comm_address (str, optional) – Address for the server request driver. Defaults to None and a new address is generated. **kwargs – Additional keyword arguments are passed to parent class.

comm¶

The comm class that should be used to communicate with the server request driver.

Type:	str

comm_address¶

Address for the server request driver.

Type:	str

response_drivers¶

Response drivers created for each request.

Type:	list

before_loop()[source]¶

Send client sign on to server response driver.

close_comm()[source]¶

Close response drivers.

close_response_drivers()[source]¶

Close response driver.

last_header¶

Information contained in the header of the last message received from the client model.

Type:	dict

model_response_address¶

The address of the channel used by the client model to receive responses.

Type:	str

printStatus(*args, **kwargs)[source]¶

Also print response drivers.

request_address¶

The address of the channel used to send requests to the server request driver.

Type:	str

request_id¶

Unique ID for the last message.

Type:	str

request_name¶

The name of the channel used to send requests to the server request driver.

Type:	str

send_message(*args, **kwargs)[source]¶

Start a response driver for a request message and send message with header.

Parameters:	*args – Arguments are passed to parent class send_message. **kwargs – Keyword arguments are passed to parent class send_message.
Returns:	Success or failure of send.
Return type:	bool

cis_interface.drivers.ClientResponseDriver module¶

class cis_interface.drivers.ClientResponseDriver.ClientResponseDriver(model_response_address, request_name=None, comm=None, msg_id=None, **kwargs)[source]¶

Bases: cis_interface.drivers.ConnectionDriver.ConnectionDriver

Class for handling client side RPC type communication.

Parameters:

model_response_address (str) – The address of the channel used by the client model to receive responses. comm (str, optional) – The comm class that should be used to communicate with the server response driver. Defaults to tools.get_default_comm(). msg_id (str, optional) – ID associate with the request message this driver was created to respond to. Defaults to new unique ID. **kwargs – Additional keyword arguments are passed to parent class.

comm¶

The comm class that should be used to communicate with the server response driver.

Type:	str

msg_id¶

ID associate with the request message this driver was created to respond to.

Type:	str

response_address¶

Address of response comm.

Type:	str

cis_interface.drivers.ConnectionDriver module¶

Module for funneling messages from one comm to another.

class cis_interface.drivers.ConnectionDriver.ConnectionDriver(name, translator=None, single_use=False, onexit=None, **kwargs)[source]¶

Bases: cis_interface.drivers.Driver.Driver

Class that continuously passes messages from one comm to another.

Parameters:

name (str) – Name that should be used to set names of input/output comms. icomm_kws (dict, optional) – Keyword arguments for the input communicator. ocomm_kws (dict, optional) – Keyword arguments for the output communicator. translator (str, func, optional) – Function or string specifying function that should be used to translate messages from the input communicator before passing them to the output communicator. If a string, the format should be “<package.module>:<function>” so that <function> can be imported from <package>. Defaults to None and messages are passed directly. This can also be a list of functions/strings that will be called on the messages in the order they are provided. timeout_send_1st (float, optional) – Time in seconds that should be waited before giving up on the first send. Defaults to self.timeout. single_use (bool, optional) – If True, the driver will be stopped after one loop. Defaults to False. onexit (str, optional) – Class method that should be called when the corresponding model exits, but before the driver is shut down. Defaults to None. **kwargs – Additonal keyword arguments are passed to the parent class.

icomm_kws¶

Keyword arguments for the input communicator.

Type:	dict

ocomm_kws¶

Keyword arguments for the output communicator.

Type:	dict

icomm¶

Input communicator.

Type:	CommBase

ocomm¶

Output communicator.

Type:	CommBase

nrecv¶

Number of messages received.

Type:	int

nproc¶

Number of messages processed.

Type:	int

nsent¶

Number of messages sent.

Type:	int

nskip¶

Number of messages skipped.

Type:	int

state¶

Descriptor of last action taken.

Type:	str

translator¶

Function that will be used to translate messages from the input communicator before passing them to the output communicator.

Type:	func

timeout_send_1st¶

Time in seconds that should be waited before giving up on the first send.

Type:	float

single_use¶

If True, the driver will be stopped after one loop.

Type:	bool

onexit¶

Class method that should be called when the corresponding model exits, but before the driver is shut down.

Type:	str

after_loop()[source]¶

Actions to perform after sending messages.

before_loop()[source]¶

Actions to perform prior to sending messages.

cleanup()[source]¶

Ensure that the communicators are closed.

close_comm()[source]¶

Close the communicators.

confirm_input(timeout=None)[source]¶

Confirm receipt of messages from input comm.

confirm_output(timeout=None)[source]¶

Confirm receipt of messages from output comm.

do_terminate()[source]¶

Stop the driver by closing the communicators.

drain_input(timeout=None)[source]¶

Drain messages from input comm.

drain_output(timeout=None)[source]¶

Drain messages from output comm.

graceful_stop(timeout=None, **kwargs)[source]¶

Stop the driver, first waiting for the input comm to be empty.

Parameters:	timeout (float, optional) – Max time that should be waited. Defaults to None and is set to attribute timeout. **kwargs – Additional keyword arguments are passed to the parent class’s graceful_stop method.

is_comm_closed¶

Returns True if both communicators are closed.

Type:	bool

is_comm_open¶

Returns True if both communicators are open.

Type:	bool

is_valid¶

Returns True if the connection is open and the parent class is valid.

Type:	bool

n_msg¶

Number of messages waiting in input communicator.

Type:	int

on_eof()[source]¶

Actions to take when EOF received.

Returns:	Value that should be returned by recv_message on EOF.
Return type:	str, bool

on_message(msg)[source]¶

Process a message.

Parameters:	msg (bytes, str) – Message to be processed.
Returns:	Processed message.
Return type:	bytes, str

on_model_exit()[source]¶

Drain input and then close it.

open_comm()[source]¶

Open the communicators.

printStatus(beg_msg='', end_msg='')[source]¶

Print information on the status of the ConnectionDriver.

Parameters:	beg_msg (str, optional) – Additional message to print at beginning. end_msg (str, optional) – Additional message to print at end.

recv_message(**kwargs)[source]¶

Get a new message to send.

Parameters:	**kwargs – Additional keyword arguments are passed to the appropriate recv method.
Returns:	False if no more messages, message otherwise.
Return type:	str, bool

run_loop()[source]¶

Run the driver. Continue looping over messages until there are not any left or the communication channel is closed.

send_eof()[source]¶

Send EOF message.

Returns:	Success or failure of send.
Return type:	bool

send_message(*args, **kwargs)[source]¶

Send a single message.

Parameters:	*args – Arguments are passed to the output comm send method. *kwargs – Keyword arguments are passed to the output comm send method.
Returns:	Success or failure of send.
Return type:	bool

set_close_state(state)[source]¶

Set the close state if its not already set.

start()[source]¶

Open connection before running.

update_serializer(msg)[source]¶

Update the serializer for the output comm based on input.

wait_close_state(state, timeout=None)[source]¶

Set the close state after waiting for specified time for the close state to be set by another method.

Parameters:	state (str) – Close state that should be set after timeout. timeout (float, optional) – Time that should be waited before setting the timeout. Defaults to self.timeout.

wait_for_route(timeout=None)[source]¶

Wait until messages have been routed.

cis_interface.drivers.Driver module¶

class cis_interface.drivers.Driver.Driver(name, yml=None, env=None, comm_env=None, namespace=None, rank=None, **kwargs)[source]¶

Bases: cis_interface.tools.CisThreadLoop

Base class for all drivers.

Parameters:

name (str) – Driver name. yml (dict, optional) – Dictionary of yaml specification options for this driver. Defaults to empty dict. env (dict, optional) – Dictionary of environment variables that should be set when the driver starts. Defaults to {}. comm_env (dict, optional) – Dictionary of environment variables for paired IO communication drivers. Defaults to {}. namespace (str, optional) – Namespace for set of drivers running together. If not provided, the config option (‘rmq’, ‘namespace’) is used. rank (int, optional) – Rank of the integration. Defaults to None.

name¶

Driver name.

Type:	str

env¶

Dictionary of environment variables.

Type:	dict

comm_env¶

Dictionary of environment variables for paired IO communication drivers.

Type:	dict

yml¶

Dictionary of yaml specification options for this driver.

Type:	dict

namespace¶

Namespace for set of drivers running together.

Type:	str

rank¶

Rank of the integration.

Type:	int

do_terminate()[source]¶

Actions that should stop the driver.

graceful_stop()[source]¶

Gracefully stop the driver.

is_valid¶

True if the driver is functional.

Type:	bool

on_model_exit()[source]¶

Processes that should be run when an associated model exits.

stop()[source]¶

Stop the driver.

terminate()[source]¶

Stop the driver, without attempting to allow it to finish.

cis_interface.drivers.FileInputDriver module¶

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

Bases: cis_interface.drivers.InputDriver.InputDriver

Class that sends messages read from a file.

Parameters:	name (str) – Name of the queue that messages should be sent to. args (str) – Path to the file that messages should be read from. **kwargs – Additional keyword arguments are passed to the parent class.

cis_interface.drivers.FileOutputDriver module¶

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

Bases: cis_interface.drivers.OutputDriver.OutputDriver

Class to handle output of received messages to a file.

Parameters:	name (str) – Name of the output queue to receive messages from. args (str) – Path to the file that messages should be written to. **kwargs – Additional keyword arguments are passed to the parent class.

cis_interface.drivers.GCCModelDriver module¶

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

Bases: cis_interface.drivers.ModelDriver.ModelDriver

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.

cis_interface.drivers.GCCModelDriver.build_api(cpp=False, overwrite=False, as_shared=False)[source]¶

Build api library.

cis_interface.drivers.GCCModelDriver.build_datatypes(just_obj=False, overwrite=False, as_shared=False)[source]¶

Build the datatypes library.

cis_interface.drivers.GCCModelDriver.build_regex_win32(just_obj=False, overwrite=False)[source]¶

Build the regex_win32 library.

cis_interface.drivers.GCCModelDriver.call_compile(src, out=None, flags=[], overwrite=False, verbose=False, cpp=None, working_dir=None)[source]¶

Compile a source file, checking for errors.

Parameters:	src (str) – Full path to source file. out (str, optional) – Full path to the output object file that should be created. Defaults to None and is created from the provided source file. flags (list, optional) – Compilation flags. Defaults to []. overwrite (bool, optional) – If True, the existing compile file will be overwritten. Otherwise, it will be kept and this function will return without recompiling the source file. verbose (bool, optional) – If True, the compilation command and any output produced by the command will be displayed on success. Defaults to False. cpp (bool, optional) – If True, value is returned assuming the source is written in C++. Defaults to False. working_dir (str, optional) – Working directory that input file paths are relative to. Defaults to current working directory.
Returns:	Full path to compiled source.
Return type:	str

cis_interface.drivers.GCCModelDriver.call_link(obj, out=None, flags=[], overwrite=False, verbose=False, cpp=False, shared=False, static=False, working_dir=None)[source]¶

Compile a source file, checking for errors.

Parameters:	obj (list) – Object files that should be linked. out (str, optional) – Full path to output file that should be created. If None, the path will be determined from the path to the first object file provided. Defaults to False. flags (list, optional) – Compilation flags. Defaults to []. overwrite (bool, optional) – If True, the existing compile file will be overwritten. Otherwise, it will be kept and this function will return without recompiling the source file. verbose (bool, optional) – If True, the linking command and any output produced by the command will be displayed on success. Defaults to False. cpp (bool, optional) – If True, value is returned assuming the source is written in C++. Defaults to False. shared (bool, optional) – If True, the object files are combined into a shared library. Defaults to False. static (bool, optional) – If True, the object files are combined into a static library. Defaults to False. working_dir (str, optional) – Working directory that input file paths are relative to. Defaults to current working directory.
Returns:	Full path to compiled source.
Return type:	str

cis_interface.drivers.GCCModelDriver.do_compile(src, out=None, cc=None, ccflags=None, ldflags=None, working_dir=None, overwrite=False, verbose=False)[source]¶

Compile a C/C++ program with necessary interface libraries.

Parameters:	src (list) – List of source files. out (str, optional) – Path where compile executable should be saved. Defaults to name of source file without extension on Linux/MacOS and with .exe extension on windows. cc (str, optional) – Compiler command. Defaults to gcc/g++ on Linux/MacOS and cl on windows. ccflags (list, optional) – Compiler flags. Defaults to []. ldflags (list, optional) – Linker flags. Defaults to []. working_dir (str, optional) – Working directory that input file paths are relative to. Defaults to current working directory. overwrite (bool, optional) – If True, any existing executable and object files are overwritten. Defaults to False. verbose (bool, optional) – If True, the compilation/linking commands and any output produced by them will be displayed on success. Defaults to False.
Returns:	Products produced by the compilation. The first element will be the executable.
Return type:	list

cis_interface.drivers.GCCModelDriver.get_cc(cpp=False, shared=False, static=False, linking=False)[source]¶

Get command line compiler utility.

Parameters:	cpp (bool, optional) – If True, value is returned assuming the source is written in C++. Defaults to False. shared (bool, optional) – If True, the command line utility will be used to combine object files into a shared library. Defaults to False. static (bool, optional) – If True, the command line utility will be used to combine object files into a static library. Defaults to False. linking (bool, optional) – If True, the command line utility will be used for linking. Defaults to False.
Returns:	Command line compiler.
Return type:	str

cis_interface.drivers.GCCModelDriver.get_flags(for_cmake=False, for_api=False, cpp=False)[source]¶

Get the necessary flags for compiling & linking with CiS libraries.

Parameters:	for_cmake (bool, optional) – If True, the returned flags will match the format required by cmake. Defaults to False. for_api (bool, optional) – If True, the returned flags will match those required for compiling the API static library. Defaults to False. cpp (bool, optional) – If True, flags for compiling a C++ model are returned. Otherwise, flags for compiling a C model are returned. Defaults to False.
Returns:	compile and linker flags.
Return type:	tuple(list, list)

cis_interface.drivers.GCCModelDriver.get_ipc_flags(for_cmake=False, for_api=False)[source]¶

Get the necessary flags for compiling & linking with ipc libraries.

Parameters:	for_cmake (bool, optional) – If True, the returned flags will match the format required by cmake. Defaults to False. for_api (bool, optional) – If True, the returned flags will match those required for compiling the API static library. Defaults to False.
Returns:	compile and linker flags.
Return type:	tuple(list, list)

cis_interface.drivers.GCCModelDriver.get_zmq_flags(for_cmake=False, for_api=False)[source]¶

Get the necessary flags for compiling & linking with zmq libraries.

Parameters:	for_cmake (bool, optional) – If True, the returned flags will match the format required by cmake. Defaults to False. for_api (bool, optional) – If True, the returned flags will match those required for compiling the API static library. Defaults to False.
Returns:	compile and linker flags.
Return type:	tuple(list, list)

cis_interface.drivers.InputDriver module¶

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

Bases: cis_interface.drivers.ConnectionDriver.ConnectionDriver

Driver for receiving input from another model’s comm via a local comm.

Parameters:	name (str) – The name of the local message comm that the driver should connect to. args (str) – The name of the other message comm that the driver should connect to. **kwargs – Additional keyword arguments are passed to parent class.

cis_interface.drivers.LPyModelDriver module¶

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

Bases: cis_interface.drivers.ModelDriver.ModelDriver

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

cis_interface.drivers.MakeModelDriver module¶

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

Bases: cis_interface.drivers.ModelDriver.ModelDriver

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.

cis_interface.drivers.MakeModelDriver.setup_environ(compile_flags=[], linker_flags=[])[source]¶

Set environment variables CISCCFLAGS and CISLDFLAGS.

Parameters:	compile_flags (list, optional) – Additional compile flags that should be set. Defaults to []. linker_flags (list, optional) – Additional linker flags that should be set. Defaults to [].

cis_interface.drivers.MatlabModelDriver module¶

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

Bases: cis_interface.drivers.ModelDriver.ModelDriver

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.MatlabModelDriver.MatlabProcess(target, args, kwargs=None, name=None, matlab_engine=None)[source]¶

Bases: cis_interface.tools.CisClass

Add features to mimic subprocess.Popen while running Matlab function asynchronously.

Parameters:

target (func) – Matlab function that should be called. args (list, tuple) – Arguments that should be passed to target. kwargs (dict, optional) – Keyword arguments that should be passed to target. Defaults to empty dict. name (str, optional) – A name for the process. Generated if not provided. matlab_engine (MatlabEngine, optional) – MatlabEngine that should be used to get errors. Defaults to None and errors will not be recovered unless passed through stdout and stderr before shutdown.

stdout¶

File like string buffer that stdout from target will be written to.

Type:	StringIO

stderr¶

File like string buffer that stderr from target will be written to.

Type:	StringIO

target¶

Matlab function that should be called.

Type:	func

args¶

Arguments that should be passed to target.

Type:	list, tuple

kwargs¶

Keyword arguments that should be passed to target.

Type:	dict

future¶

Future result from async function. This will be None until start is called.

Type:	MatlabFutureResult

matlab_engine¶

MatlabEngine that should be used to get errors.

Type:	MatlabEngine

Raises:	RuntimeError – If Matlab is not installed.

is_alive()[source]¶

bool: Is the async call funning.

is_cancelled()[source]¶

bool: Was the async call cancelled or not.

is_done()[source]¶

bool: Is the async call still running.

is_started()[source]¶

bool: Has start been called.

kill(*args, **kwargs)[source]¶

Cancel the async call.

on_matlab_error()[source]¶

Actions performed on error in Matlab engine.

poll(*args, **kwargs)[source]¶

Fake poll.

print_output()[source]¶

Print output from stdout and stderr.

returncode¶

Return code.

Type:	int

start()[source]¶

Start asychronous call.

stderr_line¶

Output to stderr from function call.

Type:	str

stdout_line¶

Output to stdout from function call.

Type:	str

cis_interface.drivers.MatlabModelDriver.connect_matlab(matlab_session, first_connect=False)[source]¶

Connect to Matlab engine.

Parameters:	matlab_session (str) – Name of the Matlab session that should be connected to. first_connect (bool, optional) – If True, this is the first time Python is connecting to the Matlab shared engine and certain environment variables should be set. Defaults to False.
Returns:	Matlab engine that was connected.
Return type:	MatlabEngine

cis_interface.drivers.MatlabModelDriver.get_matlab_version()[source]¶

Determine the version of matlab that is installed, if at all.

Returns:	Matlab version string.
Return type:	str

cis_interface.drivers.MatlabModelDriver.install_matlab_engine()[source]¶

Install the MATLAB engine API for Python.

cis_interface.drivers.MatlabModelDriver.is_matlab_running()[source]¶

Determine if there is a Matlab engine running.

Returns:	True if there is a Matlab engine running, False otherwise.
Return type:	bool

cis_interface.drivers.MatlabModelDriver.kill_all()[source]¶

Kill all Matlab shared engines.

cis_interface.drivers.MatlabModelDriver.locate_matlab_engine_processes()[source]¶

Get all of the active matlab sharedEngine processes.

Returns:	Active matlab sharedEngine processes.
Return type:	list

cis_interface.drivers.MatlabModelDriver.locate_matlabroot()[source]¶

Find directory that servers as matlab root.

Returns:	Full path to matlabroot directory.
Return type:	str

cis_interface.drivers.MatlabModelDriver.start_matlab(skip_connect=False, timeout=None)[source]¶

Start a Matlab shared engine session inside a detached screen session.

Parameters:	skip_connect (bool, optional) – If True, the engine is not connected. Defaults to False. timeout (int, optional) – Time (in seconds) that should be waited for Matlab to start up. Defaults to None and is set from the config option (‘matlab’, ‘startup_waittime_s’).
Returns:	Information on the started session including the name of the screen session running matlab, the created engine object, the name of the matlab session, and the matlab engine process.
Return type:	tuple
Raises:	RuntimeError – If Matlab is not installed.

cis_interface.drivers.MatlabModelDriver.stop_matlab(screen_session, matlab_engine, matlab_session, matlab_process, keep_engine=False)[source]¶

Stop a Matlab shared engine session running inside a detached screen session.

Parameters:

screen_session (str) – Name of the screen session that the shared Matlab session was started in. matlab_engine (MatlabEngine) – Matlab engine that should be stopped. matlab_session (str) – Name of Matlab session that the Matlab engine is connected to. matlab_process (psutil.Process) – Process running the Matlab shared engine. keep_engine (bool, optional) – If True, the references to the engine will be removed so it is not deleted. Defaults to False.

Raises:

RuntimeError – If Matlab is not installed.

cis_interface.drivers.ModelDriver module¶

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

Bases: cis_interface.drivers.Driver.Driver

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.

set_env()[source]¶

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

cis_interface.drivers.OutputDriver module¶

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

Bases: cis_interface.drivers.ConnectionDriver.ConnectionDriver

Driver for sending output to another model’s comm via a local comm.

Parameters:	name (str) – The name of the local message comm that the driver should connect to. args (str) – The name of the other message comme that the driver should connect to. **kwargs – Additional keyword arguments are passed to parent class.

cis_interface.drivers.PythonModelDriver module¶

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

Bases: cis_interface.drivers.ModelDriver.ModelDriver

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

cis_interface.drivers.RMQAsyncClientDriver module¶

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

Bases: cis_interface.drivers.ClientDriver.ClientDriver

Class for handling an RMQAsync client.

Parameters:	*args – Arguments are passed to parent class. **kwargs – Keyword arguments are passed to parent class.

cis_interface.drivers.RMQAsyncServerDriver module¶

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

Bases: cis_interface.drivers.ServerDriver.ServerDriver

Class for handling an RMQAsync server.

Parameters:	*args – Arguments are passed to parent class. **kwargs – Keyword arguments are passed to parent class.

cis_interface.drivers.RMQClientDriver module¶

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

Bases: cis_interface.drivers.ClientDriver.ClientDriver

Class for handling an RMQ client.

Parameters:	*args – Arguments are passed to parent class. **kwargs – Keyword arguments are passed to parent class.

cis_interface.drivers.RMQServerDriver module¶

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

Bases: cis_interface.drivers.ServerDriver.ServerDriver

Class for handling an RMQ server.

Parameters:	*args – Arguments are passed to parent class. **kwargs – Keyword arguments are passed to parent class.

cis_interface.drivers.ServerDriver module¶

class cis_interface.drivers.ServerDriver.ServerDriver(model_request_name, request_name=None, comm=None, comm_address=None, **kwargs)[source]¶

Bases: cis_interface.drivers.ServerRequestDriver.ServerRequestDriver

Alias for ServerRequestDriver.

cis_interface.drivers.ServerRequestDriver module¶

class cis_interface.drivers.ServerRequestDriver.ServerRequestDriver(model_request_name, request_name=None, comm=None, comm_address=None, **kwargs)[source]¶

Bases: cis_interface.drivers.ConnectionDriver.ConnectionDriver

Class for handling server side RPC type communication.

Parameters:

model_request_name (str) – The name of the channel used by the server model to send requests. request_name (str, optional) – The name of the channel that should be used to receive requests from the client request driver. Defaults to model_request_name + ‘_SERVER’ if not set. comm (str, optional) – The comm class that should be used to communicate with the client request driver. Defaults to tools.get_default_comm(). comm_address (str, optional) – Address for the client request driver. Defaults to None and a new address is generated. **kwargs – Additional keyword arguments are passed to parent class.

comm¶

The comm class that should be used to communicate with the server driver. Defaults to tools.get_default_comm().

Type:	str

comm_address¶

Address for the client request driver.

Type:	str

response_drivers¶

Response drivers created for each request.

Type:	list

nclients¶

Number of clients signed on.

Type:	int

close_comm()[source]¶

Close response drivers.

close_response_drivers()[source]¶

Close response drivers.

last_header¶

Information contained in the header of the last message received from the client model.

Type:	dict

on_client_exit()[source]¶

Close input comm to stop the loop.

on_eof()[source]¶

On EOF, decrement number of clients. Only send EOF if the number of clients drops to 0.

on_message(msg)[source]¶

Process a message checking to see if it is a client signing on.

Parameters:	msg (bytes, str) – Message to be processed.
Returns:	Processed message.
Return type:	bytes, str

printStatus(*args, **kwargs)[source]¶

Also print response drivers.

request_id¶

Unique ID for the last message.

Type:	str

request_name¶

The name of the channel used to receive requests from the client request driver.

Type:	str

response_address¶

The address of the channel used by the server response driver to send responses.

Type:	str

send_message(*args, **kwargs)[source]¶

Send a single message.

Parameters:	*args – Arguments are passed to parent class send_message. **kwargs – Keyword arguments are passed to parent class send_message.
Returns:	Success or failure of send.
Return type:	bool

cis_interface.drivers.ServerResponseDriver module¶

class cis_interface.drivers.ServerResponseDriver.ServerResponseDriver(response_address, comm=None, msg_id=None, request_name=None, **kwargs)[source]¶

Bases: cis_interface.drivers.ConnectionDriver.ConnectionDriver

Class for handling server side RPC type communication.

Parameters:

response_address (str) – The address of the channel used to send responses to the client response driver. comm (str, optional) – The comm class that should be used to communicate with the server resposne driver. Defaults to tools.get_default_comm(). msg_id (str, optional) – ID associate with the request message this driver was created to respond to. Defaults to new unique ID. **kwargs – Additional keyword arguments are passed to parent class.

comm¶

The comm class that should be used to communicate with the server driver. Defaults to tools.get_default_comm().

Type:	str

msg_id¶

ID associate with the request message this driver was created to respond to.

Type:	str

model_response_address¶

The address of the channel used by the server model to send responses.

Type:	str

model_response_name¶

The name of the channel used by the server model to send responses.

Type:	str

response_address¶

The address of the channel used to send responses to the client response driver.

Type:	str

cis_interface.drivers.lpy_model module¶

Module contents¶

IO and Model drivers.

cis_interface.drivers.import_driver(driver=None)[source]¶

Dynamically import a driver based on a string.

Parameters:	driver (str) – Name of the driver that should be imported.

cis_interface.drivers.create_driver(driver=None, name=None, args=None, **kwargs)[source]¶

Dynamically create a driver based on a string and other driver properties.

Parameters:	driver (str) – Name of the driver that should be created. name (str) – Name to give the driver. args (object, optional) – Second argument for drivers which take a minimum of two arguments. If None, the driver is assumed to take a minimum of one argument. Defaults to None. **kwargs – Additional keyword arguments are passed to the driver class.
Returns:	Instance of the requested driver.
Return type:	object