Circuits

Circuit Controller

The circuit controller mediates the interaction between the view class UI_Circuit and the model class QuCircuit.

class ctrl_circuit.Circuit(info, model=None, view=None)

A circuit represents a directed acyclic processing network, where the primary processing units are cells. The Circuit object acts as a controller for the view and model components. The view component handles visual representation while the model component handles calculation and other processing. The controller is responsible for coordinating the communication between model and view.

Parameters:
  • info (CircuitInfo) – Contains circuit meta-data that is needed to create a circuit controller
  • model (QuCircuit) – Optional. Use this parameter to set the model object to an existing instance variable.
  • view (UI_Circuit) – Optional. Supply a value to set the view object that this controller manages.
Variables:
  • info – Contains a reference to a CircuitInfo.
  • model – Contains a reference to a QuCircuit.
  • view – Contains a reference to a UI_Circuit.
  • vertices – A dictionary of cells belonging to this circuit.
  • edges – A list of pipes belonging to this circuit.
  • cells_menu – A dictionary with a nested structure representing the category hierarchy of all available cells.
  • scheduler – Contains a reference to a QuScheduler used to manage the calculation of the circuit.
  • pos – The position of the UI circuit. The UI is an infinite plane and you can position the view at any coordinate.
  • name – The name associated with a particular circuit instance.
  • selected – A list of selected objects based on the current selection mode.
build_add_cmd()

Builds the contextual menu containing all the cell types. It depends on QuCell .categories to supply a list of category hierarchy for each cell.

For example, if the list was ['Math', 'Operators', 'Unary'], then the cell would be listed in Math > Operators > Unary. If the categories don’t exist at build-time, they will be automatically created.

build_context_menu(structure, selection_fn, content=<class 'tuple'>)

Construct the structure of menu widgets by using a recusively defined dict of content.

Parameters:
  • structure – a recursively defined dict. May contain submenus or items.
  • selection_fn – the function to call when a selection is made
  • content – the type of object that represents a selectable item
build_switch_select_cmd()

Creates a context menu that allows you to change the selection mode. The selection mode of a circuit determines which elements you are able to add to the active selection. (i.e. Cells, Pipes, Sockets)

callback_update(*largs)

Internal. Saves the circuit state to graph database.

close()

Closes the circuit.

connect(socket1, socket2)

Creates a pipe between two sockets belonging to cells that exist in the current circuit.

Parameters:
  • socket1 (Socket) – The output socket.
  • socket2 (Socket) – The input socket.
connect_selected()

Connects sockets in the current selection. If there are more than one output sockets in the selection, it will use the first one it finds as the source socket and connect that to all selected input sockets. It will ignore all other output sockets in the selection.

get_selectable_objects()

Provides a list of selectable objects in the circuit based on the selection mode.

Returns:A list of circuit components.
Return type:List
insert(cell)

Insert a new cell into the circuit.

Parameters:cell (Cell) – The cell to insert

Todo

There are 3 functions related to creating a cell: new_cell(), spawn_cell(), insert(). Needs refactor!

listen(pipe)

This is used when a duplicate circuit is running on another processor. It listens for any synchronization data coming from the duplicated circuit and updates the local copy with the new data.

Parameters:pipe (multiprocessing.Pipe) – One end of a communication pipe.
load(circuit_info)

Loads a circuit from the graph database.

Parameters:circuit_info (CircuitInfo) – Contains data neccessary to query database and load the circuit.
new_cell(inst, val)

Adds a new cell to the current circuit’s graph data.

Parameters:
  • inst (object) –
  • val (CmdItem) – Data for creating adding the cell as a new node in the graph database.
recurse_dict(categories, cur)

A helper function that traverses a nested dict based on a list of categories. This is used to organize the Cell add menu into nested categories with add commands at any level of the hierarchy.

Variables:
  • categories – a list of strings that represent a category hierarchy
  • cur – a nested dict of categories.

Note

Parameters categories and cur are modified in place by this function.

New nested dicts and their associated categories as the key will be created if it doesn’t already exist. Once it reaches the lowest level of the list, it will return the dict corresponding to that category.

Example:

>>> structure = {'Math':{'Operators':{'Add':add_command}}}
>>> categories = ['Math', 'Operators']
>>> lowest_level = recurse_dict(categories, structure)
>>> print(lowest_level)
{'Add':add_command}

If the category does not exist, it will be created in cur and an empty dict will be added to the new category. The empty dict will be returned by the function. Continuing with the above example:

>>> recurse_dict(['Math', 'Operators', 'Unary'], structure)
{}
>>> print(structure)
{'Math':{'Operators':{'Add':add_command, 'Unary':{}}}}
remove(elements, **kwargs)

