Salabim

==========================
New functionality
-----------------
Support for animated GIF production. If Environment.animation.parameters(video=...) of Environment.video()
gets a filename with .gif as extension, an animated GIF is created.
Note that GIF production does not require numpy nor opencv, and therefore Environment.can_video() does not
have to be True to produce an animated GIF.
This feature is particularly useful on Pythonista platforms, where opencv is not supported.

For animated GIFs, Environment.animation_parameters() has two extra parameters:
video_repeat ==> how many times the animated GIF will be repeated (default 1)
video_pingpong ==> whether all frames should be appended in reverse order at the end of the animated GIF
resulting in a smooth repeating video (default: False)

Two methods have been added to Environment to support GIF file production:
Environment.video_repeat()
Environment,video_pingpong()


For ordinary video files (non GIF), it is now possible to specify a codec, by adding a plus sign and
the name of the codec after the extension of the file, like
video='myvideo.avi+DIVX'


Introduced Resource.occupancy timestamped monitor. The occupancy is defined as the claimed quantity
divided by the capacity. Note that when the capacity of r changes over time, r.occupancy.mean() may differ
from r.claimed_quantity.mean() / r.capacity.mean(). Also, in that case, the occupancy may be even greater than 1.
If the capacity is <=0, the occupancy is assumed to be 0.


Improvements
------------
The time in the upper right-hand corner is now displayed with the mono font, which is better legible and
not as 'nervous' as the narrow font that was used previously. Also, on Pythonista, the text is moved a bit
to the left in order not to coincide with the closing symbol X.


Clarification
-------------
When a process ends, all claimed resources will be automatically released.
If that functionality is not desired, the process should be prematurely cancelled, with
yield self.cancel()

Compare these two components:
class X(sim.Component):
def process(self):
yield self.request(r)
yield self.hold(1)
automatically releases r at the end of the process

class Y(sim.Component):
def process(self):
yield self.request(r)
yield self.hold(1)
yield self.cancel() process ends here and r is NOT released!

Also, all animation objects that have set the parent field to a component will be removed automatically
when the process of that component ends. Again, this can be prevented by yield self.cancel().

This information will be included in the documentation.


Bug fixes
---------
Bugs in AnimateSlider fixed (thanks to John Hutchinson).

Bug when honoring a resource request of a component that was already claiming that resource fixed.

Bug in the line number of the trace when auto releasing claimed resources at end of a process fixed.

Bug in wait with a fail_at parameter fixed.

==========================
New functionality
-----------------
Function reset() resets all global variables and closes a video recording, if any
It can be useful to start a script with sim.reset() when used in REPLs and under Pythonista (iPad).

Release notes 2.2.17 corrections
--------------------------------
Method Environment.scale() introduced, returning the scale of the animation, i.e. width / (x1 - x0)
(not (x1 - x0) / width).

Function arrow_polygon added (not polygon_arrow).
Function centered_rectangle() added (not rectangle_centered).

Bug fixes
---------
Bug in AnimateSlider corrected.

==========================
New functionality
-----------------
Normal distribution now supports specification of coefficient_of_variation as an alternative
to standard_deviation.
Note that it is not allowed to specify both standard_deviation and cooeficient_of_variation.
The coefficient_of_variation is now also shown in Normal.print_info().
The coefficient_of_variation is defined as the standard deviation divided by the mean.

Method Environment.scale() introduced, returning the scale of the animation, i.e. (x1 - x0) / width

sim.Animate and sim.update now allows and prefers circle0 or circle1 to be specified as a scalar.
The functionality to the specify the radius as a one element tuple/list is still supported.
E.g. sim.Animate(circle0=(30,)) is equivalent to sim.Animate(circle0=30) now.
Note that Animate.circle may also return a one item tuple/list or a scalar.

sim.Animate() and sim.update() now allows the specification of
line0, line1, rectangle0, rectangle1, poloygon0 and polygon1 to include None values
The None values will repeat the previous x or y value. E.g.
sim.Animate(line0=(10, 20, None, 30, 40, None)) is equivalent to sim.Animate(line0=(10, 20, 10, 30, 40, 30))

Function polygon_arrow() added.
Function rectangle_centered() added.

Video production now supports .MP4 and .AVI extensions. Other extensions are not accepted.

Environment.is_dark(colorspec) now returns the is_dark value of the background color
if the alpha value of the colorspec is 0.

Changed API
-----------
The parameter lambda_ for the Poisson distribution is renamed to mean, in order to avoid problems
with the online documentation.

Bug fixes
---------
Bug in handling width/height of images when using a redefined coordinate system fixed.
Bug in method Queue.add_at_head() fixed.
Bug with default font handling on Pythonista fixed.
Bug in Environment.animation_parameters() and Environment.video() fixed.
Work around a PIL bug where rendering the first letter of some italic font texts chopped the lefthand serif.

