Merge branch 'fig-animation' into 'master'

Fig animation

See merge request !7

_toc.yml

@@ -24,3 +24,4 @@ parts:
      - file: content/additional/links.md
      - file: content/additional/contact.md
      - file: content/additional/credits.md
+     - file: content/additional/fig_animation.md
\ No newline at end of file

content/additional/fig_animation.md

+# Creating Animated Figures with Matplotlib
+
+In this chapter, we will explore creating animated figures using Matplotlib animations.
+
+## Requirements
+
+Before getting started with creating animated figures using Matplotlib, make sure you have the following requirements in place:
+- Python installed on your system
+- Matplotlib library installed
+- IPython library installed
+
+## Sources
+
+To learn more about creating animated figures using Matplotlib, you can refer to the following resources:
+
+- [Matplotlib Animation API](https://matplotlib.org/stable/api/animation_api.html): This documentation provides insights into how the animation method works internally and offers multiple coding examples.
+- [Matplotlib FuncAnimation](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.FuncAnimation.html): Here, you can find detailed information about the parameters of the FuncAnimation function and the methods it provides.
+
+In the next sections, we will guide you through the main steps, provide a brief explanation, and present a code example.
+
+## The method
+
+The `FuncAnimation` module creates an animation by repeatedly calling a function (`func` argument). Each call generates one frame of the animation. The `frames` argument specifies the source of data to pass to the `func` for each frame.
+
+The main arguments needed for the animation are as follows:
+
+- `fig`: A figure object that serves as the canvas for the animation.
+- `func`: The function to call at each frame. This function should update the information of the figure object to capture the frame in the animation.
+- `frames=None`: The domain of values for which a frame will be created. The `func` function is called with each value from the `frames` argument.
+
+It's important to note that the `funcAnimation` first calls the `func` function and then draws the content of the `fig` object at each frame. Therefore, the `func` function should update the figure object to reflect the desired changes for each frame.
+
+> **Note:** For more information and examples, refer to the [Matplotlib Animation API documentation](https://matplotlib.org/stable/api/animation_api.html).
+
+## Coding example
+
+The following code example demonstrates how to create an animated figure using Matplotlib:
+
+
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+from IPython.display import HTML
+
+plt.rcParams["animation.html"] = "jshtml"   # Set the animation format to "jshtml"
+x = np.linspace(0, 2 * np.pi, 100)  
+
+fig, ax = plt.subplots()   # Create a figure and axes object
+line, = ax.plot(x, np.sin(x))  
+
+def update(frame):
+    line.set_ydata(np.sin(x + frame))   # Update the y-data of the line with the new frame value
+
+ani = animation.FuncAnimation(fig, update, frames=x)  # Create the animation object
+
+plt.close(fig)  # Prevent the initial figure from being displayed inline
+
+HTML(ani.to_jshtml())  # Display the animation as HTML
+```
+Or another example, which can be found in the [Open Quantum Sensing and Measurement Notes](https://interactivetextbooks.tudelft.nl/qsm/src/5_wigner_2.html#change-phase-of-alpha) is: 
+```python
+from qutip import *
+
+N = 30
+fig, ax = plt.subplots(1, 1, figsize=(4, 4))
+
+def update(phi):
+    ax.cla()
+    psi = coherent(N,3*np.exp(1j*phi)) +  coherent(N,-3*np.exp(1j*phi))
+    plot_wigner(psi,fig=fig,ax=ax)
+
+phi_values = np.linspace(0, 2*np.pi, 100)
+anim = animation.FuncAnimation(fig, update, frames=phi_values)
+plt.close(fig)  # Close the figure to prevent it from displaying inline
+
+HTML(anim.to_jshtml())
+```
+
+
+## General process
+The general process to create an animated figure using Matplotlib is as follows:
+
+1. Ensure that the necessary packages are installed.
+2. Define the figure object, e.g. using `plt.subplots()`.
+3. Specify the frames argument, which determines the domain of values for creating each frame.
+4. Define the func function that will be called for each frame. This function should update the figure object accordingly. The first argument will be the frame value and [additional arguments](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.FuncAnimation.html#:~:text=The%20function%20to%20call%20at%20each%20frame.%20The%20first%20argument%20will%20be%20the%20next%20value%20in%20frames.%20Any%20additional%20positional%20arguments%20can%20be%20supplied%20using%20functools.partial%20or%20via%20the%20fargs%20parameter.) can be added if needed. 
+5. Create the `FuncAnimation` object by providing the above-mentioned arguments and any other relevant arguments.
+6. Set the `animation.html` ([link](https://matplotlib.org/stable/users/explain/customizing.html#:~:text=%2D%20%27jshtml%27%20creates%20a%20JavaScript%20animation)) parameter to "jshtml" to plot the animation as HTML.
+7. Generate the HTML representation of the animation using the `.to_jshtml()` function and convert the result to HTML using the `IPython.display.HTML` method.
+
+For more details and examples, refer to the [Matplotlib Animation API documentation](https://matplotlib.org/stable/api/animation_api.html).
+
+### Remark 
+
+When compiling your book locally, the default cell execution time-out is set to 30 seconds. However, given that certain animations may require additional processing time, it is recommended to extend the execution time, such as to 300 milliseconds. This adjustment can be made by configuring the timeout for all notebook executions in your `_config.yml` file (see [here](https://jupyterbook.org/en/stable/content/execute.html#setting-execution-timeout)) using the following approach:
+```
+execute:
+  timeout: 300
+```
\ No newline at end of file