Removes components from the circuit.

Parameters:elements (List) – A list of circuit components. Components must exist in the current circuit and they should be either a Pipe or Cell
remove_cell(cell, **kwargs)

Removes a cell from the circuit.

Parameters:cell (Cell) – A cell that currently exists in the circuit.
remove_pipe(pipe, **kwargs)

Removes a pipe from the circuit.

Parameters:pipe (Pipe) – A connection between cells.
send(pipe)

This is used when the circuit is a duplicate copy of an existing circuit in another processor. While the scheduler is executing the circuit, this method sends any synchronization data through a multiprocessing pipe so that the original copy can update its data.

Parameters:pipe (multiprocessing.Pipe) – One end of a communication pipe.
size_all(*largs, **kwargs)

Loops through all cells in the circuit to refresh their UI.

spawn_cell(cell_info)

Creates all the necessary cell model, controller, and view objects in the circuit using data from the graph database.

Parameters:cell_info (CellInfo) – Data from the graph database needed to create the cell.
stop_cmd()

Interrupt the scheduler and halt further processing.

Circuit UI Elements

This module defines the objects that make up the circuit UI.

class ui_circuit.CmdItem(**kwargs)

An item in a contextual menu that is associated with a callable function.

Parameters:
  • value (String) – The cell’s identifier key in the cell registry.
  • action (callable) – The function to execute.
collide_point(x, y)

A function that tests if a coordinate falls within the widget’s draw boundaries.

Parameters:
  • x (Float) – The x coordinate to test.
  • y (Float) – The y coordinate to test.
Returns:

Whether or not the test passed.
Return type:

bool
on_touch_up(touch)

A touch event handler. It determines how the UI will react to on the up portion of a click or touch.

Parameters:touch (MotionEvent) – The touch data associated with a touch event.
Returns:Whether or not the touch event is passed to the next widget in the widget hierarchy.
Return type:bool
class ui_circuit.QButton(**kwargs)

Defines the look/feel of all buttons

Ival value:The button’s label text.
Ival action:A funcntion to call when the button is pressed.
collide_point(x, y)

Checks if x and y values are within object draw boundaries.

Parameters:
  • x (Integer) – The x coordinate to test.
  • y (Integer) – The y coordinate to test.
Returns:

Whether or not the coordinates fall within the button’s draw boundaries.
Return type:

bool
on_touch_down(touch)

Internal. An event handler for clicks or touches.

Parameters:touch (MotionEvent) – The touch data associated with the event.
Returns:Whether or not the event should be passed on to the next widget in the hierarchy.
Return type:bool
class ui_circuit.UI_Circuit(**kwargs)

This class handles touches and keyboard events related to circuits. It also defines the look/feel of the circuit workspace.

Variables:
  • select_modes – A list of element selection modes supported.
  • select_mode – The currently chosen selection mode.
  • texture – An image representing the grid background.
  • alpha – Alpha transparency value of the grid image.
  • color – Grid color.
  • scale_max – Maximum zoom factor on the circuit.
  • scale_min – Minimum zoom level on the circuit.
  • default_alpha – Alpha level when not in focus.
  • keyboard – A keyboard listener.
  • controller – The controller object assigned to manage this view.
  • kb – A map of hot key assignments.
  • scale – The current zoom factor.
  • is_focusable – Determines whether or not the circuit can capture keyboard focus.
  • unfocus_on_touch – Determines if the circuit will lose focus after a touch is registered outside of it’s collision boundary.
  • focus – Indicates whether or not the circuit currently has keyboard focus.
  • multiselect – Enables or disables shift and ctrl as multiple selection modifiers.
  • do_rotation – Enable or disable circuit rotation.
  • do_scale – Enable or disable zooming.
  • last_pos – The circuit position to save when Quantum quits.
  • spawn_menu_pos – A list or tuple having coordinates for where to spawn a context menu
  • window_size – A tuple representing width and height of window.
  • mouse_pos – Mouse position in window coordinates.
build_keyboard()

Configures the KeyboardMap which controls circuit shortcuts.

Todo

Document shortcuts in User Guide.

connect_sockets()

Connect two or more selected cell sockets.

delete_selected()

Delete one or more selected cells from the circuit.

deselect_node(node)

Internal. This handles deselect events.

Parameters:node (Widget) – The UI object to deselect
focus_event(inst, val)

Internal. Handles the focus event.

get_selectable_nodes()

Internal. This determines what can and cannot be selected. This is primarily used by Kivy. We simply provide a list to Kivy containing the objects we wish to allow for selection.

