SimRunner

class spicelib.sim.sim_runner.SimRunner(*, simulator=None, parallel_sims=4, timeout=600.0, verbose=False, output_folder=None, cwd=None)

Bases: AnyRunner

The SimRunner class implements all the methods required for launching batches of Spice simulations.

It is iterable, but with a catch: The iteration will only return the completed tasks (succeeded or not), in the order they were completed. If all completed tasks have been returned, and there are still running tasks, it will wait for the completion of the next task. If you used no callbacks, the result is a tuple with the raw and log file names. If you used callbacks, it will return the return code of the callback function, or None if there was an error. Also see sim_info() for more details on the completed tasks.

Parameters:

• simulator (Simulator, optional) – Forcing a given simulator executable.

• parallel_sims (int, optional) – Defines the number of parallel simulations that can be executed at the same time. Ideally this number should be aligned to the number of CPUs (processor cores) available on the machine.

• timeout (float, optional) – Timeout parameter as specified on the OS subprocess.run() function. Default is 600 seconds, i.e. 10 minutes. For no timeout, set to None.

• verbose (bool, optional) – If True, it enables a richer printout of the program execution.

• output_folder (str, optional) – specifying which directory shall be used for simulation files (raw and log files).

• cwd (str or pathlib.Path, optional) – The current working directory to run the command in. If None, no change will be done of the working directory.

Raises:

FileNotFoundError – When the file is not found. !This will be changed.

active_threads()

Returns the number of active simulation runs

add_command_line_switch(switch, path='')

Used to add an extra command line argument such as ‘-I<path>’ to add symbol search path or ‘-FastAccess’ to convert the raw file into Fast Access. The argument is a string as is defined in the command line documentation of the used simulator. It is preferred that you use the Simulator’s class valid_switch() method for validation of the switch.

Parameters:

• switch (str) – switch to be added. See Command Line Switches documentation of the used simulator.

• path (str, optional) – path to the file related to the switch being given.

Returns:

Nothing

cleanup_files()

Will delete all log and raw files that were created by the script. This should only be executed at the end of data processing.

clear_command_line_switches()

Clear all the command line switches added previously

create_raw_file_with(raw_filename, save, conditions)

Creates a new raw_file, with traces belonging to different runs. The type of the raw file is the same as the first raw file that is matching the conditions. See filter_completed_tasks() method.

Parameters:

• raw_filename (Path | str) – The new RAW filename

• save (list[str]) – A list with traces that are going to be saved in the new raw file

• conditions (Callable[[RunTask], bool] | dict | None) – A filter as specified on the TaskIterator class

Returns:

True if the raw file was created successfully and includes ALL runs, False otherwise

Return type:

bool

export_sim_log(logfile)

Exports the simulation log to a file.

Parameters:

logfile (Path | str) – The path to the log file

property failSim: int

number of failed simulations

file_cleanup()

Deprecated since version 1.0: Use cleanup_files() instead.

kill_all_ltspice()

Deprecated since version 1.0: Use kill_all_spice() instead.

This is only here for compatibility with previous code.

Function to terminate LTSpice

kill_all_spice()

Function to terminate xxSpice processes

property okSim: int

number of successful completed simulations

run(netlist, *, wait_resource=True, callback=None, callback_args=None, switches=None, timeout=None, run_filename=None, callback_on_error=False, exe_log=False)

Executes a simulation run with the conditions set by the user. Conditions are set by the set_parameter, set_component_value or add_instruction functions.

Parameters:

• netlist (str | Path | BaseEditor) – The name of the netlist can be optionally overridden if the user wants to have a better control of how the simulations files are generated.

• wait_resource (bool) – Setting this parameter to False will force the simulation to start immediately, irrespective of the number of simulations already active. By default, the SimRunner class uses only four processors. This number can be overridden by setting the parameter ´parallel_sims´ to a different number. If there are more than ´parallel_sims´ simulations being done, the new one will be placed on hold till one of the other simulations are finished.

