docs: clean up tutorial for gallery

Author: skim0119

Makefile

@@ -112,8 +112,12 @@ pytestcache-remove:
 build-remove:
 	rm -rf build/ dist/
 
+.PHONY: doc-remove
+doc-remove:
+	rm -rf docs/_build docs/gen_modules/ docs/sg_execution_times.rst docs/_gallery/
+
 .PHONY: cleanup
-cleanup: pycache-remove dsstore-remove ipynbcheckpoints-remove pytestcache-remove mypycache-remove build-remove
+cleanup: pycache-remove dsstore-remove ipynbcheckpoints-remove pytestcache-remove mypycache-remove build-remove doc-remove
 
 all: format-codestyle cleanup test
 

examples/AxialStretchingCase/run_axial_stretching.py

@@ -2,9 +2,11 @@
 Axial Stretching
 ================
 
-This case tests the axial stretching of a rod. A rod is fixed at one end and
-a force is applied at the other end. The rod stretches and the displacement
-of the tip is compared with the analytical solution.
+This case tests the axial stretching of a rod.
+The expected behavior is supposed to be like a spring-gravity motion, but
+with a rod. A rod is fixed at one end and a force is applied at the other
+end. The rod stretches and the displacement of the tip is compared with
+the analytical solution.
 """
 
 # isort:skip_file
@@ -15,8 +17,10 @@
 import elastica as ea
 
 # %%
-# First, we define a simulator class that inherits from the necessary mixins.
-# This makes it easy to add constraints, forces, and damping to the system.
+# Simulation Setup
+# ----------------
+# We define a simulator class that inherits from the necessary mixins.
+# This makes constraints, forces, and damping evailable to the system.
 
 
 class StretchingBeamSimulator(
@@ -29,9 +33,13 @@ class StretchingBeamSimulator(
 final_time = 200.0
 
 # %%
-# Next, we set up the test parameters for the simulation. This includes the
+# Rod Setup
+# ---------
+# Next, we set up the test parameters for the simulating rods. This includes the
 # number of elements, the start position, direction, normal, length, radius,
 # density, and Young's modulus of the rod.
+# For this case, we have fixed boundary condition at one end, and we apply external
+# force at the other end.
 
 # setting up test params
 n_elem = 19
@@ -47,10 +55,6 @@ class StretchingBeamSimulator(
 poisson_ratio = 0.5
 shear_modulus = youngs_modulus / (poisson_ratio + 1.0)
 
-# %%
-# Now we can create the `CosseratRod` object. We use the `straight_rod` method
-# to create a straight rod with the specified parameters.
-
 stretchable_rod = ea.CosseratRod.straight_rod(
     n_elem,
     start,
@@ -65,18 +69,10 @@ class StretchingBeamSimulator(
 
 stretch_sim.append(stretchable_rod)
 
-# %%
-# We then apply a boundary condition to fix one end of the rod. We use the
-# `OneEndFixedBC` constraint to fix the position and director of the first node.
-
 stretch_sim.constrain(stretchable_rod).using(
     ea.OneEndFixedBC, constrained_position_idx=(0,), constrained_director_idx=(0,)
 )
 
-# %%
-# A force is applied to the other end of the rod. We use the `EndpointForces`
-# forcing to apply a force in the x-direction.
-
 end_force_x = 1.0
 end_force = np.array([end_force_x, 0.0, 0.0])
 stretch_sim.add_forcing_to(stretchable_rod).using(
@@ -99,7 +95,9 @@ class StretchingBeamSimulator(
 
 
 # %%
-# We define a callback class to record the position and velocity of the rod
+# Callbacks
+# ---------
+# A callback object is passed to the simulator to record states of the rod
 # during the simulation. This is useful for post-processing the results.
 
 
@@ -137,16 +135,15 @@ def make_callback(
 )
 
 # %%
+# Finalize and Run
+# ----------------
 # We finalize the simulator and create the time-stepper. The `PositionVerlet`
 # time-stepper is used to integrate the system.
 
 stretch_sim.finalize()
 timestepper: ea.typing.StepperProtocol = ea.PositionVerlet()
 # timestepper = PEFRL()
 
-# %%
-# The simulation is run for the specified `final_time`.
-
 total_steps = int(final_time / dt)
 print("Total steps", total_steps)
 dt = final_time / total_steps
@@ -155,6 +152,8 @@ def make_callback(
     time = timestepper.step(stretch_sim, time, dt)
 
 # %%
+# Post-Processing
+# ---------------
 # Finally, we plot the results and compare them with the analytical solution.
 # The analytical solution is calculated using the first-order theory with
 # both the base length and the modified length.

examples/ButterflyCase/run_butterfly.py

@@ -3,8 +3,13 @@
 =========
 
 This case simulates the motion of a rod that is initially shaped like a
-butterfly. The rod is released from rest and allowed to fall under gravity.
+butterfly. The rod is released from rest and allowed to deform freely.
+The goal of the simulation is for sanity check: how does the timestepper
+reliably preserve total energy of the system, when the system is simple Hamiltonian.
 The simulation tracks the position and energy of the rod over time.
+
+This example case also demonstrate how to setup rod with customized
+positions and directors.
 """
 
 import numpy as np
