Added examples

.gitignore

@@ -0,0 +1 @@
+pypi/

README.md

@@ -1,6 +1,11 @@
 # ElegansBot
 Newtonian Mechanics Model for C. elegans Locomotion  
-Demo: https://taegonchung.github.io/elegansbot/
+
+## Web Demo
+- https://taegonchung.github.io/elegansbot/
+    - Use the sliders to observe the worm's movement changes.
+        - Water-Agar Slider: Adjust this to modify the ground's frictional coefficients.
+        - Swim-Crawl Slider: This slider alters the period and linear wave number of C. elegans' locomotion.
 
 ## Requirements
 - Python (version 3)
@@ -11,24 +16,23 @@ Demo: https://taegonchung.github.io/elegansbot/
 
 ## Tested Environment
 - Windows 10
-- python 3.8.18
-- numpy 1.19.0
-- numba 0.54.0
-    - scipy 1.5.0
-- matplotlib 3.4.2
+- Python 3.8.18
+- NumPy 1.19.0
+- Numba 0.54.0
+    - SciPy 1.5.0
+- Matplotlib 3.4.2
 
 ## Usage
-1. Download the `elegansbot.py` file into your project directory.
+1. Install library by `pip install elegansbot` or Download the `elegansbot.py` file into your project directory.
 2. Use `from elegansbot import Worm` to import the library.
 3. Refer to the detailed instructions in the docstring of the "Worm" class. Below is a brief overview of potential use-cases:
-    - If you wish to use ElegansBot with a pre-determined $\theta_{\mathrm{ctrl}}$ (target body angle or kymogram), it's recommended to utilize the "run" method of an instance of the "Worm" class.
     - If you want to determine $\theta_{\mathrm{ctrl}}$ dynamically, it's advised to update "act" (equivalent to theta_ctrl) manually and then invoke the "steps" method on an instance of the "Worm" class.
+    - If you wish to use ElegansBot with a pre-determined $\theta_{\mathrm{ctrl}}$ (target body angle or kymogram), it's recommended to utilize the "run" method of an instance of the "Worm" class.
 
-## Web Demo
-- https://taegonchung.github.io/elegansbot/
-    - Use the sliders to observe the worm's movement changes.
-        - Water-Agar Slider: Adjust this to modify the ground's frictional coefficients.
-        - Swim-Crawl Slider: This slider alters the period and linear wave number of C. elegans' locomotion.
+## Examples
+You may check out examples in the "examples/" directory.  
+Try running `python examples/example01.py` for dynamic input  
+or `python examples/example02.py` for kymogram input  
 
 ## Local Demo
 Execute the following command:

examples/example01.py

@@ -0,0 +1,22 @@
+from elegansbot import Worm
+import numpy as np
+
+print('Agar plate')
+env = Worm(dt=0.00005) # Numba JIT spends compile-time here, once.
+for _ in range(env.n_snapshot):
+    env.act = 0.7 * np.cos(2 * np.pi * (1.832 * np.linspace(0, 1, env.n - 1) - env.t / 1.6))
+    env.steps()
+env.plot_overview()
+env.plot_speed_graph()
+env.play_animation()
+# env.save_animation('demo_crawl.mp4')
+
+print('Water')
+env = Worm(dt=0.00005, bT=5.2e3, bII=5.2e3/1.5) # You can calculate faster with less accurate result by increasing dt.
+for _ in range(env.n_snapshot):
+    env.act = 0.5 * np.cos(2 * np.pi * (0.667 * np.linspace(0, 1, env.n - 1) - env.t / 0.4))
+    env.steps()
+env.plot_overview()
+env.plot_speed_graph()
+env.play_animation()
+# env.save_animation('demo_swim.mp4')

examples/example02.py

@@ -0,0 +1,43 @@
+from elegansbot import Worm, set_bbox_inches_tight
+import numpy as np
+import matplotlib.pyplot as plt
+
+# kymogram
+fps = 30
+kymogram = np.zeros((fps*5, 24))
+for i in range(kymogram.shape[0]):
+    t = (1/fps) * i
+    kymogram[i] = 0.5 * np.cos(2 * np.pi * (1.832 * np.linspace(0, 1, 24) - t / 1.6))
+
+# kymogram figure
+matrix = kymogram.transpose()
+shape = np.shape(matrix)
+
+fig, ax = plt.subplots(dpi=120)
+im = ax.imshow(matrix, aspect=.3*(shape[1]/shape[0]), cmap='bwr')
+ax.set_title('Kymogram')
+ax.set_xlabel('frame number')
+ax.set_ylabel('body position')
+ax.set_yticks([0, shape[0]-1])
+ax.set_yticklabels(['head', 'tail'])
+
+[l, b, w, h] = ax.get_position().bounds
+cbound = [l+w*1.05, b, w*0.05, h]
+cax = fig.add_axes(cbound)
+cbar = fig.colorbar(im, ax=ax, cax=cax)
+cax.set_title('dorsal', fontsize=8)
+cax.set_xlabel('ventral', fontsize=8)
+
+set_bbox_inches_tight(fig)
+plt.show()
+
+# ElegansBot Simulation
+env = Worm(scale_friction=0.01)
+env.run(kymogram, 1/fps)
+
+env.plot_overview()
+env.plot_speed_graph()
+# %matplotlib notebook # uncomment this line if the code runs in jupyter-notebook.
+env.play_animation(speed_playback=0.5)
+# %matplotlib inline # uncomment this if it's in jupyter-notebook.
+# env.save_animation('demo.mp4') # FFMPEG is required for saving animation.