• callback (Callable[[...], Any] | type[ProcessCallback] | None) – The user can optionally give a callback function for when the simulation finishes so that processing can be done immediately. The callback can either be a function or a class derived from ProcessCallback. A callback function must receive two at least input parameters that correspond the raw and log files created by the simulation. These need to be the first two parameters of the callback function. The other parameters are passed as a dictionary or a tuple in the callback_args parameter. If the callback is a class derived from ProcessCallback, then the callback is executed in a separate process. The callback function must be defined in the callback() method of the class. As for the callback function, the first two parameters are the raw and log files. The other parameters are passed as dictionary in the callback_args parameter.

• callback_args (tuple | dict | None) – The callback function arguments. This parameter is passed as keyword arguments to the callback function.

• switches (list | None) – Command line switches override

• timeout (float | None) – Timeout to be used in waiting for resources. Default time is value defined in this class constructor.

• run_filename (str | None) – Name to be used for the log and raw file.

• callback_on_error (bool) – If False (default), the callback function is not called if the simulation fails. If True, the callback function is called even if the simulation fails. Know that in that case it is not guaranteed that the raw and log files will be available.

• exe_log (bool) – If True, the simulator’s execution console messages will be written to a log file (named …exe.log) instead of console. This is especially useful when running under wine or when running simultaneous tasks.

Returns:

The task object of type RunTask. For internal use only.

Return type:

RunTask | None

run_now(netlist, *, switches=None, run_filename=None, timeout=None, exe_log=False)

Executes a simulation run with the conditions set by the user. Conditions are set by the set_parameter, set_component_value or add_instruction functions.

Parameters:

• netlist (str | Path | BaseEditor) – The name of the netlist can be optionally overridden if the user wants to have a better control of how the simulations files are generated.

• switches (list) – Command line switches override

• run_filename (str | None) – Name to be used for the log and raw file.

• timeout (float | None) – Timeout to be used in waiting for resources. Default time is value defined in this class constructor.

• exe_log (bool) – If True, the simulator’s execution console messages will be written to a log file (named …exe.log) instead of console. This is especially useful when running under wine or when running simultaneous tasks.

Returns:

the raw and log filenames

Return type:

tuple[Path | None, Path | None]

property runno: int

number of total runs

set_simulator(spice_tool)

Manually overriding the simulator to be used.

Parameters:

spice_tool (type[Simulator]) – String containing the path to the spice tool to be used, or alternatively the Simulator object.

Returns:

Nothing

Return type:

None

sim_info()

Returns a dictionary with detailed information of all completed tasks. It is best to be called after the completion of all tasks.

The dictionary keys are the run numbers. The values are:

• netlist_file: Path to the netlist file

• raw_file: Path to the raw file

• log_file: Path to the log file

• retcode: Return code of the simulator. -2 means an exception was raised, -1 means the simulation is undefined.

• exception_text: Exception information in case of an exception during simulation. None if no exception was raised.

• callback_return: Return value of the callback function. None if no callback was used.

• start_time: Start time of the simulation

• stop_time: Stop time of the simulation

Example: `{ 1: {'netlist_file': 'circuit1.net', 'raw_file': 'circuit1.raw', 'log_file': 'circuit1.log'`, etc….

Returns:

Dictionary with detailed information of all completed tasks.

Return type:

dict

tasks(conditions=None)

Returns an iterator which iterates all completed tasks

Parameters:

conditions (Callable[[RunTask], bool] | dict | None) – Filter to be used in the iterator. See TaskIterator conditions parameter documentation.

Returns:

Iterator[RunTask]

Return type:

Iterator[RunTask]

static validate_callback_args(callback, callback_args)

It validates that the callback_args are matching the callback function. Note that the first two parameters of the callback functions need to be the raw and log files.

wait_completion(timeout=None, abort_all_on_timeout=False)

This function will wait for the execution of all scheduled simulations to complete.

Parameters:

• timeout (float | None) – Cancels the wait after the number of seconds specified by the timeout. This timeout is reset everytime that a simulation is completed. The difference between this timeout and the one defined in the SimRunner instance, is that the latter is implemented by the subprocess class, and this one just cancels the wait.

• abort_all_on_timeout (bool) – attempts to stop all LTSpice processes if timeout is expired.

Returns:

True if all simulations were executed successfully

Return type:

bool