Reference

3D Animation

class salabim.Animate3dBase(visible: bool = True, keep: bool = True, arg: Any = None, layer: float = 0, parent: Component = None, env: Environment = None, **kwargs)

Base class for a 3D animation object

When a class inherits from this base class, it will be added to the animation objects list to be shown

Parameters:
  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default True)

  • layer (int) –

    layer value

    lower layer values are displayed later in the frame (default 0)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • env (Environment) –

    environment where the component is defined

    if omitted, default_env will be used

remove() None

removes the 3d animation oject

setup() None

called immediately after initialization of a the Animate3dBase object.

by default this is a dummy method, but it can be overridden.

only keyword arguments will be passed

Example

class AnimateVehicle(sim.Animate3dBase):
def setup(self, length):

self.length = length self.register_dynamic_attributes(“length”)

show(unremove)

It is possible to use this method if already shown

class salabim.Animate3dBox(x_len: float | Callable = 1, y_len: float | Callable = 1, z_len: float | Callable = 1, x: float | Callable = 0, y: float | Callable = 0, z: float | Callable = 0, z_angle: float | Callable = 0, x_ref: float | Callable = 0, y_ref: float | Callable = 0, z_ref: float | Callable = 0, color: str | Iterable[float] | Callable = 'white', edge_color: str | Iterable[float] | Callable = '', shaded: bool | Callable = False, visible: bool | Callable = True, arg: Any = None, layer: float | Callable = 0, parent: Component = None, env: Environment = None, **kwargs)

Creates a 3D box

Parameters:
  • x_len (float) – length of the box in x direction (deffult 1)

  • y_len (float) – length of the box in y direction (default 1)

  • z_len (float) – length of the box in z direction (default 1)

  • x (float) – x position of the box (default 0)

  • y (float) – y position of the box (default 0)

  • z (float) – z position of the box (default 0)

  • z_angle (float) – angle around the z-axis (default 0)

  • x_ref (int) –

    if -1, the x parameter refers to the ‘end’ of the box

    if 0, the x parameter refers to the center of the box (default)

    if 1, the x parameter refers to the ‘start’ of the box

  • y_ref (int) –

    if -1, the y parameter refers to the ‘end’ of the box

    if 0, the y parameter refers to the center of the box (default)

    if 1, the y parameter refers to the ‘start’ of the box

  • z_ref (int) –

    if -1, the z parameter refers to the ‘end’ of the box

    if 0, the z parameter refers to the center of the box (default)

    if 1, the z parameter refers to the ‘start’ of the box

  • color (colorspec) –

    color of the box (default “white”)

    if the color is “” (or the alpha is 0), the sides will not be colored at all

  • edge_color (colorspec) –

    color of the edges of the (default “”)

    if the color is “” (or the alpha is 0), the edges will not be drawn at all

  • shaded (bool) – if False (default), all sides will be colored with color if True, the various sides will have a sligtly different darkness, thus resulting in a pseudo shaded object

  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default True)

  • layer (int) –

    layer value

    lower layer values are displayed later in the frame (default 0)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • env (Environment) –

    environment where the component is defined

    if omitted, default_env will be used

Note

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: my_x

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.Animate3dCylinder(x0: float | Callable = 0, y0: float | Callable = 0, z0: float | Callable = 0, x1: float | Callable = 1, y1: float | Callable = 1, z1: float | Callable = 1, color: str | Iterable[float] | Callable = 'white', radius: float | Callable = 1, number_of_sides: int | Callable = 8, rotation_angle: float | Callable = 0, show_lids: bool | Callable = True, visible: bool | Callable = True, arg: Any = None, layer: float | Callable = 0, parent: Component = None, env: Environment = None, **kwargs)

Creates a 3D cylinder between two given points

Parameters:
  • x0 (float) – x coordinate of start point (default 0)

  • y0 (float) – y coordinate of start point (default 0)

  • z0 (float) – z coordinate of start point (default 0)

  • x1 (float) – x coordinate of end point (default 0)

  • y1 (float) – y coordinate of end point (default 0)

  • z1 (float) – z coordinate of end point (default 0)

  • color (colorspec) – color of the cylinder (default “white”)

  • radius (float) – radius of the cylinder (default 1)

  • number_of_sides (int) –

    number of sides of the cylinder (default 8)

    must be >= 3

  • rotation_angle (float) – rotation of the bar in degrees (default 0)

  • show_lids (bool) – if True (default), the lids will be drawn if False, tyhe cylinder will be open at both sides

  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default True)

  • layer (int) –

    layer value

    lower layer values are displayed later in the frame (default 0)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • env (Environment) –

    environment where the component is defined

    if omitted, default_env will be used

Note

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: my_x

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.Animate3dGrid(x_range: Iterable[float] | Callable = [0], y_range: Iterable[float] | Callable = [0], z_range: Iterable[float] | Callable = [0], color: str | Iterable[float] | Callable = 'white', visible: bool | Callable = True, arg: Any = None, layer: float | Callable = 0, parent: Component = None, env: Environment = None, **kwargs)

Creates a 3D grid

Parameters:
  • x_range (iterable) – x coordinates of grid lines (default [0])

  • y_range (iterable) – y coordinates of grid lines (default [0])

  • z_range (iterable) – z coordinates of grid lines (default [0])

  • color (colorspec) – color of the line (default “white”)

  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default True)

  • layer (int) –

    layer value

    lower layer values are displayed later in the frame (default 0)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • env (Environment) –

    environment where the component is defined

    if omitted, default_env will be used

Note

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: my_x

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.Animate3dLine(x0: float | Callable = 0, y0: float | Callable = 0, z0: float | Callable = 0, x1: float | Callable = 1, y1: float | Callable = 1, z1: float | Callable = 0, color: str | Iterable[float] | Callable = 'white', visible: bool | Callable = True, arg: Any = None, layer: float | Callable = 0, parent: Component = None, env: Environment = None, **kwargs)

Creates a 3D line

Parameters:
  • x0 (float) – x coordinate of start point (default 0)

  • y0 (float) – y coordinate of start point (default 0)

  • z0 (float) – z coordinate of start point (default 0)

  • x1 (float) – x coordinate of end point (default 0)

  • y1 (float) – y coordinate of end point (default 0)

  • z1 (float) – z coordinate of end point (default 0)

  • color (colorspec) – color of the line (default “white”)

  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default True)

  • layer (int) –

    layer value

    lower layer values are displayed later in the frame (default 0)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • env (Environment) –

    environment where the component is defined

    if omitted, default_env will be used

Note

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: my_x

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.Animate3dObj(filename: str | Callable, x: float | Callable = 0, y: float | Callable = 0, z: float | Callable = 0, x_angle: float | Callable = 0, y_angle: float | Callable = 0, z_angle: float | Callable = 0, x_translate: float | Callable = 0, y_translate: float | Callable = 0, z_translate: float | Callable = 0, x_scale: float | Callable = 1, y_scale: float | Callable = 1, z_scale: float | Callable = 1, show_warnings: bool | Callable = False, visible: bool | Callable = True, arg: Any = None, layer: float | Callable = 0, parent: Component = None, env: Environment = None, **kwargs)

Creates a 3D animation object from an .obj file

Parameters:
  • filename (str or Path) –

    obj file to be read (default extension .obj)

    if there are .mtl or .jpg required by this file, they should be available

  • x (float) – x position (default 0)

  • y (float) – y position (default 0)

  • z (float) – z position (default 0)

  • x_angle (float) – angle along x axis (default: 0)

  • y_angle (float) – angle along y axis (default: 0)

  • z_angle (float) – angle along z axis (default: 0)

  • x_translate (float) – translation in x direction (default: 0)

  • y_translate (float) – translation in y direction (default: 0)

  • z_translate (float) – translation in z direction (default: 0)

  • x_scale (float) – scaling in x direction (default: 1)

  • y_translate – translation in y direction (default: 1)

  • z_translate – translation in z direction (default: 1)

  • show_warnings (bool) –

    as pywavefront does not support all obj commands, reading the file sometimes leads to (many) warning log messages

    with this flag, they can be turned off (the deafult)

  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default True)

  • layer (int) –

    layer value

    lower layer values are displayed later in the frame (default 0)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • env (Environment) –

    environment where the component is defined

    if omitted, default_env will be used

Note

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: my_x

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

Note

This method requires the pywavefront and pyglet module to be installed

class salabim.Animate3dQueue(queue: Queue, x: float | Callable = 0, y: float | Callable = 0, z: float | Callable = 0, direction: str | Callable = 'x+', max_length: int | Callable = None, reverse: bool | Callable = False, layer: int | Callable = 0, id: Any | Callable = None, arg: Any = None, parent: Component = None, visible: bool | Callable = True, keep: bool | Callable = True)

Animates the component in a queue.

Parameters:
  • queue (Queue) –

  • x (float) –

    x-position of the first component in the queue

    default: 0

  • y (float) –

    y-position of the first component in the queue

    default: 0

  • z (float) –

    z-position of the first component in the queue

    default: 0

  • direction (str) –

    if “x+”, waiting line runs in positive x direction (default)

    if “x-”, waiting line runs in negative x direction

    if “y+”, waiting line runs in positive y direction

    if “y-”, waiting line runs in negative y direction

    if “z+”, waiting line runs in positive z direction

    if “z-”, waiting line runs in negative z direction

reversebool

if False (default), display in normal order. If True, reversed.

max_lengthint

maximum number of components to be displayed

layerint

layer (default 0)

idany

the animation works by calling the animation_objects method of each component, optionally with id. By default, this is self, but can be overriden, particularly with the queue

argany

this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

default: self (instance itself)

visiblebool

if False, nothing will be shown

(default True)

keepbool

if False, animation object will be taken from the animation objects. With show(), the animation can be reshown. (default True)

parentComponent

component where this animation object belongs to (default None)

if given, the animation object will be removed automatically when the parent component is no longer accessible

Note

All parameters, apart from queue, id, arg and parent can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

queue()
Returns:

the queue this object refers to. Can be useful in Component.animation3d_objects

Return type:

queue

show(unremove)

It is possible to use this method if already shown

class salabim.Animate3dRectangle(x0: float | Callable = 0, y0: float | Callable = 0, x1: float | Callable = 1, y1: float | Callable = 1, z: float | Callable = 0, color: str | Iterable[float] | Callable = 'white', visible: bool | Callable = True, arg: Any = None, layer: float | Callable = 0, parent: Component = None, env: Environment = None, **kwargs)

Creates a 3D rectangle

Parameters:
  • x0 (float) – lower left x position (default 0)

  • y0 (float) – lower left y position (default 0)

  • x1 (float) – upper right x position (default 1)

  • y1 (float) – upper right y position (default 1)

  • z (float) – z position of rectangle (default 0)

  • color (colorspec) – color of the rectangle (default “white”)

  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default True)

  • layer (int) –

    layer value

    lower layer values are displayed later in the frame (default 0)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • env (Environment) –

    environment where the component is defined

    if omitted, default_env will be used

Note

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: my_x

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

Animation

class salabim.Animate(parent: Component = None, layer: float = 0, keep: bool = True, visible: bool = True, screen_coordinates: bool = None, t0: float = None, x0: float = 0, y0: float = 0, offsetx0: float = 0, offsety0: float = 0, circle0: float | Iterable = None, line0: Iterable[float] = None, polygon0: Iterable[float] = None, rectangle0: Iterable[float] = None, points0: Iterable[float] = None, image: Any = None, text: str = None, font: str | Iterable[str] = '', anchor: str = 'c', as_points: bool = False, max_lines: int = 0, text_anchor: str = None, linewidth0: float = None, fillcolor0: str | Iterable[float] = None, linecolor0: str | Iterable[float] = 'fg', textcolor0: str | Iterable[float] = 'fg', angle0: float = 0, alpha0: float = 255, fontsize0: float = 20, width0: float = None, t1: float = None, x1: float = None, y1: float = None, offsetx1: float = None, offsety1: float = None, circle1: float | Iterable[float] = None, line1: Iterable[float] = None, polygon1: Iterable[float] = None, rectangle1: Iterable[float] = None, points1: Iterable[float] = None, linewidth1: float = None, fillcolor1: str | Iterable[float] = None, linecolor1: str | Iterable[float] = None, textcolor1: str | Iterable[float] = None, angle1: float = None, alpha1: float = None, fontsize1: float = None, width1: float = None, xy_anchor: str = '', over3d: bool = None, flip_horizontal: bool = False, flip_vertical: bool = False, animation_start: float = None, animation_speed: float = 1, animation_repeat: bool = False, animation_pingpong: bool = False, animation_from: float = 0, animation_to: float = inf, env: Environment = None)

defines an animation object

Parameters:
  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • layer (int) –

    layer value

    lower layer values are on top of higher layer values (default 0)

  • keep (bool) –

    keep

    if False, animation object is hidden after t1, shown otherwise (default True)

  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default True)

  • screen_coordinates (bool) –

    use screen_coordinates

    normally, the scale parameters are use for positioning and scaling objects.

    if True, screen_coordinates will be used instead.

  • xy_anchor (str) –

    specifies where x and y (i.e. x0, y0, x1 and y1) are relative to

    possible values are (default: sw)

    nw    n    ne
    w     c     e
    sw    s    se
    

    If null string, the given coordimates are used untranslated

  • t0 (float) – time of start of the animation (default: now)

  • x0 (float) – x-coordinate of the origin at time t0 (default 0)

  • y0 (float) – y-coordinate of the origin at time t0 (default 0)

  • offsetx0 (float) – offsets the x-coordinate of the object at time t0 (default 0)

  • offsety0 (float) – offsets the y-coordinate of the object at time t0 (default 0)

  • circle0 (float or tuple/list) –

    the circle spec of the circle at time t0

    • radius

    • one item tuple/list containing the radius

    • five items tuple/list cntaining radius, radius1, arc_angle0, arc_angle1 and draw_arc

    (see class AnimateCircle for details)

  • line0 (list or tuple) – the line(s) (xa,ya,xb,yb,xc,yc, …) at time t0

  • polygon0 (list or tuple) –

    the polygon (xa,ya,xb,yb,xc,yc, …) at time t0

    the last point will be auto connected to the start

  • rectangle0 (list or tuple) – the rectangle (xlowerleft,ylowerleft,xupperright,yupperright) at time t0

  • image (str, pathlib.Path or PIL image) –

    the image to be displayed

    This may be either a filename or a PIL image

  • text (str, tuple or list) –

    the text to be displayed

    if text is str, the text may contain linefeeds, which are shown as individual lines

  • max_lines (int) –

    the maximum of lines of text to be displayed

    if positive, it refers to the first max_lines lines

    if negative, it refers to the first -max_lines lines

    if zero (default), all lines will be displayed

  • font (str or list/tuple) –

    font to be used for texts

    Either a string or a list/tuple of fontnames. If not found, uses calibri or arial

  • anchor (str) –

    anchor position

    specifies where to put images or texts relative to the anchor point

    possible values are (default: c)

    nw    n    ne
    w     c     e
    sw    s    se
    

  • as_points (bool) –

    if False (default), lines in line, rectangle and polygon are drawn

    if True, only the end points are shown in line, rectangle and polygon

  • linewidth0 (float) –

    linewidth of the contour at time t0 (default 0 for polygon, rectangle and circle, 1 for line)

    if as_point is True, the default size is 3

  • fillcolor0 (colorspec) –

    color of interior at time t0 (default foreground_color)

    if as_points is True, fillcolor0 defaults to transparent

  • linecolor0 (colorspec) – color of the contour at time t0 (default foreground_color)

  • textcolor0 (colorspec) – color of the text at time 0 (default foreground_color)

  • angle0 (float) – angle of the polygon at time t0 (in degrees) (default 0)

  • alpha0 (float) – alpha of the image at time t0 (0-255) (default 255)

  • fontsize0 (float) – fontsize of text at time t0 (default 20)

  • width0 (float) –

    width of the image to be displayed at time t0

    if omitted or None, no scaling

  • t1 (float) –

    time of end of the animation (default inf)

    if keep=True, the animation will continue (frozen) after t1

  • x1 (float) – x-coordinate of the origin at time t1(default x0)

  • y1 (float) – y-coordinate of the origin at time t1 (default y0)

  • offsetx1 (float) – offsets the x-coordinate of the object at time t1 (default offsetx0)

  • offsety1 (float) – offsets the y-coordinate of the object at time t1 (default offsety0)

  • circle1 (float or tuple/list) –

    the circle spec of the circle at time t1 (default: circle0)

    • radius

    • one item tuple/list containing the radius

    • five items tuple/list cntaining radius, radius1, arc_angle0, arc_angle1 and draw_arc

    (see class AnimateCircle for details)

  • line1 (tuple) –

    the line(s) at time t1 (xa,ya,xb,yb,xc,yc, …) (default: line0)

    should have the same number of elements as line0

  • polygon1 (tuple) –

    the polygon at time t1 (xa,ya,xb,yb,xc,yc, …) (default: polygon0)

    should have the same number of elements as polygon0

  • rectangle1 (tuple) – the rectangle (xlowerleft,ylowerleft,xupperright,yupperright) at time t1 (default: rectangle0)

  • linewidth1 (float) – linewidth of the contour at time t1 (default linewidth0)

  • fillcolor1 (colorspec) – color of interior at time t1 (default fillcolor0)

  • linecolor1 (colorspec) – color of the contour at time t1 (default linecolor0)

  • textcolor1 (colorspec) – color of text at time t1 (default textcolor0)

  • angle1 (float) – angle of the polygon at time t1 (in degrees) (default angle0)

  • alpha1 (float) – alpha of the image at time t1 (0-255) (default alpha0)

  • fontsize1 (float) – fontsize of text at time t1 (default: fontsize0)

  • width1 (float) – width of the image to be displayed at time t1 (default: width0)

  • over3d (bool) –

    if True, this object will be rendered to the OpenGL window

    if False (default), the normal 2D plane will be used.

Note

one (and only one) of the following parameters is required:

  • circle0

  • image

  • line0

  • polygon0

  • rectangle0

  • text

colors may be specified as a

  • valid colorname

  • hexname

  • tuple (R,G,B) or (R,G,B,A)

  • “fg” or “bg”

colornames may contain an additional alpha, like red#7f