Sample files
------------
Show colornames.py shows all available colors.
Demo using process interaction in method.py gives an example of how to use hold in a separate method.
Dining philsophers animated.py updated to use the new circle specification.

Documentation
-------------
Documentation updated and improved. Although still work in progress ...

===========================
From this version, neither animation modules (PIL, tkinter) nor video modules (cv2, numpy) will
be imported unless these are required at runtime (with animation_parameters).

A user program can now check whether animation is supported with a call to sim.can_animate().
A user program can now check whether video is supported with a call to sim.can_video().

Bug fix
-------
Minor bug when ImageTk could not be imported corrected.

==========================
Animation updates
-----------------
Overhaul of the way animation is organized. Now, the animation can be started and stopped during a run.
When animation is off, the simulation model runs full speed without any overhead.
It is possible to use different environmnent for the animation although not at the same time.

The API for animation has changed slightly:
center is now refered to as 'c' (although 'center' is still accepted)
xy_anchor allows x0, x1, y0 and y1 in Animate and x and y in AnimateButton or AnimateSlider object, to be
relative to each of the wind directions 'n', 'nw', 'w', 'sw', 's', 'se', 'e' or 'ne' or 'c' (for center).
This makes it, for instance, possible to define a button relative to the top right hand corner of the
animation frame:
b = sim.AnimateButton(text='My button', x=-100, y=-20, xy_anchor='ne')

All arguments of Environment.animation_parameters have now a corresponding function that
can be used to set or query one of the animation parameters:
Environment.x0() to set/query x-coordinate of lower left corner of animation frame
Environment.x1() to set/query x-coordinate of upper right corner of animation frame
Environment.y0() to set/query y-coordinate of lower left corner of animation frame
Environment.y1() to query y-coordinate of upper right corner of animation frame
Environment.width() to set/query width of animation frame
Environment.height() to set/query height of animation frame
Environment.fps() to set/query the number of frames per second
Environment.show_time() to set/query whether time should be shown
Environment.show_fps() to set/query whether fps should be shown
Environment.modelname() to set/query the model name ('' to show nothing)
Environment.animate() to start/stop the animation and to query the current status
Environment.speed() to set/query the speed of the animation
Environment.video() to set/query the name of the video ('' for no video)

New functionality
-----------------
The Poisson distribution is now supported.

Enhancements
------------
Text alignment in text Animate is significantly improved. Now the text is always aligned according to the
(estimated) 'cap line', which is derived from a capital A.
So, when aligning south, the descender of the g is below the baseline.
When aligning north, top of the capline is the given y-position.
Finally, aligning w, c or e means given y-position is the middle of the cap line.

Functionality updates
---------------------
- linewidth0 defaults to 1 for lines, 0 for rectangles, polygons and circles.
- When a modelname is given, that is presented in a different way along with a salabim logo.

Updated animated sample files
-----------------------------
Please not that the animated sample models have been updated to use the new xy_anchor functionality.

Bug fix
-------
Collected tallies for monitors were not cached properly, resulting in non optimal performance of Monitor.x() and
querying the monitor, e.g. print_histogram.

==========================
New functionality
-----------------
Standby components just getting current and go into standby again can now be excluded from the trace.
This can be controlled with the method Environment.suppress_trace_standby().
By default, standby is excluded from the trace.


Added functionality to read item based input files (inspired by TomasRead).
Therefore, the class ItemFile is added to salabim.

Example usage:
with sim.ItemFile(filename) as f:
run_length = f.read_item_float()
run_name = f.read_item()

Or (not recommended):
f = sim.InputFile(filename)
run_length = f.read_item_float()
run_name = f.read_item()
f.close()

The input file is read per item, where blanks, linefeeds, tabs are treated as separators.
Any text on a line after a character is ignored.
Any text within curly brackets ( {} ) is ignored (and treated as an item separator).
Note that this strictly on a per line basis.
If a blank is to be included in a string, use single or double quotes.
The recommended way to end a list of values is //

So, a typical input file is:

Typical experiment file for a salabim model
1000 run length
'Experiment 2.0' run name

Model speed color
-------------- ----- ------

'Peugeot 208' 150 red
'Peugeot 3008' 175 orange
'Citroen C5' 160 blue
'Renault "Twingo"' 165 green
//

France {country} Europe {continent}

end of file

Instead of the filename as a parameter to ItemFile, also a string with the content can be given. In that
case, at least one linefeed has to be in the content string. Usually, the content string will be triple
quoted. This can be very useful during testing as the input is part of the source file and not external, e.g.

test_input = '''
one two
three four
five
'''
with sim.ItemFile(test_input) as f:
while True:
try:
print(f.read_item())
except EOFError:
break


​
​