Returns:A list of widgets that will be allowed to be selected.
Return type:List
keyboard_on_key_down(keyboard, keycode, codepoint, modifiers)

Internal. Handles key press events.

keyboard_on_key_up(keyboard, keycode)

Internal. Handles key press events.

mouse_to_local()

Converts the mouse position in window coordinates to circuit coordinates.

Returns:Mouse position in local coordinates.
Return type:List
on_touch_down(touch)

Internal. Handles touch (click) events.

on_touch_up(touch)

Internal. Handles touch up (unclick) events.

open_cell_menu()

Brings up the contextual menu allowing you to select a new cell for insertion into the circuit.

open_select_menu()

Brings up a contextual menu allowing you to change the selection mode.

select_node(node)

Internal. This handles selection events. It permits the selection of various circuit components.

Parameters:node (Widget) – The UI object to select
stop_running()

Interrupts a currently running circuit.

updt_canvas(inst, val)

Internal. A handler for redrawing the canvas. It is meant to be bound to changes that would require a redraw like changing window size.

class ui_circuit.UI_Context_Cmd(cmd_items, **kwargs)

This object is used to represent various contextual menus. This class may contain children that are separate instances of UI_Context_Cmd to define a menu with nested submenus.

Parameters:
  • cmd_items (List) – A list containing a mix of UI_Context_Cmd or a tuple in the form (item, value) where item is a string that acts as parameters for creating a new CmdItem.
  • selection (CmdItem) – The most recently clicked command.
hide()

Hide the menu.

show(x=None, y=None)

Show the menu.

Variables:
  • x – x screen coordinate where menu is to be displayed.
  • y – y screen coordinate where menu is to be displayed.
updt_children(inst, val)

Internal. An event handling method that is bound to the cmd_items. When cmd_items change, this function is called. This allows the context menu content to be controlled by the cmd_items list attribute by keeping the menu in sync with the list contents.

updt_selection(inst)

Internal. An event handling method that is bound to each CmdItem in the context menu. Whenever a selction happens, this function is called.

Cells

Cell Controller

Cells are the basic building blocks of a graph processing network. The cell controller mediates interaction between cell models provided by QuCell and cell ui representations provided by UI_Cell. QuCell provides the processing function while UI_Cell handles the user interaction and response. The cell controller allows for the coordination between user input, process calculation, and ui response.

class ctrl_cell.Cell(info, circuit)

A Cell represents a processing unit within a network graph. This class is the controller in a model-view-controller design pattern.

Parameters:
  • info (CellInfo) – Corresponding vertex data from the graph database that represents the cell being instanced.
  • circuit (Circuit) – The circuit that will own the new cell.
Variables:
  • i – A dict of input sockets owned by the cell.
  • o – A dict of output sockets owned by the cell.
  • i_obsrv –
  • i_text – Contains SocketInputs for each key.
  • parent – The parent of the cell.
  • refresh_triggers –
  • inner_grid – A reference to the inner contents of the cell’s ui elements.
  • factory – A factory that can generate cell ui parts.
  • assembler – An assembler that can put together cell parts to form a cell.
  • view – The cell’s visual representation.
  • selectable – A boolean value that indicates whether or not the cell can be added to the selection list.
  • tgt_width – The target width of the cell’s ui.
auto_size(dt=0.1)

Sets the size of the cell depending on a target width.

read_input(inst, val)

Event handler for changes to SocketInput fields. It inserts values into the cell’s QuCellSockets based on what the user has input.

Parameters:
  • inst (SocketInput) – The SocketInput that has changed value.
  • val (object) – The new value.
readonly_input(event, **kwargs)

Makes input labels readonly and changes styling appropriately

Parameters:event (QuEvent) – An event associated with the function call.
reset_color()

Change the cell color back to default.

save_info(inst=None, val=None)

Serializes cell info into graph database.

update(e)

Directs the cell’s ui to present various changes depending on the type of event associated with the function call.

Parameters:e (QuEvent) – An event associated with the call to update.
width_changed(inst, val)

Internal. An event handler that is meant to be bound to the cell’s width property.

Cell UI Elements

The components that make up a cell’s user interface are defined in this module. These components include the UI_Cell which represents visual elements and functionality common to all cells. This includes blink colors, default colors, configuration options, and event handlers. Another important component is the UI_Cell_Inner. This component encapuslates the portion of the cell that will vary from one cell to another. We also define the cell socket labels in this module since those are part of the cell inner due to the way we arrange the layout of the cell ui components. For inputs, we use SocketInput for most cases but we also define DropDownItem for times when we need restricted options. For outputs we use SocketOutput.

class ui_cell.DropDownItem(font_size='11sp', **kwargs)