hexnames may be either 3 of 4 bytes long (#rrggbb or #rrggbbaa)

both colornames and hexnames may be given as a tuple with an additional alpha between 0 and 255, e.g. (255,0,255,128), (“red”,127)`` or ("#ff00ff",128)

fg is the foreground color

bg is the background color

Permitted parameters

parameter

circle

image

line

polygon

rectangle

text

parent

layer

keep

screen_coordinates

xy_anchor

t0,t1

x0,x1

y0,y1

offsetx0,offsetx1

offsety0,offsety1

circle0,circle1

image

line0,line1

polygon0,polygon1

rectangle0,rectangle1

text

anchor

linewidth0,linewidth1

fillcolor0,fillcolor1

linecolor0,linecolor1

textcolor0,textcolor1

angle0,angle1

alpha0,alpha1

as_points

font

fontsize0,fontsize1

width0,width1

alpha(t=None)

alpha of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

alpha – default behaviour: linear interpolation between self.alpha0 and self.alpha1

Return type:

float

anchor(t=None)

anchor of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

anchor – default behaviour: self.anchor0 (anchor given at creation or update)

Return type:

str

angle(t=None)

angle of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

angle – default behaviour: linear interpolation between self.angle0 and self.angle1

Return type:

float

as_points(t=None)

as_points of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

as_points – default behaviour: self.as_points (text given at creation or update)

Return type:

bool

circle(t=None)

circle of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

circle – either

  • radius

  • one item tuple/list containing the radius

  • five items tuple/list cntaining radius, radius1, arc_angle0, arc_angle1 and draw_arc

(see class AnimateCircle for details)

default behaviour: linear interpolation between self.circle0 and self.circle1

Return type:

float or tuple/list

fillcolor(t=None)

fillcolor of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

fillcolor – default behaviour: linear interpolation between self.fillcolor0 and self.fillcolor1

Return type:

colorspec

font(t=None)

font of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

font – default behaviour: self.font0 (font given at creation or update)

Return type:

str

fontsize(t=None)

fontsize of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

fontsize – default behaviour: linear interpolation between self.fontsize0 and self.fontsize1

Return type:

float

image(t=None)

image of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

image – default behaviour: self.image0 (image given at creation or update)

Return type:

PIL.Image.Image

keep(t)

keep attribute of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

keep – default behaviour: self.keep0 or t <= self.t1 (visible given at creation or update)

Return type:

bool

layer(t=None)

layer of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

layer – default behaviour: self.layer0 (layer given at creation or update)

Return type:

int or float

line(t=None)

line of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

line – series of x- and y-coordinates (xa,ya,xb,yb,xc,yc, …)

default behaviour: linear interpolation between self.line0 and self.line1

Return type:

tuple

linecolor(t=None)

linecolor of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

linecolor – default behaviour: linear interpolation between self.linecolor0 and self.linecolor1

Return type:

colorspec

linewidth(t=None)

linewidth of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

linewidth – default behaviour: linear interpolation between self.linewidth0 and self.linewidth1

Return type:

float

max_lines(t=None)

maximum number of lines to be displayed of text. May be overridden.

Parameters:

t (float) – current time

Returns:

max_lines – default behaviour: self.max_lines0 (max_lines given at creation or update)

Return type:

int

offsetx(t=None)

offsetx of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

offsetx – default behaviour: linear interpolation between self.offsetx0 and self.offsetx1

Return type:

float

offsety(t=None)

offsety of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

offsety – default behaviour: linear interpolation between self.offsety0 and self.offsety1

Return type:

float

points(t=None)

points of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

points – series of x- and y-coordinates (xa,ya,xb,yb,xc,yc, …)

default behaviour: linear interpolation between self.points0 and self.points1

Return type:

tuple

polygon(t=None)

polygon of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

polygon – series of x- and y-coordinates describing the polygon (xa,ya,xb,yb,xc,yc, …)

default behaviour: linear interpolation between self.polygon0 and self.polygon1

Return type:

tuple

rectangle(t=None)

rectangle of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

rectangle – (xlowerleft,ylowerlef,xupperright,yupperright)

default behaviour: linear interpolation between self.rectangle0 and self.rectangle1

Return type:

tuple

remove()

removes the animation object from the animation queue, so effectively ending this animation.

Note

The animation object might be still updated, if required

text(t=None)

text of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

text – default behaviour: self.text0 (text given at creation or update)

Return type:

str

text_anchor(t=None)

text_anchor of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

text_anchor – default behaviour: self.text_anchor0 (text_anchor given at creation or update)

Return type:

str

textcolor(t=None)

textcolor of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

textcolor – default behaviour: linear interpolation between self.textcolor0 and self.textcolor1

Return type:

colorspec

update(layer=None, keep=None, visible=None, t0=None, x0=None, y0=None, offsetx0=None, offsety0=None, circle0=None, line0=None, polygon0=None, rectangle0=None, points0=None, image=None, text=None, font=None, anchor=None, xy_anchor0=None, max_lines=None, text_anchor=None, linewidth0=None, fillcolor0=None, linecolor0=None, textcolor0=None, angle0=None, alpha0=None, fontsize0=None, width0=None, xy_anchor1=None, as_points=None, t1=None, x1=None, y1=None, offsetx1=None, offsety1=None, circle1=None, line1=None, polygon1=None, rectangle1=None, points1=None, linewidth1=None, fillcolor1=None, linecolor1=None, textcolor1=None, angle1=None, alpha1=None, fontsize1=None, width1=None, flip_horizontal=None, flip_vertical=None, animation_start=None, animation_speed=None, animation_repeat=None, animation_pingpong=None, animation_from=None, animation_to=None)

updates an animation object

Parameters:
  • layer (int) –

    layer value

    lower layer values are on top of higher layer values (default see below)

  • keep (bool) –

    keep

    if False, animation object is hidden after t1, shown otherwise (default see below)

  • visible (bool) –

    visible

    if False, animation object is not shown, shown otherwise (default see below)

  • xy_anchor (str) –

    specifies where x and y (i.e. x0, y0, x1 and y1) are relative to

    possible values are:

    nw    n    ne

    w     c     e

    sw    s    se

    If null string, the given coordimates are used untranslated

    default see below

  • t0 (float) – time of start of the animation (default: now)

  • x0 (float) – x-coordinate of the origin at time t0 (default see below)

  • y0 (float) – y-coordinate of the origin at time t0 (default see below)

  • offsetx0 (float) – offsets the x-coordinate of the object at time t0 (default see below)

  • offsety0 (float) – offsets the y-coordinate of the object at time t0 (default see below)

  • circle0 (float or tuple/list) –

    the circle spec of the circle at time t0

    • radius

    • one item tuple/list containing the radius

    • five items tuple/list cntaining radius, radius1, arc_angle0, arc_angle1 and draw_arc

    (see class AnimateCircle for details)

  • line0 (tuple) – the line(s) at time t0 (xa,ya,xb,yb,xc,yc, …) (default see below)

  • polygon0 (tuple) –

    the polygon at time t0 (xa,ya,xb,yb,xc,yc, …)

    the last point will be auto connected to the start (default see below)

  • rectangle0 (tuple) –

    the rectangle at time t0

    (xlowerleft,ylowerlef,xupperright,yupperright) (default see below)

  • points0 (tuple) – the points(s) at time t0 (xa,ya,xb,yb,xc,yc, …) (default see below)

  • image (str or PIL image) –

    the image to be displayed

    This may be either a filename or a PIL image (default see below)

  • text (str) – the text to be displayed (default see below)

  • font (str or list/tuple) –

    font to be used for texts

    Either a string or a list/tuple of fontnames. (default see below) If not found, uses calibri or arial

  • max_lines (int) –

    the maximum of lines of text to be displayed

    if positive, it refers to the first max_lines lines

    if negative, it refers to the first -max_lines lines

    if zero (default), all lines will be displayed

  • anchor (str) –

    anchor position

    specifies where to put images or texts relative to the anchor point (default see below)

    possible values are (default: c):

    nw    n    ne

    w     c     e

    sw    s    se

  • linewidth0 (float) – linewidth of the contour at time t0 (default see below)

  • fillcolor0 (colorspec) – color of interior/text at time t0 (default see below)

  • linecolor0 (colorspec) – color of the contour at time t0 (default see below)

  • angle0 (float) – angle of the polygon at time t0 (in degrees) (default see below)

  • fontsize0 (float) – fontsize of text at time t0 (default see below)

  • width0 (float) –

    width of the image to be displayed at time t0 (default see below)

    if None, the original width of the image will be used

  • t1 (float) –

    time of end of the animation (default: inf)

    if keep=True, the animation will continue (frozen) after t1

  • x1 (float) – x-coordinate of the origin at time t1 (default x0)

  • y1 (float) – y-coordinate of the origin at time t1 (default y0)

  • offsetx1 (float) – offsets the x-coordinate of the object at time t1 (default offsetx0)

  • offsety1 (float) – offsets the y-coordinate of the object at time t1 (default offset0)

  • circle1 (float or tuple/ist) –

    the circle spec of the circle at time t1

    • radius

    • one item tuple/list containing the radius

    • five items tuple/list cntaining radius, radius1, arc_angle0, arc_angle1 and draw_arc

    (see class AnimateCircle for details)

  • line1 (tuple) –

    the line(s) at time t1 (xa,ya,xb,yb,xc,yc, …) (default: line0)

    should have the same number of elements as line0

  • polygon1 (tuple) –

    the polygon at time t1 (xa,ya,xb,yb,xc,yc, …) (default: polygon0)

    should have the same number of elements as polygon0

  • rectangle1 (tuple) – the rectangle at time t (xlowerleft,ylowerleft,xupperright,yupperright) (default: rectangle0)

points1tuple

the points(s) at time t1 (xa,ya,xb,yb,xc,yc, …) (default: points0)

should have the same number of elements as points1

linewidth1float

linewidth of the contour at time t1 (default linewidth0)

fillcolor1colorspec

color of interior/text at time t1 (default fillcolor0)

linecolor1colorspec

color of the contour at time t1 (default linecolor0)

angle1float

angle of the polygon at time t1 (in degrees) (default angle0)

fontsize1float

fontsize of text at time t1 (default: fontsize0)

width1float

width of the image to be displayed at time t1 (default: width0)

Note

The type of the animation cannot be changed with this method.

The default value of most of the parameters is the current value (at time now)

visible(t=None)

visible attribute of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

visible – default behaviour: self.visible0 and t >= self.t0 (visible given at creation or update)

Return type:

bool

width(t=None)

width position of an animated image object. May be overridden.

Parameters:

t (float) – current time

Returns:

width – default behaviour: linear interpolation between self.width0 and self.width1

if None, the original width of the image will be used

Return type:

float

x(t=None)

x-position of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

x – default behaviour: linear interpolation between self.x0 and self.x1

Return type:

float

xy_anchor(t=None)

xy_anchor attribute of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

xy_anchor – default behaviour: self.xy_anchor0 (xy_anchor given at creation or update)

Return type:

str

y(t=None)

y-position of an animate object. May be overridden.

Parameters:

t (float) – current time

Returns:

y – default behaviour: linear interpolation between self.y0 and self.y1

Return type:

float

class salabim.AnimateButton(x: float = 0, y: float = 0, width: int = 80, fillcolor: str | Iterable[float] = 'fg', color: str | Iterable[float] = 'bg', text: str = '', font: str = '', fontsize: int = 15, action: Callable = None, env: Environment = None, xy_anchor: str = 'sw')

defines a button

Parameters:
  • x (int) – x-coordinate of centre of the button in screen coordinates (default 0)

  • y (int) – y-coordinate of centre of the button in screen coordinates (default 0)

  • width (int) – width of button in screen coordinates (default 80)

  • height (int) – height of button in screen coordinates (default 30)

  • linewidth (int) – width of contour in screen coordinates (default 0=no contour)

  • fillcolor (colorspec) – color of the interior (foreground_color)

  • linecolor (colorspec) – color of contour (default foreground_color)

  • color (colorspec) – color of the text (default background_color)

  • text (str or function) –

    text of the button (default null string)

    if text is an argumentless function, this will be called each time; the button is shown/updated

  • font (str) – font of the text (default Calibri)

  • fontsize (int) – fontsize of the text (default 15)

  • action (function) –

    action to take when button is pressed

    executed when the button is pressed (default None) the function should have no arguments

xy_anchorstr

specifies where x and y are relative to

possible values are (default: sw):

nw    n    ne

w     c     e

sw    s    se

envEnvironment

environment where the component is defined

if omitted, default_env will be used

Note

All measures are in screen coordinates

On Pythonista, this functionality is emulated by salabim On other platforms, the tkinter functionality is used.

remove()

removes the button object.

the ui object is removed from the ui queue, so effectively ending this ui

class salabim.AnimateCircle(radius: float | Callable = None, radius1: float | Callable = None, arc_angle0: float | Callable = None, arc_angle1: float | Callable = None, draw_arc: float | Callable = None, x: float | Callable = None, y: float | Callable = None, fillcolor: str | Iterable[float] | Callable = None, linecolor: str | Iterable[float] | Callable = None, linewidth: float | Callable = None, text: str | Callable = None, fontsize: float | Callable = None, textcolor: str | Iterable[float] | Callable = None, font: str | Callable = None, angle: float | Callable = None, xy_anchor: str | Callable = None, layer: float | Callable = None, max_lines: int | Callable = None, offsetx: float | Callable = None, offsety: float | Callable = None, as_points: bool | Callable = None, text_anchor: str | Callable = None, text_offsetx: float | Callable = None, text_offsety: float | Callable = None, arg: Any = None, parent: Component = None, visible: bool | Callable = None, keep: bool | Callable = None, env: Environment = None, screen_coordinates: bool = False, over3d: bool = None)

Displays a (partial) circle or (partial) ellipse , optionally with a text

Parameters:
  • radius (float) – radius of the circle

  • radius1 (float) – the ‘height’ of the ellipse. If None (default), a circle will be drawn

  • arc_angle0 (float) – start angle of the circle (default 0)

  • arc_angle1 (float) –

    end angle of the circle (default 360)

    when arc_angle1 > arc_angle0 + 360, only 360 degrees will be shown

  • draw_arc (bool) – if False (default), no arcs will be drawn if True, the arcs from and to the center will be drawn

  • x (float) – position of anchor point (default 0)

  • y (float) – position of anchor point (default 0)

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw) :

    nw    n    ne

    w     c     e

    sw    s    se

    If null string, the given coordimates are used untranslated

    The positions corresponds to a full circle even if arc_angle0 and/or arc_angle1 are specified.

  • offsetx (float) – offsets the x-coordinate of the circle (default 0)

  • offsety (float) – offsets the y-coordinate of the circle (default 0)

  • linewidth (float) –

    linewidth of the contour

    default 1

  • fillcolor (colorspec) – color of interior (default foreground_color)

  • linecolor (colorspec) – color of the contour (default transparent)

  • angle (float) –

    angle of the circle/ellipse and/or text (in degrees)

    default: 0

  • text (str, tuple or list) –

    the text to be displayed

    if text is str, the text may contain linefeeds, which are shown as individual lines

  • max_lines (int) –

    the maximum of lines of text to be displayed

    if positive, it refers to the first max_lines lines

    if negative, it refers to the last -max_lines lines

    if zero (default), all lines will be displayed

  • font (str or list/tuple) –

    font to be used for texts

    Either a string or a list/tuple of fontnames. If not found, uses calibri or arial

  • text_anchor (str) –

    anchor position of text

    specifies where to texts relative to the polygon point

    possible values are (default: c):

    nw    n    ne

    w     c     e

    sw    s    se

  • textcolor (colorspec) – color of the text (default foreground_color)

  • text_offsetx (float) – extra x offset to the text_anchor point

  • text_offsety (float) – extra y offset to the text_anchor point

  • fontsize (float) – fontsize of text (default 15)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • layer (float) –

    default: 0

    lower layer numbers are placed on top of higher layer numbers

  • screen_coordinates (bool) –

    use screen_coordinates

    normally, the scale parameters are use for positioning and scaling objects.

    if True, screen_coordinates will be used instead.

  • over3d (bool) –

    if True, this object will be rendered to the OpenGL window

    if False (default), the normal 2D plane will be used.

Note

All measures are in screen coordinates

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.AnimateCombined(animation_objects: Iterable, **kwargs)

Combines several Animate? objects

Parameters:
  • animation_objects (iterable) – iterable of Animate2dBase, Animate3dBase or AnimateCombined objects

  • **kwargs (dict) – attributes to be set for objects in animation_objects

Notes

When an attribute of an AnimateCombined is assigned, it will propagate to all members, provided it has already that attribute.

When an attribute of an AnimateCombined is queried, the value of the attribute of the first animation_object of the list that has such an attribute will be returned.

If the attribute does not exist in any animation_object of the list, an AttributeError will be raised.

It is possible to use animation_objects with

an = sim.AnimationCombined(car.animation_objects[2:])
an = sim.AnimationCombined(car.animation3d_objects[3:])
append(item)

Add Animate2dBase, Animate3dBase or AnimateCombined object

Parameters:

item (Animate2dBase, Animate3dBase or AnimateCombined) – to be added

remove()

remove all members from the animation

show()

show all members in the animation

update(**kwargs)

Updated one or more attributes

Parameters:

**kwargs (dict) – attributes to be set

class salabim.AnimateEntry(x: float = 0, y: float = 0, number_of_chars: int = 20, value: str = '', fillcolor: str | Iterable[float] = 'fg', color: str | Iterable[float] = 'bg', action: Callable = None, env: Environment = None, xy_anchor: str = 'sw')

defines a button

Parameters:
  • x (int) – x-coordinate of centre of the button in screen coordinates (default 0)

  • y (int) – y-coordinate of centre of the button in screen coordinates (default 0)

  • number_of_chars (int) – number of characters displayed in the entry field (default 20)

  • fillcolor (colorspec) – color of the entry background (default foreground_color)

  • color (colorspec) – color of the text (default background_color)

  • value (str) – initial value of the text of the entry (default null string)

actionfunction

action to take when the Enter-key is pressed

the function should have no arguments

xy_anchorstr

specifies where x and y are relative to

possible values are (default: sw):

nw    n    ne

w     c     e

sw    s    se

envEnvironment

environment where the component is defined

if omitted, default_env will be used

Note

All measures are in screen coordinates

This class is not available under Pythonista.

get()

get the current value of the entry

Returns:

Current value of the entry

Return type:

str

remove()

removes the entry object.

the ui object is removed from the ui queue, so effectively ending this ui

class salabim.AnimateGrid(spacing: float = 100, env: Environment = None, **kwargs)

Draws a grid with text labels

Parameters:
  • spacing (float) – spacing of the grid lines in vertical and horizontal direction

  • env (Environment) –

    environment where the component is defined

    if omitted, default_env will be used

  • **kwargs (dict) – extra parameters to be given to AnimateLine, like linecolor, textcolor, font, visible

class salabim.AnimateImage(image: Any = None, x: float | Callable = None, y: float | Callable = None, width: float | Callable = None, text: str | Callable = None, fontsize: float | Callable = None, textcolor: str | Iterable[float] | Callable = None, font: str | Callable = None, angle: float | Callable = None, alpha: float | Callable = None, xy_anchor: str | Callable = None, layer: float | Callable = None, max_lines: int | Callable = None, offsetx: float | Callable = None, offsety: float | Callable = None, text_anchor: str | Callable = None, text_offsetx: float | Callable = None, text_offsety: float | Callable = None, anchor: str | Callable = None, animation_start: float | Callable = None, animation_repeat: bool | Callable = None, animation_pingpong: bool | Callable = None, animation_speed: float | Callable = None, animation_from: float | Callable = None, animation_to: float | Callable = None, flip_horizontal: bool | Callable = None, flip_vertical: bool | Callable = None, arg: Any = None, parent: Component = None, visible: bool | Callable = None, keep: bool | Callable = None, env: Environment = None, screen_coordinates: bool = False, over3d: bool = None)

Displays an image, optionally with a text

Parameters:
  • image (str, pathlib.Path or PIL Image) –

    image to be displayed

    if used as function or method or in direct assigmnent, the image should be a file containing an image or a PIL image

  • x (float) – position of anchor point (default 0)

  • y (float) – position of anchor point (default 0)

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw) :

    nw    n    ne

    w     c     e

    sw    s    se

    If null string, the given coordimates are used untranslated

  • anchor (str) –

    specifies where the x and refer to

    possible values are (default: sw) :

    nw    n    ne

    w     c     e

    sw    s    se

offsetxfloat

offsets the x-coordinate of the circle (default 0)

offsetyfloat

offsets the y-coordinate of the circle (default 0)

anglefloat

angle of the image (in degrees) (default 0)

alphafloat

alpha of the image (0-255) (default 255)

widthfloat

width of the image (default: None = no scaling)

textstr, tuple or list

the text to be displayed

if text is str, the text may contain linefeeds, which are shown as individual lines

max_linesint

the maximum of lines of text to be displayed

if positive, it refers to the first max_lines lines

if negative, it refers to the last -max_lines lines

if zero (default), all lines will be displayed

fontstr or list/tuple

font to be used for texts

Either a string or a list/tuple of fontnames. If not found, uses calibri or arial

text_anchorstr

anchor position of text

specifies where to texts relative to the polygon point

possible values are (default: c):

nw    n    ne

w     c     e

sw    s    se

textcolorcolorspec

color of the text (default foreground_color)

text_offsetxfloat

extra x offset to the text_anchor point

text_offsetyfloat

extra y offset to the text_anchor point

fontsizefloat

fontsize of text (default 15)

animation_startfloat

(simulation)time to start the animation

default: env.t()

When the image is not an animated GIF, no effect

animation_repeatfloat

if False (default), the animation will be shown only once

if True, the animation will be repeated

When the image is not an animated GIF, no effect

animation_speedfloat

time scale (relative to current speed) (default: 1)

When the image is not an animated GIF, no effect

animation_pingpongbool

if False (default), the animation will play forward only

if True, the animation will first play forward, then backward. Note that the backward loop might run slowly.

animation_fromfloat

animate from this time (measured in seconds in the actual gif/webp video)

default: 0

animation_tofloat

animate to this time (measured in seconds in the actual gif/webp video)

default: inf (=end of video)

argany

this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

default: self (instance itself)

parentComponent

component where this animation object belongs to (default None)

if given, the animation object will be removed automatically when the parent component is no longer accessible

layerfloat

default: 0

lower layer numbers are placed on top of higher layer numbers

screen_coordinatesbool

use screen_coordinates

normally, the scale parameters are used for positioning and scaling objects.

