Salabim

===========================

Added functionality (0)
-----------------------

Saving
an animated gif, png or webp file
a snapshot
under Python In Excel, now saves an encoded file to sim.pie_result().
The stored result contains the name of the file, so later decoding to a real file is possible.

Also, a file handler b64_file_handler is provided to allow writing to a file
in binary or text mode as an encoded file. This is used internally, but it can be used
by an application as well.

It is also possible to add text to the sim.pie_result() list without
affecting the stored file(s) information.

Note that for the decoding a VBA macro is required.

Changed functionality (0)
-------------------------

Under Python in Excel, blind_animation is enabled by default for a call to Environment().

Changed functionality (1)
-------------------------

If the trace had to show a line in the source of salabim (particularly in ComponentGenerator),
the line numbers were not always displayed correctly and were not very useful
for the trace anyway.
From now on, in that case, no line number will be shown.

Bug fix (0)
-----------

Label lines in AnimateMonitor / Monitor.animate() were obscured by the fillcolor.
From now on, the line around the frame will be shown over the label lines,
whereas the label lines will be shown over the filled rectangle.

Bug fix (1)
-----------

On Pythonista, the fallback font did not work properly as Pythonista does not support
file handles as the font parameter for PIL.ImageFont. Therefore, on this platform
salabim falls back on the standard Arial font.

Bug fix (2)
-----------

Pause/Resume an animation with <space> didn't work properly. Fixed.
(bug reported by Harald Mutzke)

Type annotation fix (0)
-----------------------

Fixed a wrong type annotation in AnimateSlider.
(flagged by Harald Mutzke)

PyPI/GitHub distribution change (0)
------------------=-----------------

On PyPI salabim now has a meaningful description.
GitHub also has an updated readme.

==========================

New functionality (0)
---------------------

A new context manager sim.capture_stdout(), makes it possible to capture all stdout output.
Unless include_print=False is given, the output *also* goes to the console (as usual).

For example, with
with sim.capture_stdout():
env = sim.Environment(trace=True)
all trace output will be printed AND be captured.

With
with sim.capture_stdout(include_print=False):
env = sim.Environment(trace=True)
, trace output will not be printed, but still be captured.

The captured output can be retrieved with
sim.captured_stdout_as_list() to retrieve it as a list of strings
sim.captured_stdout_as_str() to retrieve it as a string
sim.captured_stdout_as_file() to retrieve it in a file (given as a str, Path or file handle)

The first function is particularly useful for Python in Excel.

It is possible to clear the captured_stdout information with
sim.clear_captured_stdout()

Of course, we can also use env.capture_stdout(), env.captured_stdout_to_list(), etc. instead.

New functionality (1)
---------------------

Salabim can now run under Python in Excel.

This required a change in the line number assessment.
When the line cannot be determined, a question mark will now be used instead.

Note that only blind animation is supported as tkinter is not available under
Python in Excel.
Although technically salabim supports making an animated Gif under Python in Excel (with
some specialized VBA code), this is not very practical (as of now).

Changed functionality (0)
-------------------------

The salabim code now contains encoded versions of the fonts
"calibri" / "std" / ""
"dejavusansmono" / "mono"
"mplus_1m_regular" / "narrow"
This means that it is not longer required to have the files
calibri.ttf
DejaVuSansMono.ttf
mplus-1m-regular.ttf
installed or available anywhere anymore.
Also, when a font is not found, salabim will fall back to the calibri font.

This makes distributing models without installing salabim simpler.

And it also makes font handling available to models run under PythonInExcel.

Changed functionality (1)
-------------------------

AnimateQueue() / Queue.animate() now has a screen_coordinates parameter that is True by default.
If the animation objects of the components to be shown are in user coordinates, specify screen_coordinates=False.
Actually, this change was already introduced in salabim 23.3.5, but was left out of the changelog of that version.

Bug fix (0)
-----------

The patch in salabim 23.3.5 to support Pillow 10.0.0, did not work under all circumstances.
Fixed.

Bug fix (1)
-----------

Blind animation still required tkinter under some circumstances. Fixed.

Bug fix (2)
-----------

Blind animation video making did not finish when env.run() was specified. Fixed.

Bug fix (3)
-----------

AnimateMonitor() / Monitor.animate() label lines did not observe the xy_offset parameter. Fixed.
AnimateMonotor() / Monitor.animate() label lines could 'override' the surrounding rectangle. Fixed.

Bug fix (4)
-----------

AnimateText did not observe the offsetx and offsety parameter correctly. Fixed.

==========================

Enhanced UI functionality (0)
-----------------------------

The UI window layout has been changed to be more useful with
narrower windows.
Some more updates to the appearance.

When the UI is started, the time in the animation window is no longer disabled.
The user can always switch that off with Environment.show_time(False).

Environment.start_ui() now has useful defaults for window_size and window_position.

Environment.start_ui() now has a parameter default_actions, which is True by default.
If False, there are no actions like, pause/go, speed, etc. defined, so the user has to
specify the required actions with the actions parameter.
This is useful to use a different layout or leave out certain elements. Be sure to
use the same keys to be able to use the programmed interactions. However, you
can leave out elements.

It is recommended to use the standard actions as a template:

