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, 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

imagestr, pathlib.Path or PIL image

the image to be displayed

This may be either a filename or a PIL image

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 first -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

anchorstr

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_pointsbool

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

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

linewidth0float

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

fillcolor0colorspec

color of interior at time t0 (default foreground_color)

if as_points is True, fillcolor0 defaults to transparent

linecolor0colorspec

color of the contour at time t0 (default foreground_color)

textcolor0colorspec

color of the text at time 0 (default foreground_color)

angle0float

angle of the polygon at time t0 (in degrees) (default 0)

alpha0float

alpha of the image at time t0 (0-255) (default 255)

fontsize0float

fontsize of text at time t0 (default 20)

width0float

width of the image to be displayed at time t0

if omitted or None, no scaling

t1float

time of end of the animation (default inf)

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

x1float

x-coordinate of the origin at time t1(default x0)

y1float

y-coordinate of the origin at time t1 (default y0)

offsetx1float

offsets the x-coordinate of the object at time t1 (default offsetx0)

offsety1float

offsets the y-coordinate of the object at time t1 (default offsety0)

circle1float 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)

line1tuple

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

should have the same number of elements as line0

polygon1tuple

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

should have the same number of elements as polygon0

rectangle1tuple

the rectangle (xlowerleft,ylowerleft,xupperright,yupperright) at time t1 (default: rectangle0)

linewidth1float

linewidth of the contour at time t1 (default linewidth0)

fillcolor1colorspec

color of interior at time t1 (default fillcolor0)

linecolor1colorspec

color of the contour at time t1 (default linecolor0)

textcolor1colorspec

color of text at time t1 (default textcolor0)

angle1float

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

alpha1float

alpha of the image at time t1 (0-255) (default alpha0)

fontsize1float

fontsize of text at time t1 (default: fontsize0)

width1float

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

over3dbool

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)

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 Helvetica)

• 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)

linecolorcolorspec

color of the contour (default transparent)

anglefloat

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

default: 0

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)

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

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.

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.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

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

• 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.

• 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.

• 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)

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)

• 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: str = 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.

• 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 generator function process will be used as the default process.

  note that the function must be a generator, i.e. contains at least one yield.

• 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

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

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 yield 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) → 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

Note

Only allowed for current component

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 yield 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 yield 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, 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.

• 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

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

Cannot be applied on the current component.

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

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 resources, 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

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.

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

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, but also non serialized names (without a dotcomma at the end) will be numbered)

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.

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

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 yield 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.

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

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)

10. ==> 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 = False, name: str = None, print_trace_header: bool = True, isdefault_env: bool = True, retina: bool = False, do_reset: bool = None, blind_animation: bool = False, *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=”*”.

class 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, 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

imagestr, pathlib.Path or PIL image

the image to be displayed

This may be either a filename or a PIL image

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 first -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

anchorstr

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_pointsbool

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

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

linewidth0float

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

fillcolor0colorspec

color of interior at time t0 (default foreground_color)

if as_points is True, fillcolor0 defaults to transparent

linecolor0colorspec

color of the contour at time t0 (default foreground_color)

textcolor0colorspec

color of the text at time 0 (default foreground_color)

angle0float

angle of the polygon at time t0 (in degrees) (default 0)

alpha0float

alpha of the image at time t0 (0-255) (default 255)

fontsize0float

fontsize of text at time t0 (default 20)

width0float

width of the image to be displayed at time t0

if omitted or None, no scaling

t1float

time of end of the animation (default inf)

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

x1float

x-coordinate of the origin at time t1(default x0)

y1float

y-coordinate of the origin at time t1 (default y0)

offsetx1float

offsets the x-coordinate of the object at time t1 (default offsetx0)

offsety1float

offsets the y-coordinate of the object at time t1 (default offsety0)

circle1float 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)

line1tuple

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

should have the same number of elements as line0

polygon1tuple

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

should have the same number of elements as polygon0

rectangle1tuple

the rectangle (xlowerleft,ylowerleft,xupperright,yupperright) at time t1 (default: rectangle0)

linewidth1float

linewidth of the contour at time t1 (default linewidth0)

fillcolor1colorspec

color of interior at time t1 (default fillcolor0)

linecolor1colorspec

color of the contour at time t1 (default linecolor0)

textcolor1colorspec

color of text at time t1 (default textcolor0)

angle1float

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

alpha1float

alpha of the image at time t1 (0-255) (default alpha0)

fontsize1float

fontsize of text at time t1 (default: fontsize0)

width1float

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

over3dbool

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)

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 Animate3dBar(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', edge_color: str | Iterable[float] | Callable = '', bar_width: float | Callable = 1, bar_width_2: float | Callable = None, shaded: bool | Callable = False, 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 bar 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 bar (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

• bar_width (float) – width of the bar (default 1)

• bar_width_2 (float) –

  if not specified both sides will have equal width (bar_width)

  if specified, the bar will have width bar_width and bar_width_2

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

• show_lids (bool) –

  if True (default), show the ‘lids’

  if False, it’s a hollow bar

• 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

queue()

Returns:

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

Return type:

queue

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

show(unremove)

It is possible to use this method if already shown

class 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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 Animate3dSphere(radius: float | Callable = 1, x: float | Callable = 0, y: float | Callable = 0, z: float | Callable = 0, color: str | Iterable[float] | Callable = 'white', number_of_slices: int | Callable = 32, number_of_stacks: int | Callable = None, visible: bool | Callable = True, arg: Any = None, layer: float | Callable = 0, parent: Component = None, env: Environment = None, **kwargs)

Creates a 3D box

Parameters:

• radius (float) – radius of the sphere

• 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)

• color (colorspec) – color of the sphere (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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

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 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 Helvetica)

• 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 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)

linecolorcolorspec

color of the contour (default transparent)

anglefloat

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

default: 0

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)

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

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.

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

deregister_dynamic_attributes(attributes)

Deregisters one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

getattribute_spec(attr)

special version of getattribute. When it’s dynamic it will return the value in case of a constan or a parameterless function Used only in AnimateCombined

register_dynamic_attributes(attributes)

Registers one or more attributes as being dynamic

Parameters:

attributes (str) –

a specification of attributes to be registered as dynamic

e.g. “x y”

class 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 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