if True, screen_coordinates will be used instead.

over3dbool

if True, this object will be rendered to the OpenGL window

if False (default), the normal 2D plane will be used.

Note

All measures are in screen coordinates

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

duration()
Returns:

duration of spec (in seconds) – if image is not an animated gif, 0 will be returned

does not take animation_pingpong, animation_from or animation_to into consideration

Return type:

float

class salabim.AnimateLine(spec: Iterable | Callable = None, x: float | Callable = None, y: float | Callable = None, fillcolor: str | Iterable[float] | Callable = None, linecolor: str | Iterable[float] | Callable = None, linewidth: float | Callable = None, text: str | Callable = None, fontsize: float | Callable = None, textcolor: str | Iterable[float] | Callable = None, font: str | Callable = None, angle: float | Callable = None, xy_anchor: str | Callable = None, layer: float | Callable = None, max_lines: int | Callable = None, offsetx: float | Callable = None, offsety: float | Callable = None, as_points: bool | Callable = None, text_anchor: str | Callable = None, text_offsetx: float | Callable = None, text_offsety: float | Callable = None, arg: Any = None, parent: Component = None, visible: bool | Callable = None, keep: bool | Callable = None, env: Environment = None, screen_coordinates: bool = False, over3d: bool = None)

Displays a line, optionally with a text

Parameters:
  • spec (tuple or list) – should specify x0, y0, x1, y1, …

  • x (float) – position of anchor point (default 0)

  • y (float) – position of anchor point (default 0)

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw) :

    nw    n    ne

    w     c     e

    sw    s    se

    If null string, the given coordimates are used untranslated

  • offsetx (float) – offsets the x-coordinate of the line (default 0)

  • offsety (float) – offsets the y-coordinate of the line (default 0)

  • linewidth (float) –

    linewidth of the contour

    default 1

  • linecolor (colorspec) – color of the contour (default foreground_color)

  • angle (float) –

    angle of the line (in degrees)

    default: 0

  • as_points (bool) –

    if False (default), the contour lines are drawn

    if True, only the corner points are shown

  • text (str, tuple or list) –

    the text to be displayed

    if text is str, the text may contain linefeeds, which are shown as individual lines

  • max_lines (int) –

    the maximum of lines of text to be displayed

    if positive, it refers to the first max_lines lines

    if negative, it refers to the last -max_lines lines

    if zero (default), all lines will be displayed

  • font (str or list/tuple) –

    font to be used for texts

    Either a string or a list/tuple of fontnames. If not found, uses calibri or arial

  • text_anchor (str) –

    anchor position of text

    specifies where to texts relative to the polygon point

    possible values are (default: c):

    nw    n    ne

    w     c     e

    sw    s    se

  • textcolor (colorspec) – color of the text (default foreground_color)

  • text_offsetx (float) – extra x offset to the text_anchor point

  • text_offsety (float) – extra y offset to the text_anchor point

  • fontsize (float) – fontsize of text (default 15)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • layer (float) –

    default: 0

    lower layer numbers are placed on top of higher layer numbers

  • screen_coordinates (bool) –

    use screen_coordinates

    normally, the scale parameters are use for positioning and scaling objects.

    if True, screen_coordinates will be used instead.

  • over3d (bool) –

    if True, this object will be rendered to the OpenGL window

    if False (default), the normal 2D plane will be used.

Note

All measures are in screen coordinates

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.AnimateMonitor(monitor: ~salabim.Monitor, linecolor: str | ~typing.Iterable[float] | ~typing.Callable = 'fg', linewidth: float | ~typing.Callable = None, fillcolor: ~typing.Callable | str | ~typing.Iterable[float] = '', bordercolor: str | ~typing.Iterable[float] | ~typing.Callable = 'fg', borderlinewidth: float | ~typing.Callable = 1, titlecolor: str | ~typing.Iterable[float] | ~typing.Callable = 'fg', nowcolor: str | ~typing.Iterable[float] | ~typing.Callable = 'red', titlefont: str | ~typing.Callable = '', titlefontsize: float | ~typing.Callable = 15, title: str | ~typing.Callable = None, x: float | ~typing.Callable = 0, y: float | ~typing.Callable = 0, offsetx: float | ~typing.Callable = 0, offsety: float | ~typing.Callable = 0, angle: float | ~typing.Callable = 0, vertical_offset: float | ~typing.Callable = 0, parent: ~salabim.Component = None, vertical_scale: float | ~typing.Callable = 5, horizontal_scale: float | ~typing.Callable = 1, width: float | ~typing.Callable = 200, height: float | ~typing.Callable = 75, xy_anchor: str | ~typing.Callable = 'sw', vertical_map: ~typing.Callable = <class 'float'>, labels: ~typing.Iterable | ~typing.Dict = (), label_color: str | ~typing.Iterable[float] | ~typing.Callable = 'fg', label_font: str | ~typing.Callable = '', label_fontsize: float | ~typing.Callable = 15, label_anchor: str | ~typing.Callable = 'e', label_offsetx: float | ~typing.Callable = 0, label_offsety: float | ~typing.Callable = 0, label_linewidth: float | ~typing.Callable = 1, label_linecolor: str | ~typing.Iterable[float] = 'fg', as_points: bool = None, over3d: bool = None, layer: float | ~typing.Callable = 0, visible: bool | ~typing.Callable = True, keep: bool | ~typing.Callable = True, screen_coordinates: bool = True, arg: ~typing.Any = None)

animates a monitor in a panel

Parameters:
  • monitor (Monitor) – monitor to be animated

  • linecolor (colorspec) – color of the line or points (default foreground color)

  • linewidth (int) – width of the line or points (default 1 for level, 3 for non level monitors)

  • fillcolor (colorspec) – color of the panel (default transparent)

  • bordercolor (colorspec) – color of the border (default foreground color)

  • borderlinewidth (int) – width of the line around the panel (default 1)

  • nowcolor (colorspec) – color of the line indicating now (default red)

  • titlecolor (colorspec) – color of the title (default foreground color)

  • titlefont (font) – font of the title (default null string)

  • titlefontsize (int) – size of the font of the title (default 15)

  • title (str) –

    title to be shown above panel

    default: name of the monitor

  • x (int) – x-coordinate of panel, relative to xy_anchor, default 0

  • y (int) – y-coordinate of panel, relative to xy_anchor. default 0

  • offsetx (float) – offsets the x-coordinate of the panel (default 0)

  • offsety (float) – offsets the y-coordinate of the panel (default 0)

  • angle (float) – rotation angle in degrees, default 0

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw):

    nw    n    ne

    w     c     e

    sw    s    se

  • vertical_offset (float) –

    the vertical position of x within the panel is

    vertical_offset + x * vertical_scale (default 0)

  • vertical_scale (float) – the vertical position of x within the panel is vertical_offset + x * vertical_scale (default 5)

  • horizontal_scale (float) – the relative horizontal position of time t within the panel is on t * horizontal_scale, possibly shifted (default 1)

widthint

width of the panel (default 200)

heightint

height of the panel (default 75)

vertical_mapfunction

when a y-value has to be plotted it will be translated by this function

default: float

when the function results in a TypeError or ValueError, the value 0 is assumed

when y-values are non numeric, it is advised to provide an approriate map function, like:

vertical_map = “unknown red green blue yellow”.split().index

labelsiterable or dict

if an iterable, these are the values of the labels to be shown

if a dict, the keys are the values of the labels, the keys are the texts to be shown

labels will be shown on the vertical axis (default: empty tuple)

the placement of the labels is controlled by the vertical_map method

label_colorcolorspec

color of labels (default: foreground color)

label_fontfont

font of the labels (default null string)

label_fontsizeint

size of the font of the labels (default 15)

label_anchorstr

specifies where the label coordinates (as returned by map_value) are relative to

possible values are (default: e):

nw    n    ne

w     c     e

sw    s    se

label_offsetxfloat

offsets the x-coordinate of the label (default 0)

label_offsetyfloat

offsets the y-coordinate of the label (default 0)

label_linewidthint

width of the label line (default 1)

label_linecolorcolorspec

color of the label lines (default foreground color)

layerint

layer (default 0)

as_pointsbool

allows to override the line/point setting, which is by default False for level monitors and True for non level monitors

parentComponent

component where this animation object belongs to (default None)

if given, the animation object will be removed automatically when the parent component is no longer accessible

over3dbool

if True, this object will be rendered to the OpenGL window

if False (default), the normal 2D plane will be used.

visiblebool

visible

if False, animation monitor is not shown, shown otherwise (default True)

screen_coordinatesbool

use screen_coordinates

if False, the scale parameters are use for positioning and scaling objects.

if True (default), screen_coordinates will be used.

Note

All measures are in screen coordinates

monitor() Monitor
Returns:

monitor this animation object refers to

Return type:

Monitor

remove() None

removes the animate object and thus closes this animation

show(unremove)

It is possible to use this method if already shown

class salabim.AnimatePoints(spec: Iterable | Callable = None, x: float | Callable = None, y: float | Callable = None, fillcolor: str | Iterable[float] | Callable = None, linecolor: str | Iterable[float] | Callable = None, linewidth: float | Callable = None, text: str | Callable = None, fontsize: float | Callable = None, textcolor: str | Iterable[float] | Callable = None, font: str | Callable = None, angle: float | Callable = None, xy_anchor: str | Callable = None, layer: float | Callable = None, max_lines: int | Callable = None, offsetx: float | Callable = None, offsety: float | Callable = None, as_points: bool | Callable = None, text_anchor: str | Callable = None, text_offsetx: float | Callable = None, text_offsety: float | Callable = None, arg: Any = None, parent: Component = None, visible: bool | Callable = None, keep: bool | Callable = None, env: Environment = None, screen_coordinates: bool = False, over3d: bool = None)

Displays a series of points, optionally with a text

Parameters:
  • spec (tuple or list) – should specify x0, y0, x1, y1, …

  • x (float) – position of anchor point (default 0)

  • y (float) – position of anchor point (default 0)

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw) :

    nw    n    ne

    w     c     e

    sw    s    se

    If null string, the given coordimates are used untranslated

  • offsetx (float) – offsets the x-coordinate of the points (default 0)

  • offsety (float) – offsets the y-coordinate of the points (default 0)

  • linewidth (float) –

    width of the points

    default 1

  • linecolor (colorspec) – color of the points (default foreground_color)

  • angle (float) –

    angle of the points (in degrees)

    default: 0

  • as_points (bool) –

    if False, the contour lines are drawn

    if True (default), only the corner points are shown

  • text (str, tuple or list) –

    the text to be displayed

    if text is str, the text may contain linefeeds, which are shown as individual lines

  • max_lines (int) –

    the maximum of lines of text to be displayed

    if positive, it refers to the first max_lines lines

    if negative, it refers to the last -max_lines lines

    if zero (default), all lines will be displayed

  • font (str or list/tuple) –

    font to be used for texts

    Either a string or a list/tuple of fontnames. If not found, uses calibri or arial

  • text_anchor (str) –

    anchor position of text

    specifies where to texts relative to the polygon point

    possible values are (default: c):

    nw    n    ne

    w     c     e

    sw    s    se

  • textcolor (colorspec) – color of the text (default foreground_color)

  • text_offsetx (float) – extra x offset to the text_anchor point

  • text_offsety (float) – extra y offset to the text_anchor point

  • fontsize (float) – fontsize of text (default 15)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • screen_coordinates (bool) –

    use screen_coordinates

    normally, the scale parameters are use for positioning and scaling objects.

    if True, screen_coordinates will be used instead.

  • layer (float) –

    default: 0

    lower layer numbers are placed on top of higher layer numbers

  • over3d (bool) –

    if True, this object will be rendered to the OpenGL window

    if False (default), the normal 2D plane will be used.

Note

All measures are in screen coordinates

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.AnimatePolygon(spec: Iterable | Callable = None, x: float | Callable = None, y: float | Callable = None, fillcolor: str | Iterable[float] | Callable = None, linecolor: str | Iterable[float] | Callable = None, linewidth: float | Callable = None, text: str | Callable = None, fontsize: float | Callable = None, textcolor: str | Iterable[float] | Callable = None, font: str | Callable = None, angle: float | Callable = None, xy_anchor: str | Callable = None, layer: float | Callable = None, max_lines: int | Callable = None, offsetx: float | Callable = None, offsety: float | Callable = None, as_points: bool | Callable = None, text_anchor: str | Callable = None, text_offsetx: float | Callable = None, text_offsety: float | Callable = None, arg: Any = None, parent: Component = None, visible: bool | Callable = None, keep: bool | Callable = None, env: Environment = None, screen_coordinates: bool = False, over3d: bool = None)

Displays a polygon, optionally with a text

Parameters:
  • spec (tuple or list) – should specify x0, y0, x1, y1, …

  • x (float) – position of anchor point (default 0)

  • y (float) – position of anchor point (default 0)

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw) :

    nw    n    ne

    w     c     e

    sw    s    se

    If null string, the given coordimates are used untranslated

  • offsetx (float) – offsets the x-coordinate of the polygon (default 0)

  • offsety (float) – offsets the y-coordinate of the polygon (default 0)

  • linewidth (float) –

    linewidth of the contour

    default 1

  • fillcolor (colorspec) –

    color of interior (default foreground_color)

    default transparent

  • linecolor (colorspec) – color of the contour (default transparent)

  • angle (float) –

    angle of the polygon (in degrees)

    default: 0

  • as_points (bool) –

    if False (default), the contour lines are drawn

    if True, only the corner points are shown

  • text (str, tuple or list) –

    the text to be displayed

    if text is str, the text may contain linefeeds, which are shown as individual lines

  • max_lines (int) –

    the maximum of lines of text to be displayed

    if positive, it refers to the first max_lines lines

    if negative, it refers to the last -max_lines lines

    if zero (default), all lines will be displayed

  • font (str or list/tuple) –

    font to be used for texts

    Either a string or a list/tuple of fontnames. If not found, uses calibri or arial

  • text_anchor (str) –

    anchor position of text

    specifies where to texts relative to the polygon point

    possible values are (default: c):

    nw    n    ne

    w     c     e

    sw    s    se

  • textcolor (colorspec) – color of the text (default foreground_color)

  • text_offsetx (float) – extra x offset to the text_anchor point

  • text_offsety (float) – extra y offset to the text_anchor point

  • fontsize (float) – fontsize of text (default 15)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • screen_coordinates (bool) –

    use screen_coordinates

    normally, the scale parameters are use for positioning and scaling objects.

    if True, screen_coordinates will be used instead.

  • layer (float) –

    default: 0

    lower layer numbers are placed on top of higher layer numbers

  • over3d (bool) –

    if True, this object will be rendered to the OpenGL window

    if False (default), the normal 2D plane will be used.

Note

All measures are in screen coordinates

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.AnimateQueue(queue, x=50, y=50, direction='w', trajectory=None, max_length=None, xy_anchor='sw', reverse=False, title=None, titlecolor='fg', titlefontsize=15, titlefont='', titleoffsetx=None, titleoffsety=None, layer=0, id=None, arg=None, parent=None, over3d=None, keep=True, visible=True, screen_coordinates=True)

Animates the component in a queue.

Parameters:
  • queue (Queue) – queue it concerns

  • x (float) –

    x-position of the first component in the queue

    default: 50

  • y (float) –

    y-position of the first component in the queue

    default: 50

  • direction (str) –

    if “w”, waiting line runs westwards (i.e. from right to left)

    if “n”, waiting line runs northeards (i.e. from bottom to top)

    if “e”, waiting line runs eastwards (i.e. from left to right) (default)

    if “s”, waiting line runs southwards (i.e. from top to bottom)

  • trajectory (Trajectory) – trajectory to be followed. Overrides any given directory

  • reverse (bool) – if False (default), display in normal order. If True, reversed.

  • max_length (int) – maximum number of components to be displayed

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw):

    nw    n    ne

    w     c     e

    sw    s    se

  • titlecolor (colorspec) – color of the title (default foreground color)

  • titlefont (font) – font of the title (default null string)

  • titlefontsize (int) – size of the font of the title (default 15)

  • title (str) –

    title to be shown above queue

    default: name of the queue

  • titleoffsetx (float) –

    x-offset of the title relative to the start of the queue

    default: 25 if direction is w, -25 otherwise

  • titleoffsety (float) –

    y-offset of the title relative to the start of the queue

    default: -25 if direction is s, -25 otherwise

  • id (any) – the animation works by calling the animation_objects method of each component, optionally with id. By default, this is self, but can be overriden, particularly with the queue

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • visible (bool) –

    if False, nothing will be shown

    (default True)

  • keep (bool) – if False, animation object will be taken from the animation objects. With show(), the animation can be reshown. (default True)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

Note

All measures are in screen coordinates

All parameters, apart from queue, id, arg and parent can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

show(unremove)

It is possible to use this method if already shown

class salabim.AnimateRectangle(spec: Iterable | Callable = None, x: float | Callable = None, y: float | Callable = None, fillcolor: str | Iterable[float] | Callable = None, linecolor: str | Iterable[float] | Callable = None, linewidth: float | Callable = None, text: str | Callable = None, fontsize: float | Callable = None, textcolor: str | Iterable[float] | Callable = None, font: str | Callable = None, angle: float | Callable = None, xy_anchor: str | Callable = None, layer: float | Callable = None, max_lines: int | Callable = None, offsetx: float | Callable = None, offsety: float | Callable = None, as_points: bool | Callable = None, text_anchor: str | Callable = None, text_offsetx: float | Callable = None, text_offsety: float | Callable = None, arg: Any = None, parent: Component = None, visible: bool | Callable = None, keep: bool | Callable = None, env: Environment = None, screen_coordinates: bool = False, over3d: bool = None)

Displays a rectangle, optionally with a text

Parameters:
  • spec (four item tuple or list) – should specify xlowerleft, ylowerleft, xupperright, yupperright

  • x (float) – position of anchor point (default 0)

  • y (float) – position of anchor point (default 0)

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw) :

    nw    n    ne

    w     c     e

    sw    s    se

    If null string, the given coordimates are used untranslated

  • offsetx (float) – offsets the x-coordinate of the rectangle (default 0)

  • offsety (float) – offsets the y-coordinate of the rectangle (default 0)

  • linewidth (float) –

    linewidth of the contour

    default 1

  • fillcolor (colorspec) –

    color of interior (default foreground_color)

    default transparent

  • linecolor (colorspec) – color of the contour (default transparent)

  • angle (float) –

    angle of the rectangle (in degrees)

    default: 0

  • as_points (bool) –

    if False (default), the contour lines are drawn

    if True, only the corner points are shown

  • text (str, tuple or list) –

    the text to be displayed

    if text is str, the text may contain linefeeds, which are shown as individual lines

  • max_lines (int) –

    the maximum of lines of text to be displayed

    if positive, it refers to the first max_lines lines

    if negative, it refers to the last -max_lines lines

    if zero (default), all lines will be displayed

  • font (str or list/tuple) –

    font to be used for texts

    Either a string or a list/tuple of fontnames. If not found, uses calibri or arial

  • text_anchor (str) –

    anchor position of text

    specifies where to texts relative to the rectangle point

    possible values are (default: c):

    nw    n    ne

    w     c     e

    sw    s    se

  • textcolor (colorspec) – color of the text (default foreground_color)

  • text_offsetx (float) – extra x offset to the text_anchor point

  • text_offsety (float) – extra y offset to the text_anchor point

  • fontsize (float) – fontsize of text (default 15)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • layer (float) –

    default: 0

    lower layer numbers are placed on top of higher layer numbers

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

Note

All measures are in screen coordinates

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

class salabim.AnimateSlider(x: float = 0, y: float = 0, width: int = 100, height: int = 20, vmin: float = 0, vmax: float = 10, v: float = None, resolution: float = 1, background_color: str | Iterable[float] = 'bg', foreground_color: str | Iterable[float] = 'fg', trough_color: str | Iterable[float] = 'lightgray', show_value: bool = True, label: str = '', font: str = '', fontsize: int = 12, action: Callable = None, xy_anchor: str = 'sw', env: Environment = None, linecolor: str | Iterable[float] = None, labelcolor: str | Iterable[float] = None, layer: float = None)

defines a slider