A type of button that is used as a dropdown selection menu.

Parameters:font_size (Kivy Units) – The size of font. Use kivy units. (i.e. ‘11sp’ or ‘20px’ etc.)
class ui_cell.SocketInput(font_size='11sp', **kwargs)

A textbox object used to label inputs. Since users can also manually enter values into inputs, we use text boxes rather than labels.

Parameters:font_size (Kivy Units) – The size of font. Use kivy units. (i.e. ‘11sp’ or ‘20px’ etc.)
class ui_cell.SocketOutput(font_size='11sp', **kwargs)

A label object used for socket output names.

Parameters:font_size (Kivy Units) – The size of font. Use kivy units. (i.e. ‘11sp’ or ‘20px’ etc.)
class ui_cell.UI_Cell(title='DEFAULT', controller=None, **kwargs)

This class defines the layout of elements within a cell as well as selection behavior.

Parameters:
  • title (String) – The title of the cell.
  • controller (Cell) – The cell’s controller.
Variables:
  • text – Unused
  • rspace – width of right column containing output socket icons.
  • lspace – width of left column containing input socket icons.
  • select_color – The color indicating selection.
  • default_color – The default foreground color.
  • normal_color – The normal foreground color of a cell. This overrides the default color. The purpose is to allow different cell types to have different normal colors.
  • curr_bg_color – The current background color of the cell.
  • blink_on_color – The blink on color of the cell.
  • blink_off_color – The blink off color of the cell.
  • stop_color – The color of the cell when it finishes processing.
  • error_color – The color of a cell if it encounters an error.
  • ambiguous_color – The color of the cell if it did not process successfully, but there was no error.
  • curr_color – The current color of the cell.
  • being_touched – Indicates if the cell is currently being clicked on.
  • cell_pickers – Used by the parent Themeable to build the appropriate settings interface. It maps attribute keys to a label and description tuple.
  • cell_attribs – Used by the parent Themeable to build the appropriate settings interface. It maps attribute keys to their corresponding variable names in the cell instance.
  • close – The ui of a cell is deleted from runtime if either the user wishes to delete the cell from the circuit or if the circuit is closed, in which case, the cell should not actually be deleted from the database. In this case, the cell should only be removed from ui. This variable is set prior to ui deletion to indicate to the controller whether or not the cell should also be deleted from the database. If close is True, then the ui deletion represents a closure of the circuit and the cell will not be deleted from the database.
blinker(*args, blink_on_color=None, blink_off_color=None)

Toggles the cell color between blink on and blink off.

Parameters:
  • blink_on_color (Color) – The blink on color to use.
  • blink_off_color (Color) – The blink off color to use.
delete(close=True)

Requests the cell to be deleted from UI.

Parameters:close (bool) – Indicates if deletion request is due to closing circuit, in which case, the cell should not be deleted from database.
on_deleted(*args)

Internal. Monitors and responds to cell deletion requests.

on_deselect()

Handles visual changes upon user de-select.

on_process()

Internal. Handles visual changes to indicate that the cell is processing.

on_select()

Internal. Handles visual changes upon user selection.

on_stopped()

Internal. Handles visual changes to indicate that the cell has stopped processing.

on_touch_down(touch)

Internal. Handles a touch down event.

Parameters:touch (MotionEvent) – The touch event data associated with the function call.
on_touch_up(touch)

Internal. Handles a touch up event.

Parameters:touch (MotionEvent) – The touch event data associated with the function call.
on_unknown()

Internal. Handles visual changes that indicate an unknown error has occured during processing.

class ui_cell.UI_Cell_Inner(**kwargs)

This class defines the ui behavior of the primary visible portion of a cell. This includes the title bar and socket labels arranged as a horizontal BoxLayout.

Parameters:
  • curr_bg_color (List) – Color of background elements.
  • curr_color (List) – Color of foreground elements.

Sockets

Socket controller

This is the controller in a model-view-controller pattern. Sockets are the parts of a cell that send and recieve data. The controller keeps track of what cell a socket belongs, sends data to the underlying socket model, manages the ui, as well as whether or not a socket can be selected based on the current selection mode.

class ctrl_socket.Socket(cell, model, key)

Controller object for QuCellSocket and UI_Socket. Sockets are the inputs, outputs, and parameters of a Quantum Cell that can be manipulated by the user.

Parameters:
  • cell (Cell) – A reference to the parent cell controller.
  • model (QuCellSocket) – A reference to the underlying socket model which does the job of storing and retrieving data.
  • key (String) – The unique string that identifies the particular socket in a QuCellSockets collection.
