Simmon’s Documentation

class simmon.Monitor(name=None, super_directory=None, enable_output_directory=True, enable_toggles=True)

Monitor and track a simulation. This class collects data from a simulation and stores it in a single output directory. Provides a live view to track the progress of the simulation and a convenience toggle-buttons window.

Parameters:

• name (str, optional) – A name for the Monitor. Also used as the output directory name. By default, the output directory is given a name of the form “S#” where # is the biggest number found in super_directory.

• super_directory (str, optional) – A path to a super directory, in which the output directory for the Monitor is created. The super directory is created if it doesn’t already exist.

• enable_output_directory (bool, optional) – Whether to create an output directory for the Monitor. If False, then this class acts like QuietMonitor.

• enable_toggles (bool, optional) – Whether to open a toggles window for a convenient user control.

_save_config_file()

Save attributes added to this object. These attributes are considered “configurations” and are written to a “config.txt” file.

_save_summary_file()

Save a summary of the Monitor’s run. Includes: - The duration in which the Monitor was up. - A summary of the data files in the output directory.

add_toggle(name='Toggle', desc='Press to toggle')

Add a Toggle to the toggles window.

Parameters:

• name (str, optional) – Toggle name.

• desc (str, optional) – Toggle description.

Returns:

A new Toggle object that has the method toggled().

Return type:

Toggle

close_live_view()

Close the live view.

close_toggles()

Close all toggles. No need if finalize() is called.

finalize()

Save all data tracked by this Monitor. This includes: - Config file - Summary file - Tracker .csv files - Plots It also closes the live view and the toggles window.

load_from_dir(dir_path=None)

Load data stored in a Monitor’s output directory. This can be used to resume a terminated monitored process. The data being loaded is: - Config variables. - Tracker objects including titles.

Parameters:

dir_path (str, optional) – The data is loaded from this directory if provided. Otherwise, data is loaded from self.dir_path.

open_live_view(update_rate=2)

Open a live view of the Monitor in a different process.

Parameters:

update_rate (float, optional) – How many graph updates to perform in a second.

plot(*args)

Plot trackers or groups of trackers in a single figure. This method accepts multiple arguments representing plots, and shows all plots at once.

Parameters:

args (str, Tracker, iterable) – Either titles, Tracker objects, or iterables of Tracker objects.

tracker(ind_var_name, *dep_var_names, title='no_title', autosave=False)

Create a tracker object to track variables. A tracker is associated with one independent variable, and multiple dependent variables.

Parameters:

• ind_var_name (str) – The independent variable name.

• dep_var_names (str) – The dependent variable names.

• title (str, optional) – A title for the trackers. Multiple trackers with the same title will be plotted together.

• autosave (bool, optional) – Enables autosave for the tracker. If True, each update() call appends the data into the output file. This ensures that the data won’t be lost in case of an unexpected termination. Default is False.

Returns:

A tracker object that has an update() method.

Return type:

Tracker

class simmon.QuietMonitor(name=None, enable_toggles=True)

Represents a Monitor with no output files. It is a traceless Monitor, that can be used in cases where the live-view and toggles are useful but there’s no need for an output directory.

Parameters:

• name (str, optional) – An optional name for the Monitor. Can be used to distinguish between multiple running Monitors.

• enable_toggles (bool, optional) – Whether to open a toggles window for a convenient user control.

class simmon.Toggle(main_toggle, name='Toggle', desc='Press to toggle', window_title='Toggle(s)')

This class represents a toggle button. It is supposed to be a helper to Monitor, with which you can add toggles through the add_toggle() method. But it can also work independently. This class has two “modes”: Each object is either the main_toggle, which means that it’s in charge of opening the listening process which opens the window of toggles. Or - it isn’t the main toggle, and then it is joined to a main_toggle. The main toggle’s process accepts new toggles and adds them to its tkinter window. A ‘toggle’ is simply a button that can be pressed by the user as many times as they like. Whenever the user presses the button, a count variable is incremented. When the method toggled() is then invoked, True is returned if the count value is not zero, and the count gets decremented. Thus, the method toggled() returns True for every toggle made by the user. Additionally, Toggle has a toggle_count member that keeps track of all toggles made so far and “discovered” (i.e. toggled() returned True for them). When closing a toggle, its button gets disabled but still appears as long as other toggles are enabled. When all toggles joined in the same window are closed, then the window and listening process are closed.

Parameters:

• main_toggle (Toggle, None) – A main toggle that’s in charge of opening the listening process, which then creates a window and accepts other toggles. If None, then this object would be a main toggle itself.

