Model Drivers — cis_interface 0.3.0 documentation

# Model Drivers

class `cis_interface.drivers.ModelDriver.` `ModelDriver`(name, args, is_server=False, client_of=[], with_strace=False, strace_flags=None, with_valgrind=False, valgrind_flags=None, model_index=0, **kwargs)

  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 OSX). 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`

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

  `process`

    `cis_interface.tools.CisPopen` – Process used to run the model.

  `is_server`

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

  `client_of`

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

  `with_strace`

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

  `strace_flags`

    list – Flags to pass to strace/dtrace.

  `with_valgrind`

    bool – If True, the command is run with valgrind.

  `valgrind_flags`

    list – Flags to pass to valgrind.

  `model_index`

    int – Index of model in list of models being run.

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

  `after_loop`()

    Actions to perform after run_loop has finished. Mainly checking if there was an error and then handling it.

  `before_loop`()

    Actions before loop.

  `before_start`()

    Actions to perform before the run starts.

  `enqueue_output_loop`()

    Keep passing lines to queue.

  `graceful_stop`()

    Gracefully stop the driver.

  `kill_process`()

    Kill the process running the model, checking return code.

  `model_process_complete`

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

  `run_loop`()

    Loop to check if model is still running and forward output.

  `wait_process`(timeout=None, key=None, key_suffix=None)

    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)

  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.

class `cis_interface.drivers.MatlabModelDriver.` `MatlabModelDriver`(name, args, **kwargs)

  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`

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

  `screen_session`

    str – Screen session that Matlab was started in.

  `mlengine`

    object – Matlab engine used to run script.

  `mlsession`

    str – Name of the Matlab session that was started.

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

  `after_loop`()

    Actions to perform after run_loop has finished. Mainly checking if there was an error and then handling it.

  `before_start`()

    Actions to perform before the run loop.

  `cleanup`()

    Close the Matlab session and engine.

  `run_loop`()

    Loop to check if model is still running and forward output.

  `start_matlab`()

    Start matlab session and connect to it.

class `cis_interface.drivers.GCCModelDriver.` `GCCModelDriver`(name, args, cc=None, **kwargs)

  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 for ‘.c’ files, and g++ for ‘.cpp’ or ‘.cc’ files on Linux or OSX. Defaults to cl on Windows. **kwargs – Additional keyword arguments are passed to parent class.

  Attributes (in additon to parent class’s):
    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`()

    Remove compile executable.

  `parse_arguments`(args)

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

    Delete products produced during the compilation process.

class `cis_interface.drivers.MakeModelDriver.` `MakeModelDriver`(name, args, make_command=None, makedir=None, makefile=None, **kwargs)

  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/osx and ‘nmake’ on windows. makefile (str, optional) – Path to make file either relative to makedir or absolute. 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 an absolute path is provided, otherwise self.working_dir. **kwargs – Additional keyword arguments are passed to parent class.

  `compiled`

    bool – True if the compilation was successful, False otherwise.

  `target`

    str – Name of executable that should be created and called.

  `make_command`

    str – Command that should be used for make.

  `makedir`

    str – Directory where make should be invoked from.

  `makefile`

    str – Path to make file either relative to makedir or absolute.

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

  `cleanup`()

    Remove compile executable.

  `make_target`(target)

    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, sourcedir=None, builddir=None, cmakeargs=None, preserve_cache=False, **kwargs)

  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`

    bool – True if the compilation was successful, False otherwise.

  `target`

    str – Name of executable that should be created and called.

  `sourcedir`

    str – Source directory to call cmake on.

  `builddir`

    str – Directory where the build should be saved.

  `cmakeargs`

    list – Arguments that should be passed to cmake.

  `preserve_cache`

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

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

  `cleanup`()

    Remove compile executable.

  `run_cmake`(target=None)

    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)

  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.