Parameters:
  • x (int) – x-coordinate of centre of the slider in screen coordinates (default 0)

  • y (int) – y-coordinate of centre of the slider in screen coordinates (default 0)

  • vmin (float) – minimum value of the slider (default 0)

  • vmax (float) – maximum value of the slider (default 0)

  • v (float) –

    initial value of the slider (default 0)

    should be between vmin and vmax

  • resolution (float) – step size of value (default 1)

  • width (float) – width of slider in screen coordinates (default 100)

  • height (float) – height of slider in screen coordinates (default 20)

  • foreground_color (colorspec) – color of the foreground (default “fg”)

  • background_color (colorspec) – color of the backgroundground (default “bg”)

  • trough_color (colorspec) – color of the trough (default “lightgrey”)

  • show_value (boolean) – if True (default), show values; if False don’t show values

  • label (str) – label if the slider (default null string)

fontstr

font of the text (default Helvetica)

fontsizeint

fontsize of the text (default 12)

actionfunction

function executed when the slider value is changed (default None)

the function should have one argument, being the new value

if None (default), no action

xy_anchorstr

specifies where x and y are relative to

possible values are (default: sw):

nw    n    ne

w     c     e

sw    s    se

envEnvironment

environment where the component is defined

if omitted, default_env will be used

Note

The current value of the slider is the v attibute of the slider.

All measures are in screen coordinates

On Pythonista, this functionality is emulated by salabim On other platforms, the tkinter functionality is used.

remove()

removes the slider object

The ui object is removed from the ui queue, so effectively ending this ui

v(value=None)

value

Parameters:

value (float) –

new value

if omitted, no change

Returns:

Current value of the slider

Return type:

float

class salabim.AnimateText(text: str | Iterable[str] | Callable = None, x: float | Callable = None, y: float | Callable = None, font: str | Callable = None, fontsize: float | Callable = None, textcolor: str | Iterable[float] | Callable = None, text_anchor: str | Callable = None, angle: float | Callable = None, xy_anchor: str | Callable = None, layer: float | Callable = None, max_lines: int | Callable = None, offsetx: float | Callable = None, offsety: float | Callable = None, arg: Any = None, visible: bool | Callable = None, keep: bool | Callable = None, parent: Component = None, env: Environment = None, screen_coordinates: bool = False, over3d: bool = None)

Displays a text

Parameters:
  • text (str, tuple or list) –

    the text to be displayed

    if text is str, the text may contain linefeeds, which are shown as individual lines if text is tuple or list, each item is displayed on a separate line

  • x (float) – position of anchor point (default 0)

  • y (float) – position of anchor point (default 0)

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw) :

    nw    n    ne

    w     c     e

    sw    s    se

    If null string, the given coordimates are used untranslated

  • offsetx (float) – offsets the x-coordinate of the rectangle (default 0)

  • offsety (float) – offsets the y-coordinate of the rectangle (default 0)

  • angle (float) –

    angle of the text (in degrees)

    default: 0

  • max_lines (int) –

    the maximum of lines of text to be displayed

    if positive, it refers to the first max_lines lines

    if negative, it refers to the last -max_lines lines

    if zero (default), all lines will be displayed

  • font (str or list/tuple) –

    font to be used for texts

    Either a string or a list/tuple of fontnames. If not found, uses calibri or arial

  • text_anchor (str) –

    anchor position of text

    specifies where to texts relative to the rectangle point

    possible values are (default: c):

    nw    n    ne

    w     c     e

    sw    s    se

  • textcolor (colorspec) – color of the text (default foreground_color)

  • fontsize (float) – fontsize of text (default 15)

  • arg (any) –

    this is used when a parameter is a function with two parameters, as the first argument or if a parameter is a method as the instance

    default: self (instance itself)

  • parent (Component) –

    component where this animation object belongs to (default None)

    if given, the animation object will be removed automatically when the parent component is no longer accessible

  • screen_coordinates (bool) –

    use screen_coordinates

    normally, the scale parameters are use for positioning and scaling objects.

    if True, screen_coordinates will be used instead.

  • layer (float) –

    default: 0

    lower layer numbers are placed on top of higher layer numbers

  • over3d (bool) –

    if True, this object will be rendered to the OpenGL window

    if False (default), the normal 2D plane will be used.

Note

All measures are in screen coordinates

All parameters, apart from parent, arg and env can be specified as:

  • a scalar, like 10

  • a function with zero arguments, like lambda: title

  • a function with one argument, being the time t, like lambda t: t + 10

  • a function with two parameters, being arg (as given) and the time, like lambda comp, t: comp.state

  • a method instance arg for time t, like self.state, actually leading to arg.state(t) to be called

Component

class salabim.Component(name: str = None, at: float | Callable = None, delay: float | Callable = None, priority: float = None, urgent: bool = None, process: str = None, suppress_trace: bool = False, suppress_pause_at_step: bool = False, skip_standby: bool = False, mode: str = '', cap_now: bool = None, env: Environment = None, **kwargs)

Component object

A salabim component is used as component (primarily for queueing) or as a component with a process

Usually, a component will be defined as a subclass of Component.

Parameters:
  • name (str) –

    name of the component.

    if the name ends with a period (.), auto serializing will be applied

    if the name end with a comma, auto serializing starting at 1 will be applied

    if omitted, the name will be derived from the class it is defined in (lowercased)

  • at (float or distribution) –

    schedule time

    if omitted, now is used

    if distribution, the distribution is sampled

  • delay (float or distributiom) –

    schedule with a delay

    if omitted, no delay

    if distribution, the distribution is sampled

  • priority (float) –

    priority

    default: 0

    if a component has the same time on the event list, this component is sorted accoring to the priority.

  • urgent (bool) –

    urgency indicator

    if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

    if True, the component will be scheduled in front of all components scheduled for the same time and priority

  • process (str) –

    name of process to be started.

    if None (default), it will try to start self.process()

    if null string, no process will be started even if self.process() exists, i.e. become a data component.

suppress_tracebool

suppress_trace indicator

if True, this component will be excluded from the trace

If False (default), the component will be traced

Can be queried or set later with the suppress_trace method.

suppress_pause_at_stepbool

suppress_pause_at_step indicator

if True, if this component becomes current, do not pause when stepping

If False (default), the component will be paused when stepping

Can be queried or set later with the suppress_pause_at_step method.

skip_standbybool

skip_standby indicator

if True, after this component became current, do not activate standby components

If False (default), after the component became current activate standby components

Can be queried or set later with the skip_standby method.

modestr preferred

mode

will be used in trace and can be used in animations

if omitted, the mode will be “”.

also mode_time will be set to now.

cap_nowbool

indicator whether times (at, delay) in the past are allowed. If, so now() will be used. default: sys.default_cap_now(), usualy False

envEnvironment

environment where the component is defined

if omitted, default_env will be used

activate(at: float | Callable = None, delay: Callable | float = 0, priority: float = 0, urgent: bool = False, process: str = None, keep_request: bool = False, keep_wait: bool = False, mode: str = None, cap_now: bool = None, **kwargs) None

activate component

Parameters:
  • at (float or distribution) –

    schedule time

    if omitted, now is used

    inf is allowed

    if distribution, the distribution is sampled

  • delay (float or distribution) –

    schedule with a delay

    if omitted, no delay

    if distribution, the distribution is sampled

  • priority (float) –

    priority

    default: 0

    if a component has the same time on the event list, this component is sorted accoring to the priority.

  • urgent (bool) –

    urgency indicator

    if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

    if True, the component will be scheduled in front of all components scheduled for the same time and priority

  • process (str) –

    name of process to be started.

    if None (default), process will not be changed

    if the component is a data component, the process method will be used as the default process.

  • keep_request (bool) –

    this affects only components that are requesting.

    if True, the requests will be kept and thus the status will remain requesting

    if False (the default), the request(s) will be canceled and the status will become scheduled

  • keep_wait (bool) –

    this affects only components that are waiting.

    if True, the waits will be kept and thus the status will remain waiting

    if False (the default), the wait(s) will be canceled and the status will become scheduled

  • cap_now (bool) – indicator whether times (at, delay) in the past are allowed. If, so now() will be used. default: sys.default_cap_now(), usualy False

  • mode (str preferred) –

    mode

    will be used in the trace and can be used in animations

    if nothing specified, the mode will be unchanged.

    also mode_time will be set to now, if mode is set.

Note

Only if yieldless is False: if to be applied to the current component, use yield self.activate().

if both at and delay are specified, the component becomes current at the sum of the two values.

animation3d_objects(id: Any) Tuple

defines how to display a component in Animate3dQueue

Parameters:

id (any) – id as given by Animate3dQueue. Note that by default this the reference to the Animate3dQueue object.

Returns:

size_x : how much to displace the next component in x-direction, if applicable

size_y : how much to displace the next component in y-direction, if applicable

size_z : how much to displace the next component in z-direction, if applicable

animation objects : instances of Animate3dBase class

default behaviour:

white 3dbox of size 8, placed on the z=0 plane (displacements 10).

Return type:

List or tuple containg

Note

If you override this method, be sure to use the same header, either with or without the id parameter.

Note

The animation object should support the x_offset, y_offset and z_offset attributes, in order to be able to position the object correctly. All native salabim Animate3d classes are offset aware.

animation_objects(id: Any) Tuple

defines how to display a component in AnimateQueue

Parameters:

id (any) – id as given by AnimateQueue. Note that by default this the reference to the AnimateQueue object.

Returns:

size_x : how much to displace the next component in x-direction, if applicable

size_y : how much to displace the next component in y-direction, if applicable

animation objects : instances of Animate class

default behaviour:

square of size 40 (displacements 50), with the sequence number centered.

Return type:

List or tuple containg

Note

If you override this method, be sure to use the same header, either with or without the id parameter.

base_name() str
Returns:

base name of the component (the name used at initialization)

Return type:

str

cancel(mode: str = None) None

cancel component (makes the component data)

Parameters:

mode (str preferred) –

mode

will be used in trace and can be used in animations

if nothing specified, the mode will be unchanged.

also mode_time will be set to now, if mode is set.

Note

Only if yieldless is False: if to be used for the current component, use yield self.cancel().

claimed_quantity(resource: Resource = None) float
Parameters:

resource (Resoure) – resource to be queried

Returns:

the claimed quantity from a resource – if the resource is not claimed, 0 will be returned

Return type:

float or int

claimed_resources() List
Returns:

list of claimed resources

Return type:

list

count(q: Queue = None) int

queue count

Parameters:

q (Queue) –

queue to check or

if omitted, the number of queues where the component is in

Returns:

1 if component is in q, 0 otherwise

Return type:

int

if q is omitted, the number of queues where the component is in

creation_time() float
Returns:

time the component was created

Return type:

float

deregister(registry: List) Component

deregisters the component in the registry

Parameters:

registry (list) – list of registered components

Returns:

component (self)

Return type:

Component

enter(q: Queue) Component

enters a queue at the tail

Parameters:

q (Queue) – queue to enter

Note

the priority will be set to the priority of the tail component of the queue, if any or 0 if queue is empty

enter_at_head(q: Queue) Component

enters a queue at the head

Parameters:

q (Queue) – queue to enter

Note

the priority will be set to the priority of the head component of the queue, if any or 0 if queue is empty

enter_behind(q: Queue, poscomponent: Component) Component

enters a queue behind a component

Parameters:
  • q (Queue) – queue to enter

  • poscomponent (Component) – component to be entered behind

Note

the priority will be set to the priority of poscomponent

enter_in_front_of(q: Queue, poscomponent: Component) Component

enters a queue in front of a component

Parameters:
  • q (Queue) – queue to enter

  • poscomponent (Component) – component to be entered in front of

Note

the priority will be set to the priority of poscomponent

enter_sorted(q: Queue, priority: float) Component

enters a queue, according to the priority

Parameters:
  • q (Queue) – queue to enter

  • priority (type that can be compared with other priorities in the queue) – priority in the queue

Note

The component is placed just before the first component with a priority > given priority

enter_time(q: Queue) float
Parameters:

q (Queue) – queue where component belongs to

Returns:

time the component entered the queue

Return type:

float

failed() bool
Returns:

  • True, if the latest request/wait has failed (either by timeout or external) (bool)

  • False, otherwise

filter(value: callable)

updates the filter used in self.from_to

Parameters:

value (callable) – new filter, which should be a function with one parameter(component) and returning a bool

Note

After applying the new filter, items (components) may leave or enter the store

from_store(store: ~salabim.Store | ~typing.Iterable, filter: ~typing.Callable = <function Component.<lambda>>, fail_priority: float = 0, urgent: bool = True, fail_at: float = None, fail_delay: float = None, mode: str = None, cap_now: bool = None, key: callable = None) Component

get item from store(s)

Parameters:
  • store (store or iterable stores) – store(s) to get item from

  • filter (callable) –

    only components that return True when applied to them will be considered

    should be a function with one parameter(component) and returning a bool

    default: lambda c: True (i.e. always return True)

  • fail_priority (float) –

    priority of the fail event

    default: 0

    if a component has the same time on the event list, this component is sorted according to the priority.

  • urgent (bool) –

    urgency indicator

    if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

    if True, the component will be scheduled in front of all components scheduled for the same time and priority

  • fail_at (float or distribution) –

    time out

    if the request is not honored before fail_at, the request will be cancelled and the parameter failed will be set.

    if not specified, the request will not time out.

    if distribution, the distribution is sampled

  • fail_delay (float or distribution) –

    time out

    if the request is not honored before now+fail_delay, the request will be cancelled and the parameter failed will be set.

    if not specified, the request will not time out.

    if distribution, the distribution is sampled

  • mode (str preferred) –

    mode

    will be used in trace and can be used in animations

    if nothing specified, the mode will be unchanged.

    also mode_time will be set to now, if mode is set.

  • cap_now (bool) – indicator whether times (fail_at, fail_delay) in the past are allowed. If, so now() will be used. default: sys.default_cap_now(), usualy False

  • key (callable) –

    should be a function with one parameter (a component) and return a key value, to be used to compare components (most likely a number or string).

    The component with lowest key value (satisfying the filter condition) will be returned.

    If omitted, no sorting will be applied.

Note

Only allowed for current component

Only if yieldless is False: Always use as use item = yield self.from_store(...).

The parameter failed will be reset by a calling request, wait, from_store or to_store

from_store_item() Component | None

return item returned from a self.from_store(…) if valid

Returns:

item returned

Return type:

Component or None, if not valid

from_store_store() Component | None

return store where item was returned from a self.from_store(…) if valid

Returns:

item returned

Return type:

Component or None, if not valid

get(*args, **kwargs) None

equivalent to request

hold(duration: float | Callable = None, till: float | Callable = None, priority: float = 0, urgent: bool = False, mode: str = None, interrupted: bool | int = False, cap_now: bool = None) None

hold the component

Parameters:
  • duration (float or distribution) –

    specifies the duration

    if omitted, 0 is used

    inf is allowed

    if distribution, the distribution is sampled

  • till (float or distribution) –

    specifies at what time the component will become current

    if omitted, now is used

    inf is allowed

    if distribution, the distribution is sampled

  • priority (float) –

    priority

    default: 0

    if a component has the same time on the event list, this component is sorted accoring to the priority.

  • urgent (bool) –

    urgency indicator

    if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

    if True, the component will be scheduled in front of all components scheduled for the same time and priority

  • mode (str preferred) –

    mode

    will be used in trace and can be used in animations

    if nothing specified, the mode will be unchanged.

    also mode_time will be set to now, if mode is set.

  • interrupted (bool or int) –

    if False (default), not interrupted

    if True, the component will immediately go into interrupted state

    if an integer, this is the interrupt_level

  • cap_now (bool) – indicator whether times (duration, till) in the past are allowed. If, so now() will be used. default: sys.default_cap_now(), usualy False

Note

Only if yieldless is False: if to be used for the current component, use yield self.hold(...).

if both duration and till are specified, the component will become current at the sum of these two.

index(q: Queue) int
Parameters:

q (Queue) – queue to be queried

Returns:

index of component in q – if component belongs to q

-1 if component does not belong to q

Return type:

int

interrupt(mode: str = None) None

interrupt the component

Parameters:

mode (str preferred) –

mode

will be used in trace and can be used in animations

if nothing is specified, the mode will be unchanged.

also mode_time will be set to now, if mode is set.

Note

The component has to be scheduled.

Use resume() to resume

interrupt_level() int

returns interrupt level of an interrupted component

non interrupted components return 0

interrupted_status() Any

returns the original status of an interrupted component

possible values are
  • passive

  • scheduled

  • requesting

  • waiting

  • standby

isbumped(resource: Resource = None) bool

check whether component is bumped from resource

Parameters:

resource (Resource) – resource to be checked if omitted, checks whether component belongs to any resource claimers

Returns:

True if this component is not in the resource claimers – False otherwise

Return type:

bool

isclaiming(resource: Resource = None) bool

check whether component is claiming from resource

Parameters:

resource (Resource) – resource to be checked if omitted, checks whether component is in any resource claimers

Returns:

True if this component is in the resource claimers – False otherwise

Return type:

bool

iscurrent() bool
Returns:

True if status is current, False otherwise

Return type:

bool

Note

Be sure to always include the parentheses, otherwise the result will be always True!

isdata() bool
Returns:

True if status is data, False otherwise

Return type:

bool

Note

Be sure to always include the parentheses, otherwise the result will be always True!

isinterrupted() bool
Returns:

True if status is interrupted, False otherwise

Return type:

bool

Note

Be sure to always include the parentheses, otherwise the result will be always True

ispassive() bool
Returns:

True if status is passive, False otherwise

Return type:

bool

Note

Be sure to always include the parentheses, otherwise the result will be always True!

isrequesting()
Returns:

True if status is requesting, False otherwise

Return type:

bool

Note

Be sure to always include the parentheses, otherwise the result will be always True!

isscheduled() bool
Returns:

True if status is scheduled, False otherwise

Return type:

bool

Note

Be sure to always include the parentheses, otherwise the result will be always True!

isstandby() bool
Returns:

True if status is standby, False otherwise

Return type:

bool

Note

Be sure to always include the parentheses, otherwise the result will be always True

iswaiting() bool
Returns:

True if status is waiting, False otherwise

Return type:

bool

Note

Be sure to always include the parentheses, otherwise the result will be always True!

leave(q: Queue = None) Component

leave queue

Parameters:

q (Queue) – queue to leave

Note

statistics are updated accordingly

line_number() str

current line number of the process

Returns:

Current line number – for data components, “” will be returned

Return type:

str

mode_time() float
Returns:

time the component got it’s latest mode – For a new component this is the time the component was created.

this function is particularly useful for animations.

Return type:

float

name(value: str = None) str
Parameters:

value (str) – new name of the component if omitted, no change

Returns:

Name of the component

Return type:

str

Note

base_name and sequence_number are not affected if the name is changed

passivate(mode: str = None) None

passivate the component

Parameters:

mode (str preferred) –

mode

will be used in trace and can be used in animations

if nothing is specified, the mode will be unchanged.

also mode_time will be set to now, if mode is set.

Note

Only if yieldless is False: if to be used for the current component (nearly always the case), use yield self.passivate().

predecessor(q: Queue) Component
Parameters:
  • q (Queue) – queue where the component belongs to

  • Returns (Component) –

    predecessor of the component in the queue if component is not at the head.

    returns None if component is at the head.

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the component

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

priority(q: Queue, priority: float = None) float

gets/sets the priority of a component in a queue

Parameters:
  • q (Queue) – queue where the component belongs to

  • priority (type that can be compared with other priorities in the queue) –

    priority in queue

    if omitted, no change

Returns:

the priority of the component in the queue

Return type:

float

Note

if you change the priority, the order of the queue may change

put(*args, **kwargs) None

equivalent to request, but anonymous quantities are negated

queues() Set
Returns:

set of queues where the component belongs to

Return type:

set

register(registry: List) Component

registers the component in the registry

Parameters:

registry (list) – list of (to be) registered objects

Returns:

component (self)

Return type:

Component

Note

Use Component.deregister if component does not longer need to be registered.

release(*args) None

release a quantity from a resource or resources

Parameters:

args (sequence of items, where each items can be) –

  • a resource, where quantity=current claimed quantity

  • a tuple/list containing a resource and the quantity to be released

Note

It is not possible to release from an anonymous resource, this way. Use Resource.release() in that case.

Example

If yieldless, refrain from yield,

yield self.request(r1,(r2,2),(r3,3,100))

–> requests 1 from r1, 2 from r2 and 3 from r3 with priority 100

c1.release

–> releases 1 from r1, 2 from r2 and 3 from r3

yield self.request(r1,(r2,2),(r3,3,100))