[sg.Text("", key="-TIME-", metadata=[1, 2], size=200)],
[sg.Button("Pause", key="-PAUSE-GO-", metadata=[1, 2]), sg.Button("Stop", key="-STOP-", button_color=("white", "firebrick3"), metadata=[1, 2])],
[sg.Checkbox("Pause at each step", False, key="-PAUSE-AT-EACH-STEP-", enable_events=True, metadata=[1, 2])],
[sg.Text(f"Pause at{env.get_time_unit(template='(t)')}", key="-PAUSE-AT-TEXT-", size=17), sg.Input("", key="-PAUSE-AT-", size=(10, 20))],
[sg.Text(f"Pause each{env.get_time_unit(template='(d)')}", key="-PAUSE-EACH-TEXT-", size=17), sg.Input("", key="-PAUSE-EACH-", size=(10, 20))],
[
sg.Text("Speed", key="-SPEED-TEXT-", metadata=[1]),
sg.Button("/2", key="-SPEED/2-", metadata=[1]),
sg.Button("*2", key="-SPEED*2-", metadata=[1]),
sg.Input("", key="-SPEED-", size=(7, 10)),
],
[sg.Checkbox("Trace", env.trace(), key="-TRACE-", metadata=[1, 2], enable_events=True)],
[sg.Checkbox("Synced", env.synced(), key="-SYNCED-", metadata=[1], enable_events=True)],
[sg.Checkbox("Animate", True, key="-ANIMATE-", metadata=[1, 2], enable_events=True)],


The simulation did not stop exactly at the time given in 'Pause at'. Fixed.

Added demos (0)
---------------

The program demo_ui.py shows a pretty standard UI with some extra elements.

The program demo_horizontal_ui.py demonstrates the same functionality, but now
with a horizontal UI window. Note that this requires quite a bit more
code than the standard one.
But it demonstrates what is possible.

Bug fix (0)
-----------

Component.to_store_store did not always return the right store. Fixed.
Thanks to Florian Förster for reporting this bug and the fix.

Bug fix (1)
-----------

Store.to_store_requesters() returned the wrong queue. Fixed.

==========================

Bug fix (0)
-----------

Environment.paused(True) did not call set_start_animation(), which is required. Fixed.

Bug fix (1)
-----------

Removing and showing an animated monitor did not restore the labels and label lines. Fixed.

==========================

New functionality (0)
---------------------

The parameter datetime0 in Environment(), may now be also a string, which is relatively
free format as it uses dateutil.parser.parse.
Note that (unless Environment.dateutil_parse is overridden), it is advised to use
Y-M-D format, e.g.
env = sim.Environment(datetime0="2023-08-17")
Note that for this functionality, dateutil has to be installed, most likely with
pip install python-dateutil

New functionality (1)
---------------------

The parameter datetime0 in Environment.datetime0(), may now be also a string, which is relatively
free format as it uses dateutil.parser.parse.
Note that (unless Environment.dateutil_parse is overridden), it is advised to use
Y-M-D format, e.g.
env.datetime0("2023-08-17")
Note that for this functionality, dateutil has to be installed, most likely with
pip install python-dateutil


New functionality (2)
---------------------

The above functionality uses a method Environment.dateutil_parse, which more or less defaults to
def dateutil_parse(self, spec):
import dateutil.parser
return dateutil.parser.parse(spec, dayfirst=False, yearfirst=True)

If other values for dayfirst or yearfirst are desired, formulate a custom method, like
sim.Environment.dateutil_parse = lambda self, spec: dateutil.parser.parse(spec, dayfirst=True, yearfirst=False)

Refer to the Python dateutil.parse documentation for details.

Note that for this functionality, dateutil has to be installed, most likely with
pip install python-dateutil

Changed functionality (3)
-------------------------

If datetime0 is not False, all process interaction methods that require a time, like Component.hold,
Component creation, fail_at parameters, can now be a datetime.datetime, e.g.
comp.hold(till=datetime.datetime(year=2023, month=8, day=17))
Or it can be string containing a relatively free format date, like
comp.hold(till="2023-08_07")
And now it is even possible to use a string:
comp.hold(till="1000")

If datetime0 is not False, all process interaction methods that require a duration, like Component.hold,
Component creation, fail_delay parameters, can now be a datetime.timedelta, e.g.
comp.hold(datetime.timedelta(hours=1)
Vehicle(delay=datetime.timedelta(days=2))
Or it can be string containing a relatively free format duration, like
comp.hold("12:00:00"))
And now it is even possible to use a string:
comp.hold("1000")

Of course, these parameters can also be a callable, like
comp.hold(env.Pdf(("12:00", "13:45", "20:30"), 1))

Note that this functionality is a by-product of the implementation of the not yet documented, but already
available, UI (using PySimpleGUI) functionality.

New functionality (4)
---------------------

The value of State.value can now be assigned and queried directly. E.g.
my_state.value.value = 3
print(my_state.value.value)
is equivalent to
my_state.set(3)
print(my_state.get())
This can be useful to increment or decrement a state. E.g.
my_state.value.value += 5
is equivalent to
my.state.set(my_state.get() + 5)

The value of Component.mode can now be assigned also like:
my_component.mode.value = "working"
, instead of
my_component.set_mode("working")
This can also be useful to increment or decrement a mode. E.g.
my_component.mode.value += 5
is equivalent to
my_component.set_mode(my_component.mode() + 5)

Changed functionality (0)
-------------------------

The class Environmnent does not contain a subclass Environment anymore,
so you can't say
env1 = env.Environment()
anymore. This was never intended to be supported.
Use
env1 = sim.Environment()
now.

Compatibility fix (0)
---------------------

When saving a video as .gif, Pythonista required the images2gif module, which has a bug in
the latest version of Pythonista.
As Pythonista has now an updated version of Pillow, saving can and will be done in the same way as
in non Pythonista versions.

==========================

Compatibility update (0)
------------------------

Due to a change in Pillow 10.0.0, salabim did not work properly with that version:

- font.getsize was deprecated. Salabim now uses font.getbbox.
- Image.ANTIALIAS was deprecated. Salabim now uses Image.LANCZOS
From now on, Pillow >=10.0.0 is also supported.