Variables:
  • view – The socket’s ui representation.
  • model – The underlying model.
  • key – The string identifier that can be used to lookup the socket in the parent cell’s collection of sockets.
  • cell – The parent cell controller
  • selectable – A readonly property that determines if the socket can be added to the current selection.
update(e)

Internal. An event handler that determines how the socket behaves when it recieves different types of events.

Parameters:e (QuEvent) – The event associated with the function call.

Socket UI Elements

Socket UI objects are represented as a label. It is drawn to screen using an icon font.

class ui_socket.UI_Socket(controller, font_size='11sp', **kwargs)

This class handles the look/feel of cell sockets in the ui.

Parameters:
  • controller (Socket) – A socket controller that will be assigned to manage this instance of the ui.
  • font_size (Kivy Units) – The font size to render. Use Kivy font units.
Variables:
  • icon – A single character from an icon font.
  • markup – A boolean that determines whether or not the rendering of the font can accept bb code.
  • text – The icon surrounded by bb code which determines the render color.
  • controller – A reference to the socket controller.
  • font_size – The current font size.
  • center_pos – The absolute window position of the center of the socket ui. Used to draw pipes that originate from the center of one socket and terminates at the center of another socket.
  • curr_color – The current color of the socket ui.
  • type_color – The normal color of the socket based on the underlying data type.
  • select_color – The color the socket will change to when it is selected.
on_deselect()

Internal. Bound to the deselect event. Handles what happens when the socket is deselected.

on_select()

Internal. Bound to the select event. Handles what happens when the socket is selected.

on_touch_down(touch)

Internal. Handles touch events.

Parameters:touch (MotionEvent) – The data associated with the touch (click).
updt_text(inst, val)

Internal. Used to update the bb code when the curr_color changes.

Pipes

Pipe Controller

Pipes represent the communication channel between two sockets.

class ctrl_pipe.Pipe(info, circuit)

This is a Pipe controller. It manages the visual and model representations of pipes between cell nodes.

Parameters:
  • info (PipeInfo) – Data describing the pipe
  • circuit (Circuit) – a circuit object where the pipe is to be created
Variables:
  • info – The data associated with the pipe.
  • view – This is the visual representation of the pipe.
  • src – The output socket containing values to be sent through the pipe.
  • tgt – The input socket that will recieve values sent through the pipe.
selectable

Determines if the pipe can be added to the selection based on the current selection mode.

tgt_update(event)

Internal. A callback that reacts to any changes in the target cell.

Parameters:event (QuEvent) – The event data associated with the function call.

Todo

Doesn’t work.

Pipe UI Elements

These objects manage the visual properties of the connection between two cells in the user interface.

class ui_pipe.UI_Pipe(controller, src_ui, tgt_ui, **kwargs)

UI_Pipe draws the line that connects two cell sockets.

Parameters:
  • controller (Pipe) – A controller object that will be assigned to manage this UI object.
  • src_ui (UI_Socket) – A reference to the socket ui at the originating end of the connection.
  • tgt_ui (UI_Socket) – A reference to the socket ui at the terminating end of the connection.
Variables:
  • src_ui – The source socket ui object.
  • tgt_ui – The target socket ui object.
  • select_color – A setting variable that determines the color of the ui when connection is in the current selection.
  • normal_color – A setting variable that determines the color of the ui when the connection is not in the current selection.
  • curr_color – A variable that determines the current color displayed.
  • controller – The object that provides instructions to UI_Pipe for how to represent the connection on screen.
collide_point(x, y)

Determines the coordinates in which a touch (click) even registers as belonging to this connection.

Todo

Currently, this is the entire rectangle that encloses the line. However, this is mostly empty space as the line that is drawn goes from one corner of the box to the other. This function should be updated so that the collision doesn’t register when you click in the empty space.

on_deselect()

Internal. Determines what happens when the connection is removed from the current selection.

on_execute()

Internal. Determines what happens when the cell at the terminating end of the connection is executing.

on_select()

Internal. Determines what happens when the connection is added to the current selection.

on_touch_down(touch)

Internal. A callback that handles touch (click) events.

Parameters:touch (MotionEvent) – The data associated with the touch.
update_pos(inst=None, val=None)

Internal. A callback that sets the position of the connection ui. This should line up so that one end of the line begins at the position of src_ui and ends at the position of tgt_ui. It is a callback because the position will need to change when either the src_ui or tgt_ui changes position.

update_tr(inst=None, val=None)

Internal. A callback that sets the size of the connection ui. This should line up so that one end of the line begins at the position of src_ui and ends at the position of tgt_ui. It is a callback because the position will need to change when either the src_ui or tgt_ui changes position.