c1.release((r2,1))

–> releases 1 from r2

yield self.request(r1,(r2,2),(r3,3,100))

c1.release((r2,1),r3)

–> releases 2 from r2,and 3 from r3

remaining_duration(value: float = None, priority: float = 0, urgent: bool = False) float
Parameters:

value (float) –

set the remaining_duration

The action depends on the status where the component is in:

  • passive: the remaining duration is update according to the given value

  • standby and current: not allowed

  • scheduled: the component is rescheduled according to the given value

  • waiting or requesting: the fail_at is set according to the given value

  • interrupted: the remaining_duration is updated according to the given value

priorityfloat

priority

default: 0

if a component has the same time on the event list, this component is sorted accoring to the priority.

urgentbool

urgency indicator

if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

if True, the component will be scheduled in front of all components scheduled for the same time and priority

Returns:

remaining duration – if passive, remaining time at time of passivate

if scheduled, remaing time till scheduled time

if requesting or waiting, time till fail_at time

else: 0

Return type:

float

Note

This method is useful for interrupting a process and then resuming it, after some (breakdown) time

remove_animation_children() None

removes animation children

Note

Normally, the animation_children are removed automatically upon termination of a component (when it terminates)

request(*args, **kwargs) None

request from a resource or resources

Parameters:

args (sequence of items where each item can be:) –

  • resource, where quantity=1, priority=tail of requesters queue

  • tuples/list containing a resource, a quantity and optionally a priority.

    if the priority is not specified, the request for the resource be added to the tail of the requesters queue

priorityfloat

priority of the fail event

default: 0

if a component has the same time on the event list, this component is sorted according to the priority.

urgentbool

urgency indicator

if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

if True, the component will be scheduled in front of all components scheduled for the same time and priority

fail_atfloat or distribution

time out

if the request is not honored before fail_at, the request will be cancelled and the parameter failed will be set.

if not specified, the request will not time out.

if distribution, the distribution is sampled

fail_delayfloat or distribution

time out

if the request is not honored before now+fail_delay, the request will be cancelled and the parameter failed will be set.

if not specified, the request will not time out.

if distribution, the distribution is sampled

oneofbool

if oneof is True, just one of the requests has to be met (or condition), where honoring follows the order given.

if oneof is False (default), all requests have to be met to be honored

modestr preferred

mode

will be used in trace and can be used in animations

if nothing specified, the mode will be unchanged.

also mode_time will be set to now, if mode is set.

cap_nowbool

indicator whether times (fail_at, fail_delay) in the past are allowed. If, so now() will be used. default: sys.default_cap_now(), usualy False

Note

Not allowed for data components or main.

Only if yieldless is False: If to be used for the current component (which will be nearly always the case), use yield self.request(...).

If the same resource is specified more that once, the quantities are summed

The requested quantity may exceed the current capacity of a resource

The parameter failed will be reset by a calling request or wait

Example

For yieldless, refrain from yield !

yield self.request(r1)

–> requests 1 from r1

yield self.request(r1,r2)

–> requests 1 from r1 and 1 from r2

yield self.request(r1,(r2,2),(r3,3,100))

–> requests 1 from r1, 2 from r2 and 3 from r3 with priority 100

yield self.request((r1,1),(r2,2))

–> requests 1 from r1, 2 from r2

yield self.request(r1, r2, r3, oneoff=True)

–> requests 1 from r1, r2 or r3

requested_quantity(resource: Resource = None) float
Parameters:

resource (Resoure) – resource to be queried

Returns:

the requested (not yet honored) quantity from a resource – if there is no request for the resource, 0 will be returned

Return type:

float or int

requested_resources() List
Returns:

list of requested resources

Return type:

list

resume(all: bool = False, mode: str = None, priority: float = 0, urgent: bool = False) None

resumes an interrupted component

Parameters:
  • all (bool) –

    if True, the component returns to the original status, regardless of the number of interrupt levels

    if False (default), the interrupt level will be decremented and if the level reaches 0, the component will return to the original status.

  • mode (str preferred) –

    mode

    will be used in trace and can be used in animations

    if nothing is specified, the mode will be unchanged.

    also mode_time will be set to now, if mode is set.

  • priority (float) –

    priority

    default: 0

    if a component has the same time on the event list, this component is sorted accoring to the priority.

urgentbool

urgency indicator

if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

if True, the component will be scheduled in front of all components scheduled for the same time and priority

Note

Can be only applied to interrupted components.

running_process() str
Returns:

name of the running process – if data component, None

Return type:

str

scheduled_priority() float
Returns:

priority the component is scheduled with – returns None otherwise

Return type:

float

Note

The method has to traverse the event list, so performance may be an issue.

scheduled_time() float
Returns:

time the component scheduled for, if it is scheduled – returns inf otherwise

Return type:

float

sequence_number() int
Returns:

sequence_number of the component – (the sequence number at initialization)

normally this will be the integer value of a serialized name.

Non serialized names (without a dot or a comma at the end) will return 1)

Return type:

int

set_mode(value: str = None) None
Parameters:

value (any, str recommended) –

new mode

mode_time will be set to now if omitted, no change

setup() None

called immediately after initialization of a component.

by default this is a dummy method, but it can be overridden.

only keyword arguments will be passed

Example

class Car(sim.Component):
def setup(self, color):

self.color = color

def process(self):

redcar=Car(color=”red”)

bluecar=Car(color=”blue”)

skip_standby(value: bool = None) bool
Parameters:

value (bool) –

new skip_standby value

if omitted, no change

Returns:

skip_standby indicator – components with the skip_standby indicator of True, will not activate standby components after the component became current.

Return type:

bool

standby(mode: str = None) None

puts the component in standby mode

Parameters:

mode (str preferred) –

mode

will be used in trace and can be used in animations

if nothing specified, the mode will be unchanged.

also mode_time will be set to now, if mode is set.

Note

Not allowed for data components or main.

Only if yieldless is False: if to be used for the current component (which will be nearly always the case), use yield self.standby().

successor(q: Queue) Component
Parameters:

q (Queue) – queue where the component belongs to

Returns:

the successor of the component in the queue – if component is not at the tail.

returns None if component is at the tail.

Return type:

Component

suppress_pause_at_step(value: bool = None) bool
Parameters:

value (bool) –

new suppress_trace value

if omitted, no change

Returns:

suppress_pause_at_step – components with the suppress_pause_at_step of True, will be ignored in a step

Return type:

bool

suppress_trace(value: bool = None) bool
Parameters:

value (bool) –

new suppress_trace value

if omitted, no change

Returns:

suppress_trace – components with the suppress_status of True, will be ignored in the trace

Return type:

bool

to_store(store: Store | Iterable, item: Component, priority: float = 0, fail_priority: float = 0, urgent: bool = True, fail_at: float = None, fail_delay: float = None, mode: str = None, cap_now: bool = None) Component

put item to store(s)

Parameters:
  • store (store or iterable stores) – store(s) to put item to

  • item (Component) – component to put to store

  • fail_priority (float) –

    priority of the fail event

    default: 0

    if a component has the same time on the event list, this component is sorted according to the priority.

  • urgent (bool) –

    urgency indicator

    if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

    if True, the component will be scheduled in front of all components scheduled for the same time and priority

  • fail_at (float or distribution) –

    time out

    if the request is not honored before fail_at, the request will be cancelled and the parameter failed will be set.

    if not specified, the request will not time out.

    if distribution, the distribution is sampled

  • fail_delay (float or distribution) –

    time out

    if the request is not honored before now+fail_delay, the request will be cancelled and the parameter failed will be set.

    if not specified, the request will not time out.

    if distribution, the distribution is sampled

  • mode (str preferred) –

    mode

    will be used in trace and can be used in animations

    if nothing specified, the mode will be unchanged.

    also mode_time will be set to now, if mode is set.

  • cap_now (bool) – indicator whether times (fail_at, fail_delay) in the past are allowed. If, so now() will be used. default: sys.default_cap_now(), usualy False

Note

Only allowed for current component

Only if yieldless is False: Always use as use yield self.to_store(...).

The parameter failed will be reset by a calling request, wait, from_store, to_store

to_store_requesters() Queue

get the queue holding all to_store requesting components

Returns:

queue holding all to_store requesting components

Return type:

Queue

to_store_store() Component | None

return store where item was sent to with last self.to_store(…) if valid

Returns:

item returned

Return type:

Component or None, if not valid

wait(*args, **kwargs) None

wait for any or all of the given state values are met

Parameters:

args (sequence of items, where each item can be) –

  • a state, where value=True, priority=tail of waiters queue)

  • a tuple/list containing

    state, a value and optionally a priority.

    if the priority is not specified, this component will be added to the tail of the waiters queue

priorityfloat

priority of the fail event

default: 0

if a component has the same time on the event list, this component is sorted accoring to the priority.

urgentbool

urgency indicator

if False (default), the component will be scheduled behind all other components scheduled for the same time and priority

if True, the component will be scheduled in front of all components scheduled for the same time and priority

fail_atfloat or distribution

time out

if the wait is not honored before fail_at, the wait will be cancelled and the parameter failed will be set.

if not specified, the wait will not time out.

if distribution, the distribution is sampled

fail_delayfloat or distribution

time out

if the wait is not honored before now+fail_delay, the request will be cancelled and the parameter failed will be set.

if not specified, the wait will not time out.

if distribution, the distribution is sampled

allbool

if False (default), continue, if any of the given state/values is met

if True, continue if all of the given state/values are met

modestr preferred

mode

will be used in trace and can be used in animations

if nothing specified, the mode will be unchanged.

also mode_time will be set to now, if mode is set.

cap_nowbool

indicator whether times (fail_at, fail_duration) in the past are allowed. If, so now() will be used. default: sys.default_cap_now(), usualy False

Note

Not allowed for data components or main.

Only if yieldless is False: If to be used for the current component (which will be nearly always the case), use yield self.wait(...).

It is allowed to wait for more than one value of a state

the parameter failed will be reset by a calling wait

If you want to check for all components to meet a value (and clause), use Component.wait(…, all=True)

The value may be specified in three different ways:

  • constant, that value is just compared to state.value()

    yield self.wait((light,”red”))

  • an expression, containg one or more $-signs the $ is replaced by state.value(), each time the condition is tested.

    self refers to the component under test, state refers to the state under test.

    yield self.wait((light,’$ in (“red”,”yellow”)’))

    yield self.wait((level,”$<30”))

  • a function. In that case the parameter should function that should accept three arguments: the value, the component under test and the state under test.

    usually the function will be a lambda function, but that’s not a requirement.

    yield self.wait((light,lambda t, comp, state: t in (“red”,”yellow”)))

    yield self.wait((level,lambda t, comp, state: t < 30))

Example

If yieldless, refrain from yield.

yield self.wait(s1)

–> waits for s1.value()==True

yield self.wait(s1,s2)

–> waits for s1.value()==True or s2.value==True

yield self.wait((s1,False,100),(s2,"on"),s3)

–> waits for s1.value()==False or s2.value==”on” or s3.value()==True

s1 is at the tail of waiters, because of the set priority

yield self.wait(s1,s2,all=True)

–> waits for s1.value()==True and s2.value==True

ComponentGenerator

class salabim.ComponentGenerator(component_class: Type, generator_name: str = None, at: float | Callable = None, delay: float | Callable = None, till: float | Callable = None, duration: float | Callable = None, number: int | Callable = None, iat=None, force_at: bool = False, force_till: bool = False, suppress_trace: bool = False, suppress_pause_at_step: bool = False, disturbance: Callable = None, equidistant: bool = False, at_end: Callable = None, env: Environment = None, **kwargs)

Component generator object

A component generator can be used to genetate components

There are two ways of generating components:

  • according to a given inter arrival time (iat) value or distribution

  • random spread over a given time interval

Parameters:
  • component_class (callable, usually a subclass of Component or Pdf or Cdf distribution) –

    the type of components to be generated

    in case of a distribution, the Pdf or Cdf should return a callable

  • generator_name (str) –

    name of the component generator.

    if the name ends with a period (.), auto serializing will be applied

    if the name end with a comma, auto serializing starting at 1 will be applied

    if omitted, the name will be derived from the name of the component_class, padded with ‘.generator’

  • at (float or distribution) –

    time where the generator starts time

    if omitted, now is used

    if distribution, the distribution is sampled

  • delay (float or distribution) –

    delay where the generator starts (at = now + delay)

    if omitted, no delay

    if distribution, the distribution is sampled

  • till (float or distribution) –

    time up to which components should be generated

    if omitted, no end

    if distribution, the distribution is sampled

  • duration (float or distribution) –

    duration to which components should be generated (till = now + duration)

    if omitted, no end

    if distribution, the distribution is sampled

  • number (int or distribution) –

    (maximum) number of components to be generated

    if distribution, the distribution is sampled

  • iat (float or distribution) –

    inter arrival time (distribution).

    if None (default), a random spread over the interval (at, till) will be used

force_atbool

for iat generation:

if False (default), the first component will be generated at time = at + sample from the iat

if True, the first component will be generated at time = at

for random spread generation:

if False (default), no force for time = at

if True, force the first generation at time = at

force_tillbool

only possible for random spread generation:

if False (default), no force for time = till

if True, force the last generated component at time = till

disturbancecallable (usually a distribution)

for each component to be generated, the disturbance call (sampling) is added to the actual generation time.

disturbance may only be used together with iat. The force_at parameter is not allowed in that case.

suppress_tracebool

suppress_trace indicator

if True, the component generator events will be excluded from the trace

If False (default), the component generator will be traced

Can be queried or set later with the suppress_trace method.

suppress_pause_at_stepbool

suppress_pause_at_step indicator

if True, if this component generator becomes current, do not pause when stepping

If False (default), the component generator will be paused when stepping

Can be queried or set later with the suppress_pause_at_step method.

equidistantbool

spread the arrival moments evenly over the defined duration

in this case, iat may not be specified and number=1 is not allowed.

force_at and force_till are ignored.

at_endcallable

function called upon termination of the generator.

e.g. env.main().activate()

envEnvironment

environment where the component is defined

if omitted, default_env will be used

Note

For iat distributions: if till/duration and number are specified, the generation stops whichever condition comes first.

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the component generator

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

Distributions

class salabim.Beta(alpha: float, beta: float, randomstream: Any = None)

beta distribution

Parameters:
  • alpha (float) –

    alpha shape of the distribution

    should be >0

  • beta (float) –

    beta shape of the distribution

    should be >0

  • randomstream (randomstream) –

    randomstream to be used

    if omitted, random will be used

    if used as random.Random(12299) it assigns a new stream with the specified seed

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribution

Return type:

float

class salabim.Bounded(dis, lowerbound: float = None, upperbound: float = None, fail_value: float = None, number_of_retries: int = None, include_lowerbound: bool = True, include_upperbound: bool = True, time_unit: str = None, env: Environment = None)
Parameters:
  • dis (distribution) – distribution to be bounded

  • lowerbound (float) –

    sample values < lowerbound will be rejected (at most 100 retries)

    if omitted, no lowerbound check

  • upperbound (float) –

    sample values > upperbound will be rejected (at most 100 retries)

    if omitted, no upperbound check

  • fail_value (float) –

    value to be used if. after number_of_tries retries, sample is still not within bounds

    default: lowerbound, if specified, otherwise upperbound

  • number_of_tries (int) –

    number of tries before fail_value is returned

    default: 100

  • include_lowerbound (bool) – if True (default), the lowerbound may be included. if False, the lowerbound will be excluded.

  • include_upperbound (bool) – if True (default), the upperbound may be included. if False, the upperbound will be excluded.

  • time_unit (str) –

    specifies the time unit of the lowerbound or upperbound

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

Note

If, after number_of_tries retries, the sampled value is still not within the given bounds, fail_value will be returned

Samples that cannot be converted to float (only possible with Pdf and CumPdf) are assumed to be within the bounds.

mean() float
Returns:

Mean of the expression of bounded distribution – unless no bounds are specified, returns nan

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the expression of distribution(s)

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

class salabim.Cdf(spec: Iterable, time_unit: str = None, randomstream: Any = None, env: Environment = None)

Cumulative distribution function

Parameters:
  • spec (list or tuple) –

    list with x-values and corresponding cumulative density (x1,c1,x2,c2, …xn,cn)

    Requirements:

    x1<=x2<= …<=xn

    c1<=c2<=cn

    c1=0

    cn>0

    all cumulative densities are auto scaled according to cn, so no need to set cn to 1 or 100.

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

randomstream: randomstream

if omitted, random will be used

if used as random.Random(12299) it defines a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribution

Return type:

float

class salabim.Constant(value: float, time_unit: str = None, randomstream: Any = None, env: Environment = None)

constant distribution

Parameters:
  • value (float) – value to be returned in sample

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

randomstream: randomstream

randomstream to be used

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

Note that this is only for compatibility with other distributions

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

mean() float
Returns:

mean of the distribution (= the specified constant)

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

sample of the distribution (= the specified constant)

Return type:

float

class salabim.Distribution(spec: str, randomstream: Any = None, time_unit: str = None)

Generate a distribution from a string

Parameters:
  • spec (str) –

    • string containing a valid salabim distribution, where only the first letters are relevant and casing is not important. Note that Erlang, Cdf, CumPdf and Poisson require at least two letters (Er, Cd, Cu and Po)

    • string containing one float (c1), resulting in Constant(c1)

    • string containing two floats seperated by a comma (c1,c2), resulting in a Uniform(c1,c2)

    • string containing three floats, separated by commas (c1,c2,c3), resulting in a Triangular(c1,c2,c3)

  • time_unit (str) –

    Supported time_units:

    ”years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    if spec has a time_unit as well, this parameter is ignored

  • randomstream (randomstream) –

    if omitted, random will be used

    if used as random.Random(12299) it assigns a new stream with the specified seed

Note

The randomstream in the specifying string is ignored.

It is possible to use expressions in the specification, as long these are valid within the context of the salabim module, which usually implies a global variable of the salabim package.

Examples

Uniform(13) ==> Uniform(13)

Uni(12,15) ==> Uniform(12,15)

UNIF(12,15) ==> Uniform(12,15)

N(12,3) ==> Normal(12,3)

Tri(10,20). ==> Triangular(10,20,15)

  1. ==> Constant(10)

12,15 ==> Uniform(12,15)

(12,15) ==> Uniform(12,15)

Exp(a) ==> Exponential(100), provided sim.a=100

E(2) ==> Exponential(2) Er(2,3) ==> Erlang(2,3)

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() Any
Returns:

Sample of the distribution

Return type:

any (usually float)

class salabim.Erlang(shape: float, rate: float = None, time_unit: str = None, scale: float = None, randomstream: Any = None, env: Environment = None)

erlang distribution

Parameters:
  • shape (int) –

    shape of the distribution (k)

    should be >0

  • rate (float) –

    rate parameter (lambda)

    if omitted, the scale is used

    should be >0

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

scale: float

scale of the distribution (mu)

if omitted, the rate is used

should be >0

randomstream: randomstream

randomstream to be used

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

Note

Either rate or scale has to be specified, not both.

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribution

Return type:

float

class salabim.Exponential(mean: float = None, time_unit: str = None, rate: float = None, randomstream: Any = None, env: Environment = None)

exponential distribution

Parameters:
  • mean (float) –

    mean of the distribtion (beta)

    if omitted, the rate is used

    must be >0

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

ratefloat

rate of the distribution (lambda)

if omitted, the mean is used

must be >0

randomstream: randomstream

randomstream to be used

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

Note

Either mean or rate has to be specified, not both

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribution

Return type:

float

class salabim.External(dis: Any, *args, **kwargs)

External distribution function

This distribution allows distributions from other modules, notably random, numpy.random and scipy.stats to be used as were they salabim distributions.

Parameters:
  • dis (external distribution) –

    either

    • random.xxx

    • numpy.random.xxx

    • scipy.stats.xxx

  • *args (any) – positional arguments to be passed to the dis distribution

  • **kwargs (any) – keyword arguments to be passed to the dis distribution

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

mean() float
Returns:

mean of the distribution – only available for scipy.stats distribution. Otherwise nan will be returned.

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() Any
Returns:

Sample of the distribution via external distribution method

Return type:

any (usually float)

class salabim.Gamma(shape: float, scale: float = None, time_unit: str = None, rate=None, randomstream: Any = None, env: Environment = None)

gamma distribution