@@ -16,7 +21,9 @@
 from elastica.utils import MaxDimension
 
 # %%
-# First, we define a simulator class that inherits from the necessary mixins.
+# Simulation Setup
+# ----------------
+# We define a simulator class that inherits from the necessary mixins.
 
 
 class ButterflySimulator(ea.BaseSystemCollection, ea.CallBacks):
@@ -27,9 +34,9 @@ class ButterflySimulator(ea.BaseSystemCollection, ea.CallBacks):
 final_time = 40.0
 
 # %%
-# Next, we set up the test parameters for the simulation. This includes the
-# number of elements, the origin, the angle of inclination, the length,
-# radius, density, and Young's modulus of the rod.
+# Rod Setup
+# ---------
+# Next, we set up the test parameters for the simulation.
 
 # setting up test params
 # FIXME : Doesn't work with elements > 10 (the inverse rotate kernel fails)
@@ -95,7 +102,9 @@ class ButterflySimulator(ea.BaseSystemCollection, ea.CallBacks):
 
 
 # %%
-# We define a callback class to record the position and energy of the rod
+# Callback Setup
+# --------------
+# A callback object is defined to record the position and energy of the rod
 # during the simulation.
 
 
@@ -127,7 +136,9 @@ def make_callback(
             return
 
 
+# database
 recorded_history: dict[str, list] = ea.defaultdict(list)
+
 # initially record history
 recorded_history["time"].append(0.0)
 recorded_history["position"].append(butterfly_rod.position_collection.copy())
@@ -141,16 +152,15 @@ def make_callback(
 )
 
 # %%
+# Finalize and Run
+# ----------------
 # We finalize the simulator and create the time-stepper.
 
 butterfly_sim.finalize()
 timestepper: ea.typing.StepperProtocol
 timestepper = ea.PositionVerlet()
 # timestepper = PEFRL()
 
-# %%
-# The simulation is run for the specified `final_time`.
-
 dt = 0.01 * dl
 total_steps = int(final_time / dt)
 print("Total steps", total_steps)
@@ -160,8 +170,10 @@ def make_callback(
     time = timestepper.step(butterfly_sim, time, dt)
 
 # %%
-# Finally, we plot the results. The position of the rod is plotted at
-# different time steps, and the energies are plotted as a function of time.
+# Post-Processing
+# ---------------
+# The position of the rod is plotted at different time steps,
+# and the energies are plotted as a function of time.
 
 # Plot the histories
 fig = plt.figure(figsize=(5, 4), frameon=True, dpi=150)
@@ -180,6 +192,8 @@ def make_callback(
 # don't block
 fig.show()
 
+# %%
+
 # Plot the energies
 energy_fig = plt.figure(figsize=(5, 4), frameon=True, dpi=150)
 energy_ax = energy_fig.add_subplot(111)

examples/CatenaryCase/run_catenary.py

@@ -18,7 +18,9 @@
 )
 
 # %%
-# First, we define a simulator class that inherits from the necessary mixins.
+# Simulation Setup
+# ----------------
+# We define a simulator class that inherits from the necessary mixins.
 
 
 class CatenarySimulator(
@@ -28,24 +30,19 @@ class CatenarySimulator(
 
 
 catenary_sim = CatenarySimulator()
+final_time = 30
 
 # %%
-# Next, we set up the simulation parameters. This includes the final time,
-# damping constant, time step, and rendering frame rate.
+# Rod Setup
+# ---------
+# We set up the rod parameters. This rod is affected by a gravity force.
 
-final_time = 10
-damping_constant = 0.3
+n_elem = 500
 time_step = 1e-4
 total_steps = int(final_time / time_step)
 rendering_fps = 20
 step_skip = int(1.0 / (rendering_fps * time_step))
 
-# %%
-# We then define the properties of the rod, such as the number of elements,
-# start position, direction, normal, length, radius, and material properties.
-
-n_elem = 500
-
 start = np.zeros((3,))
 direction = np.array([1.0, 0.0, 0.0])
 normal = np.array([0.0, 0.0, 1.0])
@@ -62,9 +59,6 @@ class CatenarySimulator(
 poisson_ratio = 0.5
 shear_modulus = E / (poisson_ratio + 1.0)
 
-# %%
-# Now we can create the `CosseratRod` object and add it to the simulator.
-
 base_rod = ea.CosseratRod.straight_rod(
     n_elem,
     start,
@@ -79,25 +73,25 @@ class CatenarySimulator(
 
 catenary_sim.append(base_rod)
 
+# Add gravity
+catenary_sim.add_forcing_to(base_rod).using(
+    ea.GravityForces, acc_gravity=-9.80665 * normal
+)
+
 # %%
 # Damping is added to the system to help it reach a steady state.
 
 # add damping
+damping_constant = 0.3
 catenary_sim.dampen(base_rod).using(
     ea.AnalyticalLinearDamper,
     damping_constant=damping_constant,
     time_step=time_step,
 )
 
 # %%
-# We add gravity to the system to simulate the weight of the rod.
-
-# Add gravity
-catenary_sim.add_forcing_to(base_rod).using(
-    ea.GravityForces, acc_gravity=-9.80665 * normal
-)
-
-# %%
+# Boundary Conditions
+# -------------------
 # We fix both ends of the rod using the `FixedConstraint`.
 
 # fix catenary ends
@@ -107,10 +101,10 @@ class CatenarySimulator(
     constrained_director_idx=(0, -1),
 )
 
-
 # %%
-# We define a callback class to record the position, radius, and internal
-# forces of the rod during the simulation.
+# Callback
+# --------
+# We define a callback class to record the rod state during the simulation.
 
 
 # Add call backs
@@ -145,14 +139,13 @@ def make_callback(
 )
 
 # %%
-# We finalize the simulator and create the time-stepper.
+# Finalize and Run
+# ----------------
+# We finalize the simulator, create the time-stepper, and run.
 
 catenary_sim.finalize()
 timestepper: ea.typing.StepperProtocol = ea.PositionVerlet()
 
-# %%
-# The simulation is run for the specified number of steps.
-
 dt = final_time / total_steps
 time = 0.0
 for i in range(total_steps):
@@ -161,6 +154,8 @@ def make_callback(
 b = np.min(position[-1][2])
 
 # %%
+# Post-processing
+# ---------------
 # Finally, we can save a video of the simulation and plot the final
 # shape of the catenary.