• name (str, optional) – A name for the Toggle. The name appears on the button.

• desc (str, optional) – A description for the Toggle. The description appears above the button.

• window_title (str, optional) – A title for the toggles window. This is relevant if this toggle is the main_toggle, as it opens the process that opens the window.

_send(data)

Used to send data to the listening process through the instructions Queue.

Parameters:

data – Any data to be sent to the process.

close()

Closes this toggle. If other toggles in the window are still enabled, this toggle’s button will still appear but will become disabled. When all toggles in the window are closed, then the window is closed as well.

toggled()

Returns True for every toggle made by the user. Each time a user presses the toggle, a count is incremented. This method returns True if the count is bigger than 0, and decrements the count.

Returns:

True if the button has been toggled. False if it hasn’t.

Return type:

bool

class simmon.Tracker(monitor: Monitor, _id: float, dir_path: str, ind_var_name: str, *dep_var_names, autosave=False)

This class is a helper to the Monitor class. It tracks variables and communicates with a Monitor object. Creating a Tracker instance is conventionally meant to be done with tracker() method of Monitor.

Parameters:

• monitor (Monitor) – A reference to a Monitor object. This class communicates with the Monitor object and is also referenced from Monitor.

• _id (float) – A unique ID for the Tracker, used to identify data segments sent to the live view process when active. The live view process receives tuples with new data values along with IDs through a Queue. This way it knows where to store the new information (As it has its own copied Trackers).

• dir_path (str) – A path to the directory in which the tracker should save its data. This only truly happens in save(), or if autosave is enabled.

• ind_var_name (str) – The independent variable name this tracker is meant to track.

• dep_var_names (str sequence) – The dependent variable names that are meant to be tracked.

• autosave (bool) – If True, this means that for each update() call, the Tracker will also update the output file with the new data received.

_append_to_out_file(line)

This is a helper to the autosave operation. Appends a line to the output file located at self.path. self.path is only declared if autosave is True. If the file is currently denying permission (potentially because the user opened it in another program), it warns the user, blocks and waits until the operation succeeds.

Parameters:

line (str) – A line to append to the output file located at self.path.

save(_path=None)

Save data to an output file. If autosave is enabled, then default output file is removed.

Parameters:

_path (str, optional) – Path to an output file. If not provided, a filename is a constructed out of the data labels.

update(ind_var, *dep_vars)

Update tracker’s data. If autosave is enabled this data is also appended to the output file associated with this tracker. The data provided here should match the data labels used to create the Tracker: - The number of values should be equal to the number of data labels. - The order of the values should match the order of the data labels, i.e. ind_var, dep_var1, dep_var2 …

Parameters:

• ind_var (float) – A new value for the independent variable.

• dep_vars (float) – New values for all dependent variables.

simmon._create_dir_path(dir_path)

Provided with a path to a directory, this function creates any directory along the path that doesn’t already exist.

Parameters:

dir_path (str) – A path to a directory.

simmon._custom_pause_live_view(interval)

This is a custom pause used for a proper update of the live view figure. This is a solution taken from Stack Overflow.

Parameters:

interval (float) – A pause interval.

simmon._determine_tracker_filename(tracker, dir_path, ending)

Used to determine the filename associated with a Tracker object. This filename is simply a combination of the Tracker’s data labels. If the filename already exist in the output directory, ‘+’s are added to the name to make it unique. This function is used for both output data files, and output plot image files.

Parameters:

• tracker (Tracker) – A Tracker for which a name should be determined.

• dir_path (str) – The path to the output directory in which the file will be saved.

• ending (str) – A file ending, such as ‘.csv’ or ‘.png’.

Returns:

A filename for the Tracker’s output.

Return type:

str

simmon._generate_directory(dir_name, super_directory)

Generates an output directory for a Monitor. This function receives dir_name and super_directory, either can potentially be None. If super_directory is None, it defaults to a path such as sim_records/today’s-date. If dir_name is None, then the directory is given a generic name such as “S#”, where # is one more than the highest number that appears in super_directory.

The output directory is a combination of the two: super_directory/dir_name.

If any of the directories along the path don’t already exist, they are created.

Parameters:

• dir_name (str, None) – A directory name.

• super_directory (str, None) – A super (outer) directory.

Returns:

The constructed path of the generated directory.

Return type:

str

simmon._live_view_process(monitor: Monitor, data_q: Queue, update_rate)