Parameters:
  • shape (float) –

    shape of the distribution (k)

    should be >0

  • scale (float) –

    scale of the distribution (teta)

    should be >0

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

ratefloat

rate of the distribution (beta)

should be >0

randomstream: randomstream

randomstream to be used

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

Note

Either scale or rate has to be specified, not both.

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribution

Return type:

float

class salabim.Normal(mean: float, standard_deviation: float = None, time_unit: str = None, coefficient_of_variation: float = None, use_gauss: bool = False, randomstream: Any = None, env: Environment = None)

normal distribution

Parameters:
  • mean (float) – mean of the distribution

  • standard_deviation (float) –

    standard deviation of the distribution

    if omitted, coefficient_of_variation, is used to specify the variation if neither standard_devation nor coefficient_of_variation is given, 0 is used, thus effectively a contant distribution

    must be >=0

  • coefficient_of_variation (float) –

    coefficient of variation of the distribution

    if omitted, standard_deviation is used to specify variation

    the resulting standard_deviation must be >=0

  • use_gauss (bool) –

    if False (default), use the random.normalvariate method

    if True, use the random.gauss method

    the documentation for random states that the gauss method should be slightly faster, although that statement is doubtful.

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

randomstream: randomstream

randomstream to be used

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribution

Return type:

float

class salabim.Pdf(spec: Iterable | Dict, probabilities=None, time_unit: str = None, randomstream: Any = None, env: Environment = None)

Probability distribution function

Parameters:
  • spec (list, tuple or dict) –

    either

    • if no probabilities specified:

      list/tuple with x-values and corresponding probability dict where the keys are re x-values and the values are probabilities (x0, p0, x1, p1, …xn,pn)

    • if probabilities is specified:

      list with x-values

  • probabilities (iterable or float) –

    if omitted, spec contains the probabilities

    the iterable (p0, p1, …pn) contains the probabilities of the corresponding x-values from spec.

    alternatively, if a float is given (e.g. 1), all x-values have equal probability. The value is not important.

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

randomstreamrandomstream

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

Note

p0+p1=…+pn>0

all densities are auto scaled according to the sum of p0 to pn, so no need to have p0 to pn add up to 1 or 100.

The x-values can be any type.

If it is a salabim distribution, not the distribution, but a sample will be returned when calling sample.

mean() float
Returns:

mean of the distribution – if the mean can’t be calculated (if not all x-values are scalars or distributions), nan will be returned.

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample(n: int = None) Any
Parameters:

n (number of samples : int) –

if not specified, specifies just return one sample, as usual

if specified, return a list of n sampled values from the distribution without replacement. This requires that all probabilities are equal.

If n > number of values in the Pdf distribution, n is assumed to be the number of values in the distribution.

If a sampled value is a distribution, a sample from that distribution will be returned.

Returns:

Sample of the distribution – In case n is specified, returns a list of n values

Return type:

any (usually float) or list

class salabim.Poisson(mean: float, randomstream: Any = None, prefer_numpy: bool = False)

Poisson distribution

Parameters:
  • mean (float) – mean (lambda) of the distribution

  • randomstream (randomstream) –

    randomstream to be used

    if omitted, random will be used

    if used as random.Random(12299) it assigns a new stream with the specified seed

Note

The run time of this function increases when mean (lambda) increases.

It is not recommended to use mean (lambda) > 100

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() int
Returns:

Sample of the distribution

Return type:

int

class salabim.Triangular(low: float, high: float = None, mode: float = None, time_unit: str = None, randomstream: Any = None, env: Environment = None)

triangular distribution

Parameters:
  • low (float) – lowerbound of the distribution

  • high (float) –

    upperbound of the distribution

    if omitted, low will be used, thus effectively a constant distribution

    high must be >= low

  • mode (float) –

    mode of the distribution

    if omitted, the average of low and high will be used, thus a symmetric triangular distribution

    mode must be between low and high

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

randomstream: randomstream

randomstream to be used

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribtion

Return type:

float

class salabim.Uniform(lowerbound: float, upperbound: float = None, time_unit: str = None, randomstream: Any = None, env: Environment = None)

uniform distribution

Parameters:
  • lowerbound (float) – lowerbound of the distribution

  • upperbound (float) –

    upperbound of the distribution

    if omitted, lowerbound will be used

    must be >= lowerbound

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

randomstream: randomstream

randomstream to be used

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribution

Return type:

float

class salabim.Weibull(scale: float, shape: float, time_unit: str = None, randomstream: Any = None, env: Environment = None)

weibull distribution

Parameters:
  • scale (float) – scale of the distribution (alpha or k)

  • shape (float) –

    shape of the distribution (beta or lambda)

    should be >0

  • time_unit (str) –

    specifies the time unit

    must be one of “years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

    default : no conversion

randomstream: randomstream

randomstream to be used

if omitted, random will be used

if used as random.Random(12299) it assigns a new stream with the specified seed

envEnvironment

environment where the distribution is defined

if omitted, default_env will be used

mean() float
Returns:

Mean of the distribution

Return type:

float

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the distribution

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

sample() float
Returns:

Sample of the distribution

Return type:

float

Environment

class salabim.Environment(trace: bool = False, random_seed: Hashable = None, set_numpy_random_seed: bool = True, time_unit: str = 'n/a', datetime0: bool | datetime | str = False, name: str = None, print_trace_header: bool = True, isdefault_env: bool = True, retina: bool = False, do_reset: bool = None, blind_animation: bool = False, yieldless: bool = None, *args, **kwargs)

environment object

Parameters:
  • trace (bool or file handle) –

    defines whether to trace or not

    if this a file handle (open for write), the trace output will be sent to this file.

    if omitted, False

  • random_seed (hashable object, usually int) –

    the seed for random, equivalent to random.seed()

    if “*”, a purely random value (based on the current time) will be used (not reproducable)

    if the null string, no action on random is taken

    if None (the default), 1234567 will be used.

  • time_unit (str) –

    Supported time_units:

    ”years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”, “n/a”

    default: “n/a”

  • datetime0 (bool or datetime.datetime) –

    display time and durations as datetime.datetime/datetime.timedelta

    if falsy (default), disabled

    if True, the t=0 will correspond to 1 January 1970

    if no time_unit is specified, but datetime0 is not falsy, time_unit will be set to seconds

  • name (str) –

    name of the environment

    if the name ends with a period (.), auto serializing will be applied

    if the name end with a comma, auto serializing starting at 1 will be applied

    if omitted, the name will be derived from the class (lowercased) or “default environment” if isdefault_env is True.

  • print_trace_header (bool) –

    if True (default) print a (two line) header line as a legend

    if False, do not print a header

    note that the header is only printed if trace=True

  • isdefault_env (bool) –

    if True (default), this environment becomes the default environment

    if False, this environment will not be the default environment

    if omitted, this environment becomes the default environment

set_numpy_random_seedbool

if True (default), numpy.random.seed() will be called with the given seed.

This is particularly useful when using External distributions.

If numpy is not installed, this parameter is ignored

if False, numpy.random.seed is not called.

do_resetbool

if True, reset the simulation environment

if False, do not reset the simulation environment

if None (default), reset the simulation environment when run under Pythonista, otherwise no reset

blind_animationbool

if False (default), animation will be performed as expected

if True, animations will run silently. This is useful to make videos when tkinter is not installed (installable). This is particularly useful when running a simulation on a server. Note that this will show a slight performance increase, when creating videos.

Note

The trace may be switched on/off later with trace

The seed may be later set with random_seed()

Initially, the random stream will be seeded with the value 1234567. If required to be purely, not reproducable, values, use random_seed=”*”.

an_clocktext() None

function to initialize the system clocktext

called by run(), if animation is True.

may be overridden to change the standard behaviour.

an_menu_buttons() None

function to initialize the menu buttons

may be overridden to change the standard behaviour.

an_modelname() None

function to show the modelname

may be overridden to change the standard behaviour.

an_synced_buttons() None

function to initialize the synced buttons

may be overridden to change the standard behaviour.

an_unsynced_buttons() None

function to initialize the unsynced buttons

may be overridden to change the standard behaviour.

animate(value: str | bool = None)

animate indicator

Parameters:

value (bool) –

new animate indicator

if ‘?’, animation will be set, if possible if not specified, no change

Returns:

animate status

Return type:

bool

Note

When the run is not issued, no action will be taken.

animate3d(value: bool = None)

animate3d indicator

Parameters:

value (bool) –

new animate3d indicator

if ‘?’, 3D-animation will be set, if possible if not specified, no change

Returns:

animate3d status

Return type:

bool

Note

When the animate is not issued, no action will be taken.

animate_debug(value: bool = None)

Animate debug

Parameters:

value (bool) –

animate_debug

default: no change

initially: False

Returns:

animate_debug

Return type:

bool

animation_parameters(animate: bool | str = None, synced: bool = None, speed: float = None, width: int = None, height: int = None, title: str = None, show_menu_buttons: bool = None, x0: float = None, y0: float = None, x1: float = None, background_color: str | Iterable[float] = None, foreground_color: str | Iterable[float] = None, background3d_color: str | Iterable[float] = None, fps: float = None, modelname: str = None, use_toplevel: bool = None, show_fps: bool = None, show_time: bool = None, maximum_number_of_bitmaps: int = None, video: Any = None, video_repeat: int = None, video_pingpong: bool = None, audio: str = None, audio_speed: float = None, animate_debug: bool = None, animate3d: bool = None, width3d: int = None, height3d: int = None, video_width: int | str = None, video_height: int | str = None, video_mode: str = None, position: Any = None, position3d: Any = None, visible: bool = None)

set animation parameters

Parameters:
  • animate (bool) –

    animate indicator

    new animate indicator

    if ‘?’, animation will be set, possible

    if not specified, no change

  • animate3d (bool) –

    animate3d indicator

    new animate3d indicator

    if ‘?’, 3D-animation will be set, possible

    if not specified, no change

  • synced (bool) –

    specifies whether animation is synced

    if omitted, no change. At init of the environment synced will be set to True

  • speed (float) –

    speed

    specifies how much faster or slower than real time the animation will run. e.g. if 2, 2 simulation time units will be displayed per second.

  • width (int) –

    width of the animation in screen coordinates

    if omitted, no change. At init of the environment, the width will be set to 1024 for non Pythonista and the current screen width for Pythonista.

  • height (int) –

    height of the animation in screen coordinates

    if omitted, no change. At init of the environment, the height will be set to 768 for non Pythonista and the current screen height for Pythonista.

  • position (tuple(x,y)) –

    position of the animation window

    if omitted, no change. At init of the environment, the position will be set to (0, 0)

    no effect for Pythonista

  • width3d (int) –

    width of the 3d animation in screen coordinates

    if omitted, no change. At init of the environment, the 3d width will be set to 1024.

  • height3d (int) –

    height of the 3d animation in screen coordinates

    if omitted, no change. At init of the environment, the 3d height will be set to 768.

  • position3d (tuple(x,y)) –

    position of the 3d animation window

    At init of the environment, the position will be set to (0, 0)

    This has to be set before the 3d animation starts as the window can only be postioned at initialization

  • title (str) –

    title of the canvas window

    if omitted, no change. At init of the environment, the title will be set to salabim.

    if “”, the title will be suppressed.

  • x0 (float) –

    user x-coordinate of the lower left corner

    if omitted, no change. At init of the environment, x0 will be set to 0.

  • y0 (float) –

    user y_coordinate of the lower left corner

    if omitted, no change. At init of the environment, y0 will be set to 0.

  • x1 (float) –

    user x-coordinate of the lower right corner

    if omitted, no change. At init of the environment, x1 will be set to 1024 for non Pythonista and the current screen width for Pythonista.

  • background_color (colorspec) –

    color of the background

    if omitted, no change. At init of the environment, this will be set to white.

  • foreground_color (colorspec) –

    color of foreground (texts)

    if omitted and background_color is specified, either white of black will be used, in order to get a good contrast with the background color.

    if omitted and background_color is also omitted, no change. At init of the environment, this will be set to black.

  • background3d_color (colorspec) –

    color of the 3d background

    if omitted, no change. At init of the environment, this will be set to black.

  • fps (float) – number of frames per second

  • modelname (str) –

    name of model to be shown in upper left corner, along with text “a salabim model”

    if omitted, no change. At init of the environment, this will be set to the null string, which implies suppression of this feature.

  • use_toplevel (bool) –

    if salabim animation is used in parallel with other modules using tkinter, it might be necessary to initialize the root with tkinter.TopLevel(). In that case, set this parameter to True.

    if False (default), the root will be initialized with tkinter.Tk()

  • show_fps (bool) –

    if True, show the number of frames per second

    if False, do not show the number of frames per second (default)

  • show_time (bool) –

    if True, show the time (default)

    if False, do not show the time

  • show_menu_buttons (bool) –

    if True, show the menu buttons (default)

    if False, do not show the menu buttons

  • maximum_number_of_bitmaps (int) – maximum number of tkinter bitmaps (default 4000)

  • video (str) –

    if video is not omitted, a video with the name video will be created.

    Normally, use .mp4 as extension.

    If the extension is .gif or .png an animated gif / png file will be written, unless there is a * in the filename

    If the extension is .gif, .jpg, .png, .bmp, .ico or .tiff and one * appears in the filename, individual frames will be written with a six digit sequence at the place of the asteriks in the file name. If the video extension is not .gif, .jpg, .png, .bmp, .ico or .tiff, a codec may be added by appending a plus sign and the four letter code name, like “myvideo.avi+DIVX”.

    If no codec is given, MJPG will be used for .avi files, otherwise .mp4v

    Under PyDroid only .avi files are supported.

  • video_repeat (int) –

    number of times animated gif or png should be repeated

    0 means inifinite

    at init of the environment video_repeat is 1

    this only applies to gif and png files production.

  • video_pingpong (bool) –

    if True, all frames will be added reversed at the end of the video (useful for smooth loops) at init of the environment video_pingpong is False

    this only applies to gif and png files production.

  • audio (str) –

    name of file to be played (mp3 or wav files)

    if the none string, the audio will be stopped

    default: no change

    for more information, see Environment.audio()

  • visible (bool) –

    if True (start condition), the animation window will be visible

    if False, the animation window will be hidden (‘withdrawn’)

Note

The y-coordinate of the upper right corner is determined automatically in such a way that the x and y scaling are the same.

animation_post_tick(t: float) None

called just after the animation object loop.

Default behaviour: just return

Parameters:

t (float) – Current (animation) time.

animation_pre_tick(t: float) None

called just before the animation object loop.

Default behaviour: just return

Parameters:

t (float) – Current (animation) time.

audio(filename: str)

Play audio during animation

Parameters:

filename (str) –

name of file to be played (mp3 or wav files)

if “”, the audio will be stopped

optionaly, a start time in seconds may be given by appending the filename a > followed by the start time, like ‘mytune.mp3>12.5’ if not specified (None), no change

Returns:

filename being played (”” if nothing is being played)

Return type:

str

Note

Only supported on Windows and Pythonista platforms. On other platforms, no effect.

Variable bit rate mp3 files may be played incorrectly on Windows platforms. Try and use fixed bit rates (e.g. 128 or 320 kbps)

audio_speed(value: float = None)

Play audio during animation

Parameters:

value (float) –

animation speed at which the audio should be played

default: no change

initially: 1

Returns:

speed being played

Return type:

int

background3d_color(value: str | Iterable[float] = None)

background3d_color of the animation

Parameters:

value (colorspec) –

new background_color

if not specified, no change

Returns:

background3d_color of animation

Return type:

colorspec

background_color(value=None)

background_color of the animation

Parameters:

value (colorspec) –

new background_color

if not specified, no change

Returns:

background_color of animation

Return type:

colorspec

base_name() str

returns the base name of the environment (the name used at initialization)

beep() None

Beeps

Works only on Windows and iOS (Pythonista). For other platforms this is just a dummy method.

camera_auto_print(value: bool = None) bool

queries or set camera_auto_print

Parameters:

value (boolean) –

if None (default), no action

if True, camera_print will be called on each camera control keypress

if False, no automatic camera_print

Returns:

Current status

Return type:

bool

Note

The camera_auto_print functionality is useful to get the spec for camera_move()

camera_move(spec: str = '', lag: float = 1, offset: float = 0, enabled: bool = True)

Moves the camera according to the given spec, which is normally a collection of camera_print outputs.

Parameters:
  • spec (str) – output normally obtained from camera_auto_print lines

  • lag (float) – lag time (for smooth camera movements) (default: 1))

  • offset (float) – the duration (can be negative) given is added to the times given in spec. Default: 0

  • enabled (bool) –

    if True (default), move camera according to spec/lag

    if False, freeze camera movement

color_interp(x: float, xp: Iterable, fp: Iterable)

linear interpolation of a color

Parameters:
  • x (float) – target x-value

  • xp (list of float, tuples or lists) – values on the x-axis

  • fp (list of colorspecs) –

    values on the y-axis

    should be same length as xp

Returns:

interpolated color value

Return type:

tuple

Notes

If x < xp[0], fp[0] will be returned

If x > xp[-1], fp[-1] will be returned

colorinterpolate(t: float, t0: float, t1: float, v0: Any, v1: Any) Any

does linear interpolation of colorspecs

Parameters:
  • t (float) – value to be interpolated from

  • t0 (float) – f(t0)=v0

  • t1 (float) – f(t1)=v1

  • v0 (colorspec) – f(t0)=v0

  • v1 (colorspec) – f(t1)=v1

Returns:

linear interpolation between v0 and v1 based on t between t0 and t

Return type:

colorspec

Note

Note that no extrapolation is done, so if t<t0 ==> v0 and t>t1 ==> v1

This function is heavily used during animation

colorspec_to_tuple(colorspec: str | Iterable[float]) Tuple

translates a colorspec to a tuple

Parameters:

colorspec (tuple, list or str) –

#rrggbb ==> alpha = 255 (rr, gg, bb in hex)

#rrggbbaa ==> alpha = aa (rr, gg, bb, aa in hex)

colorname ==> alpha = 255

(colorname, alpha)

(r, g, b) ==> alpha = 255

(r, g, b, alpha)

"fg" ==> foreground_color

"bg" ==> background_color

Return type:

(r, g, b, a)

current_component() Component
Returns:

the current_component

Return type:

Component

datetime0(datetime0: datetime = None) datetime

Gets and/or sets datetime0

Parameters:

datetime0 (bool or datetime.datetime) –

if omitted, nothing will be set

if falsy, disabled

if True, the t=0 will correspond to 1 January 1970

if a datetime.datetime value, this will become datetime0

if no time_unit is specified, but datetime0 is not falsy, time_unit will be set to seconds

Returns:

current value of datetime0

Return type:

bool or datetime.datetime

datetime_to_t(datetime: datetime) float
Parameters:

datetime (datetime.datetime) –

Returns:

datetime translated to simulation time in the current time_unit

Return type:

float

Raises:

ValueError – if datetime0 is False

dateutil_parse(spec: str) datetime

Parses a string to a datetime, using dateutil.parser.parse with dayfirst=False, yearfirst=True

Parameters:

spec (str) – string to be converted into datetime.datetime

Returns:

parsed value of spec

Return type:

datetime.datetime

Note

The modules dateutil has to be installed, preferably with pip install python-dateutil

It is possible to override this method, like

import dateutil.parser sim.Environment.dateutil_parse = lambda self, spec: dateutil.parser.parse(spec, dayfirst=True, yearfirst=True)

or something that does not need dateutil at all

days(t: float) float

convert the given time in days to the current time unit

Parameters:

t (float or distribution) –

time in days

if distribution, the distribution is sampled

Returns:

time in days, converted to the current time_unit

Return type:

float

duration_to_str(duration: float) str
Parameters:

duration (float) – duration to be converted to string in trace

Returns:

duration in required format – default: f”{duration:.3f}” if datetime0 is False or duration in the format “hh:mm:dd” or “d hh:mm:ss”

Return type:

str

Note

May be overrridden.

duration_to_timedelta(duration: float) timedelta
Parameters:

duration (float) –

Returns:

timedelta corresponding to duration

Return type:

datetime.timedelta

Raises:

ValueError – if time unit is not set

foreground_color(value: str | Iterable[float] = None)

foreground_color of the animation

Parameters:

value (colorspec) –

new foreground_color

if not specified, no change

Returns:

foreground_color of animation

Return type:

colorspec

fps(value: float = None) float
Parameters:

value (float) –

new fps

if not specified, no change