This is the live view process. It creates and updates the live view figure. This process receives a copy of the Monitor object, as well as a Queue for communication and an update rate. When started, the process still doesn’t show anything. When a Tracker in the MAIN process gets updated with new values (aka via tracker.update()), it then sends the new values to this process through the Queue structure, along with the Tracker’s ID. Only then does the live view starts showing its updating plot. This is done so that only currently-updating trackers are plotted in the live view. If another tracker will later get updated as well, it will also be plotted and added to the live view figure. The live view only checks the Queue and updates the plots every once in a while, according to the update_rate, and in the rest of the time - it sleeps. This continues until the main process signals this process to stop. It does so by putting None in the Queue.

Parameters:

• monitor (Monitor) – A monitor clone object (pickled and un-pickled).

• data_q (multiprocessing.Queue) – A data queue for sending new values to the process.

• update_rate (float) – How many updates to perform per second.

simmon._load_to_tracker(tracker, _path)

Loads data from an output .csv file into a Tracker object.

Parameters:

• tracker (Tracker) – A tracker object to load the data into.

• _path (str) – Path to data file.

simmon._monitor_plot(monitor, *args, return_figure_and_axs=False)

Helper to Monitor plot. This functions receives a Monitor object, and arguments specifying what plots to make, and creates a matplotlib figure with all of these plots. It then either shows this figure in a user-interface window, or returns the figure and axs to the caller without opening the UI.

For an explanation of what arguments should be passed with *args, see Monitor.plot().

Parameters:

• args (str, Tracker, iterable) – Either titles, Tracker objects, or iterables of Tracker objects.

• return_figure_and_axs (bool, optional) – If True, a matplotlib figure is returned instead of being displayed, along with an array of axes objects.

Returns:

(optionally) A matplotlib figure, and an array of axs.

Return type:

tuple

simmon._plot_trackers(axes, trackers)

Helper to _monitor_plot. This function shows the graphs of a group of trackers in a single plot.

Parameters:

• axes (matplotlib.Axes) – An axes for the plot.

• trackers (iterable) – A list of trackers.

simmon._redraw_live_view(monitor, prev_figure, trackers)

Helper to the live view process. Whenever new trackers get updated, their plots should be added to the live view figure (see _live_view_process). In this case, a new figure needs to be created.

Parameters:

• monitor (Monitor) – The monitor clone containing the tracker objects.

• prev_figure (matplotlib.Figure) – The previous figure.

• trackers (iterable) – The updated list of trackers to be plotted.

Returns:

A new figure and a list of axes objects.

Return type:

tuple

simmon._refresh_monitor_toggles(monitor)

Helper to handle the default toggles of Monitor. When a Monitor is created, some toggles are added to it by default. These toggles then listen for user presses and remember them. But someone has to take care of what to do when they’re toggled. This function is called in every tracker update of the monitor (see Tracker.update()). It checks if any of the default monitor toggles has been toggled, and if so, it operates accordingly. For example, it opens the live-view if the live-view toggle has been pressed.

Parameters:

monitor (Monitor) – The monitor whose default toggles would be checked.

simmon._toggle_window(in_q, _counts, name, desc, window_title)

Helper to Toggle class. This is the listening process of the Toggles window. This process initially creates a tkinter window, and adds a single toggle button according to its arguments. It then listens to user toggles, and also receives signals from the main process through an instructions-queue. These instructions are of two types: 1. Add a new toggle. This is followed with information about a new toggle button to be added to the window. For an explanation of how and why toggles are added in this way, see Toggle. 2. Close a toggle button. This comes with the ID of the Toggle button to close. When a toggle is closed, its button gets disabled, but it is not removed from the window. When all toggles are closed, then the window is closed and this process terminates.

Additionally, this process takes care of preventing the computer from going into sleep mode. This is done by pressing the harmless ‘shift’ key every once in a while.

Parameters:

• in_q (multiprocessing.Queue) – An instructions-queue used to receive instructions from the main process.

• _counts (numpy.ndarray, list) – An array-like of counts used to keep track of toggles made for each Toggle.

• name (str) – The name of the initial main-toggle.

• desc (str) – Description for the main-toggle.

• window_title (str) – A window title.

simmon._update_live_view_axes(new_data, tracker, axes)

Helper to the live view process. Update a single live-view axes with a single tracker’s plot. This function takes the tracker being plotted, the axes on which it’s done, and the new values added to the data - in order to update the plot with the new values.

Parameters:

• new_data (tuple) – A tuple of new data values.

• tracker (Tracker) – The tracker whose plot needs to get updated. This tracker MUST include the updated values already.

• axes (matplotlib.Axes) – The axes of the plot.