Returns:

fps

Return type:

bool

full_screen()

sets the animation window to full screen.

Note

This sets the title to “”, so the title bar will be hidden

Note

x0 and y0 will be set to 0, x1 will be set to the screen width

get_time_unit(template: str = None) str

gets time unit

Parameters:

template (str) –

normally only used in UI functions

default: just return time_unit (including n/a)

if “d”, time_unit as duration

if “t”, time_unit as time

if “(d)”, time_unit as (duration)

if “(t)”, time_unit as (time)

Note that n/a is suppressed and an extra space is added at the front if result is not the null strinf

Returns:

Current time unit dimension (default “n/a”)

Return type:

str

height(value: int = None) int

height of the animation in screen coordinates

Parameters:

value (int) –

new height

if not specified, no change

Returns:

height of animation

Return type:

int

height3d(value: int = None) int

height of the 3d animation in screen coordinates

Parameters:

value (int) –

new 3d height

if not specified, no change

Returns:

height of 3d animation

Return type:

int

hours(t: float) float

convert the given time in hours to the current time unit

Parameters:

t (float or distribution) –

time in hours

if distribution, the distribution is sampled

Returns:

time in hours, converted to the current time_unit

Return type:

float

insert_frame(image: Any, number_of_frames: int = 1) None

Insert image as frame(s) into video

Parameters:
  • image (Pillow image, str or Path object) – Image to be inserted

  • nuumber_of_frames (int) – Number of 1/30 second long frames to be inserted

is_dark(colorspec: str | Iterable[float]) bool
Parameters:

colorspec (colorspec) – color to check

Returns:

True, if the colorspec is dark (rather black than white)

False, if the colorspec is light (rather white than black

if colorspec has alpha=0 (total transparent), the background_color will be tested

Return type:

bool

is_videoing() bool

video recording status

Returns:

video recording status – True, if video is being recorded

False, otherwise

Return type:

bool

main() Component
Returns:

the main component

Return type:

Component

maximum_number_of_bitmaps(value: int = None) int

maximum number of bitmaps (applies to animation with tkinter only)

Parameters:

value (int) –

new maximum_number_of_bitmaps

if not specified, no change

Returns:

maximum number of bitmaps

Return type:

int

microseconds(t: float) float

convert the given time in microseconds to the current time unit

Parameters:

t (float or distribution) –

time in microseconds

if distribution, the distribution is sampled

Returns:

time in microseconds, converted to the current time_unit

Return type:

float

milliseconds(t: float) float

convert the given time in milliseconds to the current time unit

Parameters:

t (float or distribution) –

time in milliseconds

if distribution, the distribution is sampled

Returns:

time in milliseconds, converted to the current time_unit

Return type:

float

minutes(t: float) float

convert the given time in minutes to the current time unit

Parameters:

t (float or distribution) –

time in minutes

if distribution, the distribution is sampled

Returns:

time in minutes, converted to the current time_unit

Return type:

float

modelname(value: str = None)
Parameters:

value (str) –

new modelname

if not specified, no change

Returns:

modelname

Return type:

str

Note

If modelname is the null string, nothing will be displayed.

name(value: str = None) str
Parameters:

value (str) – new name of the environment if omitted, no change

Returns:

Name of the environment

Return type:

str

Note

base_name and sequence_number are not affected if the name is changed

now() float
Returns:

the current simulation time

Return type:

float

paused(value: bool = None) bool

paused status

Parameters:

value (bool) –

new paused status

defines whether to be paused or not

if omitted, no change

Returns:

paused status

Return type:

bool

Note

If you want to test the status, always include parentheses, like

if env.paused():

peek() float

returns the time of the next component to become current

if there are no more events, peek will return inf

Only for advance use with animation / GUI event loops

position(value: Any = None)

position of the animation window

Parameters:

value (tuple (x, y)) –

new position

if not specified, no change

Returns:

position of animation window

Return type:

tuple (x,y)

position3d(value: Any = None)

position of the 3d animation window

Parameters:

value (tuple (x, y)) –

new position

if not specified, no change

Returns:

position of th 3d animation window

Return type:

tuple (x,y)

Note

This must be given before the 3d animation is started.

print_info(as_str: bool = False, file: TextIO = None) str

prints information about the environment

Parameters:
  • as_str (bool) – if False (default), print the info if True, return a string containing the info

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

info (if as_str is True)

Return type:

str

print_trace(s1: str = '', s2: str = '', s3: str = '', s4: str = '', s0: str = None, _optional: bool = False)

prints a trace line

Parameters:
  • s1 (str) – part 1 (usually formatted now), padded to 10 characters

  • s2 (str) – part 2 (usually only used for the compoent that gets current), padded to 20 characters

  • s3 (str) – part 3, padded to 35 characters

  • s4 (str) – part 4

  • s0 (str) – part 0. if omitted, the line number from where the call was given will be used at the start of the line. Otherwise s0, left padded to 7 characters will be used at the start of the line.

  • _optional (bool) – for internal use only. Do not set this flag!

Note

if self.trace is False, nothing is printed

if the current component’s suppress_trace is True, nothing is printed

print_trace_header() None

print a (two line) header line as a legend

also the legend for line numbers will be printed

not that the header is only printed if trace=True

reset_now(new_now: float = 0) None

reset the current time

Parameters:

new_now (float or distribution) –

now will be set to new_now

default: 0

if distribution, the distribution is sampled

Note

Internally, salabim still works with the ‘old’ time. Only in the interface from and to the user program, a correction will be applied.

The registered time in monitors will be always is the ‘old’ time. This is only relevant when using the time value in Monitor.xt() or Monitor.tx().

run(duration: float = None, till: float = None, priority: Any = inf, urgent: bool = False, cap_now: bool = None)

start execution of the simulation

Parameters:
  • duration (float or distribution) –

    schedule with a delay of duration

    if 0, now is used

    if distribution, the distribution is sampled

  • till (float or distribution) –

    schedule time

    if omitted, inf is assumed. See also note below

    if distribution, the distribution is sampled

  • priority (float) –

    priority

    default: inf

    if a component has the same time on the event list, main is sorted accoring to the priority. The default value of inf makes that all components will finish before the run is ended

  • urgent (bool) –

    urgency indicator

    if False (default), main will be scheduled behind all other components scheduled with the same time and priority

    if True, main will be scheduled in front of all components scheduled for the same time and priority

  • cap_now (bool) – indicator whether times (till, duration) in the past are allowed. If, so now() will be used. default: sys.default_cap_now(), usualy False

Note

if neither till nor duration is specified, the main component will be reactivated at the time there are no more events on the eventlist, i.e. possibly not at inf.

if you want to run till inf (particularly when animating), issue run(sim.inf)

only issue run() from the main level

scale() float

scale of the animation, i.e. width / (x1 - x0)

Returns:

scale

Return type:

float

Note

It is not possible to set this value explicitely.

screen_to_user_coordinates_size(screensize: float) float

converts a screen size to a value to be used with user coordinates

Parameters:

screensize (float) – screen size to be converted

Returns:

value corresponding with screensize in user coordinates

Return type:

float

screen_to_user_coordinates_x(screenx: float) float

converts a screen x coordinate to a user x coordinate

Parameters:

screenx (float) – screen x coordinate to be converted

Returns:

user x coordinate

Return type:

float

screen_to_user_coordinates_y(screeny: float) float

converts a screen x coordinate to a user x coordinate

Parameters:

screeny (float) – screen y coordinate to be converted

Returns:

user y coordinate

Return type:

float

seconds(t: float) float

convert the given time in seconds to the current time unit

Parameters:

t (float or distribution) –

time in seconds

if distribution, the distribution is sampled

Returns:

time in seconds, converted to the current time_unit

Return type:

float

sequence_number() int
Returns:

sequence_number of the environment – (the sequence number at initialization)

normally this will be the integer value of a serialized name.

Non serialized names (without a dot or a comma at the end) will return 1)

Return type:

int

setup() None

called immediately after initialization of an environment.

by default this is a dummy method, but it can be overridden.

only keyword arguments are passed

show_camera_position(over3d: bool = None) None

show camera position on the tkinter window or over3d window

The 7 camera settings will be shown in the top left corner.

Parameters:

over3d (bool) –

if False (default), present on 2D screen

if True, present on 3D overlay

show_fps(value: bool = None) bool
Parameters:

value (bool) –

new show_fps

if not specified, no change

Returns:

show_fps

Return type:

bool

show_menu_buttons(value: bool = None) bool

controls menu buttons

Parameters:

value (bool) –

if True, menu buttons are shown

if False, menu buttons are hidden

if not specified, no change

Returns:

show menu button status

Return type:

bool

show_time(value: bool = None) bool
Parameters:

value (bool) –

new show_time

if not specified, no change

Returns:

show_time

Return type:

bool

snapshot(filename: str, video_mode: str = '2d') None

Takes a snapshot of the current animated frame (at time = now()) and saves it to a file

Parameters:
  • filename (str) –

    file to save the current animated frame to.

    The following formats are accepted: .png, .jpg, .bmp, .ico, .gif, .webp and .tiff. Other formats are not possible. Note that, apart from .JPG files. the background may be semi transparent by setting the alpha value to something else than 255.

  • video_mode (str) –

    specifies what to save

    if “2d” (default), the tkinter window will be saved

    if “3d”, the OpenGL window will be saved (provided animate3d is True)

    if “screen” the complete screen will be saved (no need to be in animate mode)

    no scaling will be applied.

spec_to_duration(spec: int | float | str | datetime | callable) float

Converts a generic spec to a proper float duration

Parameters:

spec (int, float, str, datetime.timedelta or callable) –

Returns:

duration

Return type:

float

Note

Might require dateutil

spec_to_time(spec: int | float | str | datetime | callable) float

Converts a generic spec to a proper float time

Parameters:

spec (int, float, str, datetime.datetime or callable) –

Returns:

time

Return type:

float

Note

Might require dateutil

speed(value: float = None) float
Parameters:

value (float) –

new speed

if not specified, no change

Returns:

speed

Return type:

float

start_ui(window_size: Tuple = (None, None), window_position: Tuple = (None, None), elements: List = None, user_handle_event: Callable = None, default_elements: bool = True, actions: List = None)

start the PySimpleGUI UI

Parameters:
  • window_size (tuple) –

    width (int) ; default (None): 300

    height (int) ; default (None): 600

  • window_position (tuple) –

    x (int) ; default (None): width of animation

    y (int) ; default (None): 0

  • elements (list) – extra elements to add (refer to PySimpleGUI reference)

  • user_handle_event (callable) – default: no handler

  • default_elements (bool) –

    if True (default), UI will start with the standard elements

    if False, no standard elements will be used. Use elements to add required standard elements

step() None

executes the next step of the future event list

for advanced use with animation / GUI loops

suppress_trace()

context manager to the trace temporarily

Note

To be used as

with env.suppress_trace():
    ...
suppress_trace_linenumbers(value: bool = None) bool

indicates whether line numbers should be suppressed (False by default)

Parameters:

value (bool) –

new suppress_trace_linenumbers status

if omitted, no change

Returns:

suppress_trace_linenumbers status

Return type:

bool

Note

By default, suppress_trace_linenumbers is False, meaning that line numbers are shown in the trace. In order to improve performance, line numbers can be suppressed.

suppress_trace_standby(value: bool = None) bool

suppress_trace_standby status

Parameters:

value (bool) –

new suppress_trace_standby status

if omitted, no change

Returns:

suppress trace status

Return type:

bool

Note

By default, suppress_trace_standby is True, meaning that standby components are (apart from when they become non standby) suppressed from the trace.

If you set suppress_trace_standby to False, standby components are fully traced.

synced(value: bool = None) bool
Parameters:

value (bool) –

new synced

if not specified, no change

Returns:

synced

Return type:

bool

t() float
Returns:

the current simulation animation time

Return type:

float

t_to_datetime(t: float) Any
Parameters:

t (float) – time to convert

Returns:

t (in the current time unit) translated to the corresponding datetime

Return type:

float

Raises:

ValueError – if datetime0 is False

time_to_str(t: float) str
Parameters:

t (float) – time to be converted to string in trace and animation

Returns:

t in required format – default: f”{t:10.3f}” if datetime0 is False

or date in the format “Day YYYY-MM-DD hh:mm:dd” otherwise

Return type:

str

Note

May be overrridden. Make sure that the method always returns the same length!

timedelta_to_duration(timedelta: timedelta) float
Parameters:

timedelta (datetime.timedelta) –

Returns:

timedelta translated to simulation duration in the current time_unit

Return type:

float

Raises:

ValueError – if datetime0 is False

title(value=None)

title of the canvas window

Parameters:

value (str) –

new title

if “”, the title will be suppressed

if not specified, no change

Returns:

title of canvas window

Return type:

str

Note

No effect for Pythonista

to_days(t: float) float

convert time t to days

Parameters:

t (float or distribution) –

time to be converted

if distribution, the distribution is sampled

Returns:

Time t converted to days

Return type:

float

to_hours(t: float) float

convert time t to hours

Parameters:

t (float or distribution) –

time to be converted

if distribution, the distribution is sampled

Returns:

Time t converted to hours

Return type:

float

to_microseconds(t: float) float

convert time t to microseconds

Parameters:

t (float or distribution) –

time to be converted

if distribution, the distribution is sampled

Returns:

Time t converted to microseconds

Return type:

float

to_milliseconds(t: float) float

convert time t to milliseconds

Parameters:

t (float or distribution) –

time to be converted

if distribution, the distribution is sampled

Returns:

Time t converted to milliseconds

Return type:

float

to_minutes(t: float) float

convert time t to minutes

Parameters:

t (float or distribution) –

time to be converted

if distribution, the distribution is sampled

Returns:

Time t converted to minutes

Return type:

float

to_seconds(t: float) float

convert time t to seconds

Parameters:

t (float or distribution) –

time to be converted

if distribution, the distribution is sampled

Returns:

Time t converted to seconds

Return type:

float

to_time_unit(time_unit: str, t: float) float

convert time t to the time_unit specified

Parameters:
  • time_unit (str) –

    Supported time_units:

    ”years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

  • t (float or distribution) –

    time to be converted

    if distribution, the distribution is sampled

Returns:

Time t converted to the time_unit specified

Return type:

float

to_weeks(t: float) float

convert time t to weeks

Parameters:

t (float or distribution) –

time to be converted

if distribution, the distribution is sampled

Returns:

Time t converted to weeks

Return type:

float

to_years(t: float) float

convert time t to years

Parameters:

t (float or distribution) –

time to be converted

if distribution, the distribution is sampled

Returns:

Time t converted to years

Return type:

float

trace(value: bool | filehandle = None) bool

trace status

Parameters:

value (bool or file handle) –

new trace status

defines whether to trace or not

if this a file handle (open for write), the trace output will be sent to this file.

if omitted, no change

Returns:

trace status

Return type:

bool or file handle

Note

If you want to test the status, always include parentheses, like

if env.trace():

ui_granularity(value: int = None) int
Parameters:

value (int) –

new ui_granularity

defines how often the ui_handler is called when animation is off (initially 1)

if omitted, no change

Returns:

current ui_granularity

Return type:

int

Note

If you want to test the status, always include parentheses, like

if env.paused():

user_to_screen_coordinates_size(usersize: float) float

converts a user size to a value to be used with screen coordinates

Parameters:

usersize (float) – user size to be converted

Returns:

value corresponding with usersize in screen coordinates

Return type:

float

user_to_screen_coordinates_x(userx: float) float

converts a user x coordinate to a screen x coordinate

Parameters:

userx (float) – user x coordinate to be converted

Returns:

screen x coordinate

Return type:

float

user_to_screen_coordinates_y(usery: float) float

converts a user x coordinate to a screen x coordinate

Parameters:

usery (float) – user y coordinate to be converted

Returns:

screen y coordinate

Return type:

float

video(value: str | Iterable = None) Any

video name

Parameters:

value (str, list or tuple) –

new video name

for explanation see animation_parameters()

Note

If video is the null string or None, the video (if any) will be closed.

The call can be also used as a context manager, which automatically opens and closes a file. E.g.

with video("test.mp4"):
    env.run(100)
video_close() None

closes the current animation video recording, if any.

video_height(value: int | str = None)

height of the video animation in screen coordinates

Parameters:

value (int) –

new width

if not specified, no change

Returns:

height of video animation

Return type:

int

video_mode(value: str = None)
Parameters:

value (int) –

new video mode (“2d”, “3d” or “screen”)

if not specified, no change

Returns:

video_mode

Return type:

int

video_pingpong(value: bool = None) bool

video pingpong

Parameters:

value (bool) –

new video pingpong

if not specified, no change

Returns:

video pingpong

Return type:

bool

Note

Applies only to gif animation.

video_repeat(value: int = None) int

video repeat

Parameters:

value (int) –

new video repeat

if not specified, no change

Returns:

video repeat

Return type:

int

Note

Applies only to gif animation.

video_width(value: int | str = None)

width of the video animation in screen coordinates

Parameters:

value (int) –

new width

if not specified, no change

Returns:

width of video animation

Return type:

int

visible(value: bool = None) bool

controls visibility of the animation window

Parameters:

value (bool) –

if True, the animation window will be visible

if False, the animation window will be hidden (‘withdrawn’) if None (default), no change

Returns:

current visibility

Return type:

bool

weeks(t: float) float

convert the given time in weeks to the current time unit

Parameters:

t (float or distribution) –

time in weeks

if distribution, the distribution is sampled

Returns:

time in weeks, converted to the current time_unit

Return type:

float

width(value: int = None, adjust_x0_x1_y0: bool = False) int

width of the animation in screen coordinates

Parameters:
  • value (int) –

    new width

    if not specified, no change

  • adjust_x0_x1_y0 (bool) –

    if False (default), x0, x1 and y0 are not touched

    if True, x0 and y0 will be set to 0 and x1 will be set to the given width

Returns:

width of animation

Return type:

int

width3d(value: int = None) int

width of the 3d animation in screen coordinates

Parameters:

value (int) –

new 3d width

if not specified, no change

Returns:

width of 3d animation

Return type:

int

x0(value: float = None) float

x coordinate of lower left corner of animation

Parameters:

value (float) – new x coordinate

Returns:

x coordinate of lower left corner of animation

Return type:

float

x1(value: float = None) float

x coordinate of upper right corner of animation : float

Parameters:

value (float) –

new x coordinate

if not specified, no change

Returns:

x coordinate of upper right corner of animation

Return type:

float

y0(value: float = None) float

y coordinate of lower left corner of animation

Parameters:

value (float) –

new y coordinate

if not specified, no change

Returns:

y coordinate of lower left corner of animation

Return type:

float

y1() float

y coordinate of upper right corner of animation

Returns:

y coordinate of upper right corner of animation

Return type:

float

Note

It is not possible to set this value explicitely.

years(t: float) float

convert the given time in years to the current time unit

Parameters:

t (float or distribution) –

time in years

if distribution, the distribution is sampled

Returns:

time in years, converted to the current time_unit

Return type:

float

yieldless() bool

yieldless status

Returns:

yieldless status

Return type:

bool

Note

It is not possible to change the yieldless status

Monitor

class salabim.Monitor(name: str = None, monitor: bool = True, level: bool = False, initial_tally: Any = None, type: str = None, weight_legend: str = None, fill: Iterable = None, stats_only: bool = False, env: Environment = None, *args, **kwargs)

Monitor object

Parameters:
  • name (str) –

    name of the monitor

    if the name ends with a period (.), auto serializing will be applied

    if the name end with a comma, auto serializing starting at 1 will be applied

    if omitted, the name will be derived from the class it is defined in (lowercased)

  • monitor (bool) –

    if True (default), monitoring will be on.

    if False, monitoring is disabled

    it is possible to control monitoring later, with the monitor method

  • level (bool) –

    if False (default), individual values are tallied, optionally with weight

    if True, the tallied vslues are interpreted as levels

  • initial_tally (any, preferably int, float or translatable into int or float) –

    initial value for the a level monitor

    it is important to set the value correctly. default: 0

    not available for non level monitors

  • type (str) –

    specifies how tallied values are to be stored
    • ”any” (default) stores values in a list. This allows

      non numeric values. In calculations the values are forced to a numeric value (0 if not possible)

    • ”bool” (True, False) Actually integer >= 0 <= 255 1 byte

    • ”int8” integer >= -128 <= 127 1 byte

    • ”uint8” integer >= 0 <= 255 1 byte

    • ”int16” integer >= -32768 <= 32767 2 bytes

    • ”uint16” integer >= 0 <= 65535 2 bytes

    • ”int32” integer >= -2147483648<= 2147483647 4 bytes

    • ”uint32” integer >= 0 <= 4294967295 4 bytes

    • ”int64” integer >= -9223372036854775808 <= 9223372036854775807 8 bytes

    • ”uint64” integer >= 0 <= 18446744073709551615 8 bytes

    • ”float” float 8 bytes

  • weight_legend (str) – used in print_statistics and print_histogram to indicate the dimension of weight or duration (for level monitors, e.g. minutes. Default: weight for non level monitors, duration for level monitors.

  • stats_only (bool) –

    if True, only statistics will be collected (using less memory, but also less functionality)

    if False (default), full functionality

filllist or tuple

can be used to fill the tallied values (all at time now).

fill is only available for non level and not stats_only monitors.

envEnvironment

environment where the monitor is defined

if omitted, default_env will be used

animate(*args, **kwargs)

animates the monitor in a panel

Parameters:
  • linecolor (colorspec) – color of the line or points (default foreground color)

  • linewidth (int) – width of the line or points (default 1 for level, 3 for non level monitors)

  • fillcolor (colorspec) – color of the panel (default transparent)

  • bordercolor (colorspec) – color of the border (default foreground color)

  • borderlinewidth (int) – width of the line around the panel (default 1)

  • nowcolor (colorspec) – color of the line indicating now (default red)

  • titlecolor (colorspec) – color of the title (default foreground color)

  • titlefont (font) – font of the title (default null string)

  • titlefontsize (int) – size of the font of the title (default 15)

  • title (str) –

    title to be shown above panel

    default: name of the monitor

  • x (int) – x-coordinate of panel, relative to xy_anchor, default 0

  • y (int) – y-coordinate of panel, relative to xy_anchor. default 0

  • offsetx (float) – offsets the x-coordinate of the panel (default 0)

  • offsety (float) – offsets the y-coordinate of the panel (default 0)

  • angle (float) – rotation angle in degrees, default 0

  • xy_anchor (str) –

    specifies where x and y are relative to

    possible values are (default: sw):

    nw    n    ne

    w     c     e

    sw    s    se

  • vertical_offset (float) –

    the vertical position of x within the panel is

    vertical_offset + x * vertical_scale (default 0)

  • vertical_scale (float) – the vertical position of x within the panel is vertical_offset + x * vertical_scale (default 5)

  • horizontal_scale (float) – the relative horizontal position of time t within the panel is on t * horizontal_scale, possibly shifted (default 1)

widthint

width of the panel (default 200)

heightint

height of the panel (default 75)

vertical_mapfunction

when a y-value has to be plotted it will be translated by this function

default: float

when the function results in a TypeError or ValueError, the value 0 is assumed

when y-values are non numeric, it is advised to provide an approriate map function, like:

vertical_map = “unknown red green blue yellow”.split().index

labelsiterable

labels to be shown on the vertical axis (default: empty tuple)

the placement of the labels is controlled by the vertical_map method

label_colorcolorspec

color of labels (default: foreground color)

label_fontfont

font of the labels (default null string)

label_fontsizeint

size of the font of the labels (default 15)

label_anchorstr

specifies where the label coordinates (as returned by map_value) are relative to

possible values are (default: e):

nw    n    ne

w     c     e

sw    s    se

label_offsetxfloat

offsets the x-coordinate of the label (default 0)

label_offsetyfloat

offsets the y-coordinate of the label (default 0)

label_linewidthint

width of the label line (default 1)

label_linecolorcolorspec

color of the label lines (default foreground color)

layerint

layer (default 0)

as_pointsbool

allows to override the as_points setting of tallies, which is by default False for level monitors and True for non level monitors

parentComponent

component where this animation object belongs to (default None)

if given, the animation object will be removed automatically when the parent component is no longer accessible

screen_coordinatesbool

use screen_coordinates

normally, the scale parameters are use for positioning and scaling objects.

if True, screen_coordinates will be used instead.

over3dbool

if True, this object will be rendered to the OpenGL window

if False (default), the normal 2D plane will be used.

Returns:

reference to AnimateMonitor object

Return type:

AnimateMonitor

Note

All measures are in screen coordinates

Note

It is recommended to use sim.AnimateMonitor instead

All measures are in screen coordinates

as_dataframe(include_t: bool = True, use_datetime0=False) None

makes a pandas dataframe with the x-values and optionally the t-values of the monitors

The x column names will be the name of the monitor, suffixed with “.x”.

Parameters:
  • include_t (bool) –

    if True (default), include the t values in the dataframe

    if False, do not include t values in the dataframe

  • use_datetime0 (bool) –

    if False (default), use t-values as such

    if True, use datetime.datetime as t-values (only allowed datetime0 is set for the environment)

Returns:

dataframe containing x (and t) values

Return type:

pandas dataframe

Notes

Requires pandas to be installed

For level monitors, Monitor.as_resampled_dataframe is likely more useful

as_resampled_dataframe(extra_monitors: Iterable = [], delta_t: float | timedelta = 1, min_t: float | datetime = None, max_t: float | datetime = None, use_datetime0=False) None

makes a pandas dataframe with t, and x_values for the monitor(s)

the t values will be uniformly distributes between min_t and max_t with a time step of delta_t

this is essentially the result of a resampling process. It is guaranteed that the values at the given times are correct.

The x column names will be the name of the monitor, suffixed with “.x”.

Parameters:

extra_monitors (iterable of level monitors) – monitors to be included in the dataframe

delta_tfloat or datetime.timedelta

time step (default: 1)

specification as datetime.timedelta only allowed if use_datetime0=True

min_tfloat or datetime.datetime

start of the resampled time (default: start time of the monitor)

specification as datetime.datetime only allowed if use_datetime0=True

max_tfloat or datetime.datetime

end of the resampled time (default: env.now())

specification as datetime.datetime only allowed if use_datetime0=True

use_datetime0bool

if False (default), use t-values as such

if True, use datetime.datetime as t-values (only allowed datetime0 is set for the environment)

Returns:

dataframe containing t and x values

Return type:

pandas dataframe

Notes

Requires pandas to be installed

base_name() str
Returns:

base name of the monitor (the name used at initialization)

Return type:

str

bin_duration(lowerbound: float, upperbound: float) float

total duration of tallied values in range (lowerbound,upperbound]

Parameters:
  • lowerbound (float) – non inclusive lowerbound

  • upperbound (float) – inclusive upperbound

Returns:

total duration of values >lowerbound and <=upperbound

Return type:

float

Note

Not available for level monitors

bin_number_of_entries(lowerbound: float, upperbound: float, ex0: bool = False) int

count of the number of tallied values in range (lowerbound,upperbound]

Parameters:
  • lowerbound (float) – non inclusive lowerbound

  • upperbound (float) – inclusive upperbound

  • ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

Returns:

number of values >lowerbound and <=upperbound

Return type:

int

Note

Not available for level monitors

bin_weight(lowerbound: float, upperbound: float) float

total weight of tallied values in range (lowerbound,upperbound]

Parameters:
  • lowerbound (float) – non inclusive lowerbound

  • upperbound (float) – inclusive upperbound

Returns:

total weight of values >lowerbound and <=upperbound

Return type:

float

Note

Not available for level monitors

deregister(registry: List) Monitor

deregisters the monitor in the registry

Parameters:

registry (list) – list of registered objects

Returns:

monitor (self)

Return type:

Monitor

duration(ex0: bool = False) float

total duration

Parameters:

ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

Returns:

total duration

Return type:

float

Note

Not available for non level monitors

duration_zero() float

total duratiom of zero entries

Returns:

total duration of zero entries

Return type:

float

Note

Not available for non level monitors

freeze(name: str = None) Monitor

freezes this monitor (particularly useful for pickling)

Parameters:

name (str) –

name of the frozen monitor

default: name of this monitor + “.frozen”

Returns:

frozen monitor

Return type:

Monitor

Notes

The env attribute will become a partial copy of the original environment, with the name of the original environment, padded with ‘.copy.<serial number>’

get(t: float = None) Any

get the value of a level monitor

Parameters:

t (float) –

time at which the value of the level is to be returned

default: now

Returns:

last tallied value – Instead of this method, the level monitor can also be called directly, like

Return type:

any, usually float

level = sim.Monitor(“level”, level=True)

print(level())

print(level.get()) # identical

Note

If the value is not available, self.off will be returned.

Only available for level monitors

histogram_autoscale(ex0: bool = False) Tuple[float, float, int]

used by histogram_print to autoscale

may be overridden.

Parameters:

ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

Returns:

bin_width, lowerbound, number_of_bins

Return type:

tuple

maximum(ex0: bool = False) float

maximum of tallied values

Parameters:

ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

Returns:

maximum

Return type:

float

mean(ex0: bool = False) float

mean of tallied values

Parameters:

ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

Returns:

mean

Return type:

float

Note

If weights are applied , the weighted mean is returned

median(ex0: bool = False, interpolation: str = 'linear') float

median of tallied values

Parameters:
  • ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

  • interpolation – Default: ‘linear’

Returns:

median (50% percentile)

Return type:

float

merge(*monitors, **kwargs) Monitor

merges this monitor with other monitor(s)

Parameters:
  • monitors (sequence) – zero of more monitors to be merged to this monitor

  • name (str) –

    name of the merged monitor

    default: name of this monitor + “.merged”

Returns:

merged monitor

Return type:

Monitor

Note

Level monitors can only be merged with level monitors

Non level monitors can only be merged with non level monitors

Only monitors with the same type can be merged

If no monitors are specified, a copy is created.

For level monitors, merging means summing the available x-values

minimum(ex0: bool = False) float

minimum of tallied values

Parameters:

ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

Returns:

minimum

Return type:

float

monitor(value: bool = None) bool

enables/disables monitor

Parameters:

value (bool) –

if True, monitoring will be on.

if False, monitoring is disabled

if omitted, no change

Returns:

True, if monitoring enabled. False, if not

Return type:

bool

multiply(scale: float = 1, name: str = None) Monitor

makes a monitor with all x-values multiplied with scale

Parameters:
  • scale (float) – scale to be applied

  • name (str) –

    name of the multiplied monitor

    default: name of this monitor

Returns:

multiplied monitor

Return type:

Monitor

Note

Only non level monitors with type float can be multiplied

name(value: str = None) str
Parameters:

value (str) – new name of the monitor if omitted, no change

Returns:

Name of the monitor

Return type:

str

Note

base_name and sequence_number are not affected if the name is changed

number_of_entries(ex0: bool = False) int

count of the number of entries

Parameters:

ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

Returns:

number of entries

Return type:

int

Note

Not available for level monitors

number_of_entries_zero() int

count of the number of zero entries

Returns:

number of zero entries

Return type:

int

Note

Not available for level monitors

percentile(q: float, ex0: bool = False, interpolation: str = 'linear') float

q-th percentile of tallied values

Parameters:
  • q (float) –

    percentage of the distribution

    values <0 are treated a 0

    values >100 are treated as 100

  • ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

  • interpolation – Default: ‘linear’

Returns:

q-th percentile – 0 returns the minimum, 50 the median and 100 the maximum

Return type:

float

print_histogram(number_of_bins: int = None, lowerbound: float = None, bin_width: float = None, values: bool | Iterable = False, ex0: bool = False, as_str: bool = False, file: TextIO = None, graph_scale: float = None, sort_on_weight: bool = False, sort_on_duration: bool = False, sort_on_value: bool = False) str

print monitor statistics and histogram

Parameters:
  • number_of_bins (int) –

    number of bins

    default: 30

    if <0, also the header of the histogram will be surpressed

  • lowerbound (float) –

    first bin

    default: 0

  • bin_width (float) –

    width of the bins

    default: 1

  • values (bool) –

    if False (default), bins will be used

    if True, the individual values will be shown (in alphabetical order). in that case, no cumulative values will be given

    if an iterable, the items will be used

  • ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

  • as_str (bool) – if False (default), print the histogram if True, return a string containing the histogram

  • file (file) –

    if None(default), all output is directed to stdout

    otherwise, the output is directed to the file

  • graph_scale (float) – Scale in the graphical representation of the % and cum% (default=80)

  • sort_on_weight (bool) –

    if True, sort the values on weight first (largest first), then on the values itself

    if False, sort the values on the values itself

    False is the default for non level monitors. Not permitted for level monitors.

  • sort_on_duration (bool) –

    if True, sort the values on duration first (largest first), then on the values itself

    if False, sort the values on the values itself

    False is the default for level monitors. Not permitted for non level monitors.

  • sort_on_value (bool) –

    if True, sort on the values.

    if False (default), no sorting will take place, unless values is an iterable, in which case sorting will be done on the values anyway.

Returns:

histogram (if as_str is True)

Return type:

str

Note

If number_of_bins, lowerbound and bin_width are omitted, the histogram will be autoscaled, with a maximum of 30 classes.

print_histograms(number_of_bins: int = None, lowerbound: float = None, bin_width: float = None, values: bool = False, ex0: bool = False, as_str: bool = False, file: TextIO = None, graph_scale: float = None) str

print monitor statistics and histogram

Parameters:
  • number_of_bins (int) –

    number of bins

    default: 30

    if <0, also the header of the histogram will be surpressed

  • lowerbound (float) –

    first bin

    default: 0

  • bin_width (float) –

    width of the bins

    default: 1

  • values (bool) –

    if False (default), bins will be used

    if True, the individual values will be shown (sorted on the value). in that case, no cumulative values will be given

ex0bool

if False (default), include zeroes. if True, exclude zeroes

as_str: bool

if False (default), print the histogram if True, return a string containing the histogram

file: file

if None(default), all output is directed to stdout

otherwise, the output is directed to the file

graph_scalefloat

Scale in the graphical representation of the % and cum% (default=80)

Returns:

histogram (if as_str is True)

Return type:

str

Note

If number_of_bins, lowerbound and bin_width are omitted, the histogram will be autoscaled, with a maximum of 30 classes.

Exactly same functionality as Monitor.print_histogram()

print_statistics(show_header: bool = True, show_legend: bool = True, do_indent: bool = False, as_str: bool = False, file: TextIO = None) str

print monitor statistics

Parameters:
  • show_header (bool) – primarily for internal use

  • show_legend (bool) – primarily for internal use

  • do_indent (bool) – primarily for internal use

  • as_str (bool) – if False (default), print the statistics if True, return a string containing the statistics

  • file (file) –

    if None (default), all output is directed to stdout

    otherwise, the output is directed to the file

Returns:

statistics (if as_str is True)

Return type:

str

register(registry: List) Monitor

registers the monitor in the registry

Parameters:

registry (list) – list of (to be) registered objects

Returns:

monitor (self)

Return type:

Monitor

Note

Use Monitor.deregister if monitor does not longer need to be registered.

rename(value: str = None) Monitor
Parameters:

value (str) – new name of the monitor if omitted, no change

Returns:

self

Return type:

monitor

Note

in contrast to name(), this method returns itself, so can used to chain, e.g.

(m0 + m1 + m2+ m3).rename(‘m0-m3’).print_histograms()

m0[1000 : 2000].rename(‘m between t=1000 and t=2000’).print_histograms()

reset(monitor: bool = None, stats_only: bool = None) None

resets monitor

Parameters:
  • monitor (bool) –

    if True, monitoring will be on.

    if False, monitoring is disabled if omitted, no change of monitoring state

  • stats_only (bool) –

    if True, only statistics will be collected (using less memory, but also less functionality)

    if False, full functionality

    if omittted, no change of stats_only

reset_monitors(monitor: bool = None, stats_only: bool = None) None

resets monitor

Parameters:
  • monitor (bool) –

    if True (default), monitoring will be on.

    if False, monitoring is disabled

    if omitted, the monitor state remains unchanged

  • stats_only (bool) –

    if True, only statistics will be collected (using less memory, but also less functionality)

    if False, full functionality

    if omittted, no change of stats_only

Note

Exactly same functionality as Monitor.reset()

sequence_number() int
Returns:

sequence_number of the monitor – (the sequence number at initialization)

normally this will be the integer value of a serialized name.

Non serialized names (without a dot or a comma at the end) will return 1)

Return type:

int

setup() None

called immediately after initialization of a monitor.

by default this is a dummy method, but it can be overridden.

only keyword arguments are passed

slice(start: float = None, stop: float = None, modulo: float = None, name: str = None) Monitor

slices this monitor (creates a subset)

Parameters:
  • start (float) –

    if modulo is not given, the start of the slice

    if modulo is given, this is indicates the slice period start (modulo modulo)

  • stop (float) –

    if modulo is not given, the end of the slice

    if modulo is given, this is indicates the slice period end (modulo modulo)

    note that stop is excluded from the slice (open at right hand side)

  • modulo (float) –

    specifies the distance between slice periods

    if not specified, just one slice subset is used.

  • name (str) –

    name of the sliced monitor

    default: name of this monitor + “.sliced”

Returns:

sliced monitor

Return type:

Monitor

Note

It is also possible to use square bracktets to slice, like m[0:1000].

start_time() float
Returns:

Start time of the monitor – either the time of creation or latest reset

Return type:

float

std(ex0: bool = False) float

standard deviation of tallied values

Parameters:

ex0 (bool) – if False (default), include zeroes. if True, exclude zeroes

Returns:

standard deviation

Return type:

float

Note

If weights are applied, the weighted standard deviation is returned

t() float

get the time of last tally of a level monitor

Getter:

gets the time of the last tallied value : float

Note

t is only available for level monitors

t is available even if the monitor is turned off

tally(value: Any, weight: float = 1) None
Parameters:
  • value (any, preferably int, float or translatable into int or float) – value to be tallied

  • weight (float) –

    weight to be tallied

    default : 1

to_days(name: str = None) Monitor

makes a monitor with all x-values converted to days

Parameters:

name (str) –

name of the converted monitor

default: name of this monitor

Returns:

converted monitor

Return type:

Monitor

Note

Only non level monitors with type float can be converted.

It is required that a time_unit is defined for the environment.

to_hours(name: str = None) Monitor

makes a monitor with all x-values converted to hours

Parameters:

name (str) –

name of the converted monitor

default: name of this monitor

Returns:

converted monitor

Return type:

Monitor

Note

Only non level monitors with type float can be converted.

It is required that a time_unit is defined for the environment.

to_microseconds(name: str = None) Monitor

makes a monitor with all x-values converted to microseconds

Parameters:

name (str) –

name of the converted monitor

default: name of this monitor

Returns:

converted monitor

Return type:

Monitor

Note

Only non level monitors with type float can be converted.

It is required that a time_unit is defined for the environment.

to_milliseconds(name: str = None) Monitor

makes a monitor with all x-values converted to milliseconds

Parameters:

name (str) –

name of the converted monitor

default: name of this monitor

Returns:

converted monitor

Return type:

Monitor

Note

Only non level monitors with type float can be converted.

It is required that a time_unit is defined for the environment.

to_minutes(name: str = None) Monitor

makes a monitor with all x-values converted to minutes

Parameters:

name (str) –

name of the converted monitor

default: name of this monitor

Returns:

converted monitor

Return type:

Monitor

Note

Only non level monitors with type float can be converted.

It is required that a time_unit is defined for the environment.

to_seconds(name: str = None) Monitor

makes a monitor with all x-values converted to seconds

Parameters:

name (str) –

name of the converted monitor

default: name of this monitor

Returns:

converted monitor

Return type:

Monitor

Note

Only non level monitors with type float can be converted.

It is required that a time_unit is defined for the environment.

to_time_unit(time_unit: str, name: str = None) Monitor

makes a monitor with all x-values converted to the specified time unit

Parameters:
  • time_unit (str) –

    Supported time_units:

    ”years”, “weeks”, “days”, “hours”, “minutes”, “seconds”, “milliseconds”, “microseconds”

  • name (str) –

    name of the converted monitor

    default: name of this monitor

Returns:

converted monitor

Return type:

Monitor

Note

Only non level monitors with type float can be converted.

It is required that a time_unit is defined for the environment.

to_weeks(name: str = None) Monitor

makes a monitor with all x-values converted to weeks

Parameters:

name (str) –

name of the converted monitor

default: name of this monitor

Returns:

converted monitor

Return type:

Monitor

Note

Only non level monitors with type float can be converted.

It is required that a time_unit is defined for the environment.

to_years(name: str