:orphan:

# PyElastica Examples

This directory contains number of examples of elastica.
Each [example cases](#example-cases) are stored in separate subdirectories, containing case descriptions, run file, and all other data/script necessary to run.
More [advanced cases](#advanced-cases) are stored in separate repository with its description.

## Case Examples

Some examples provide additional files or links to published paper for a complete description.
Examples can serve as a starting template for customized usages.

* [AxialStretchingCase](./AxialStretchingCase)
    * __Purpose__: Physical convergence test of simple stretching rod.
    * __Features__: CosseratRod, OneEndFixedRod, EndpointForces
* [TimoshenkoBeamCase](./TimoshenkoBeamCase)
    * __Purpose__: Physical convergence test of simple Timoshenko beam.
    * __Features__: CosseratRod, OneEndFixedRod, EndpointForces,
* [FlexibleSwingingPendulumCase](./FlexibleSwingingPendulumCase)
    * __Purpose__: Physical convergence test of simple pendulum with flexible rod.
    * __Features__: CosseratRod, HingeBC, GravityForces
* [ContinuumSnakeCase](./ContinuumSnakeCase)
    * __Purpose__: Demonstrate simple case of modeling biological creature using PyElastica. The example uses friction to create slithering snake, and optimize the speed using [CMA](https://github.com/CMA-ES/pycma).
    * __Features__: CosseratRod, MuscleTorques, RodPlaneContactWithAnisotropicFriction, Gravity, CMA Optimization
* [ContinuumSnakeWithLiftingWaveCase](./ContinuumSnakeWithLiftingWaveCase)
    * __Purpose__: Demonstrate simple case of modeling biological creature using PyElastica. The example uses friction to create slithering snake with lift.
    * __Features__: CosseratRod, MuscleTorquesLifting(custom implemented), SnakeRodPlaneContact(custom implemented), Gravity
* [MuscularSnake](./MuscularSnake)
    * __Purpose__: Example of [Parallel connection module](../elastica/experimental/connection_contact_joint/parallel_connection.py) and customized [Force module](./MuscularSnake/muscle_forces.py) to implement muscular snake.
    * __Features__: MuscleForces(custom implemented)
* [ButterflyCase](./ButterflyCase)
    * __Purpose__: Demonstrate simple restoration with initial strain.
    * __Features__: CosseratRod
* [CantileverDistributedLoad](./CantileverDistributedLoad)
    * __Purpose__: Demonstrate the demformation of a straight cantilever under both conservative (like water pressure) and non-conservative (like gravity) distributed load, compared with numerical solutions from Tschisgale, Silvio (2019).[<strong>"Chapter 3: Numerical models of partitioned problems"</strong>](https://nbn-resolving.org/urn:nbn:de:bsz:14-qucosa2-387063) Technische Univerisitat Dresden Institution of Fluid Mechanics
    * __Features__: CosseratRod
* [CantileverTransversalLoadCase](./CantileverTransversalLoadCase)
    * __Purpose__: Demonstrate the demformation of a curved cantilever under transversal one-end load, and also do Physical convergence test, compared with numerical solutions from Tschisgale, Silvio (2019).
    * __Features__: CosseratRod
* [TumblingUnconstrainedRod](./TumblingUnconstrainedRod)
    * __Purpose__: Demostrate the dynamics of tumbling uncontrained rod, compared with analytical solution from [Hisao, Kou Hou (1998).](https://www.sciencedirect.com/science/article/pii/S0045782598001522), Computer methods in applied mechanics and engineering.
    * __Features__: CosseratRod
* [FrictionValidationCases](./FrictionValidationCases)
    * __Purpose__: Physical validation of rolling and translational friction.
    * __Features__: CosseratRod, UniformForces, RodPlaneContactWithAnisotropicFriction
* [JointCases](./JointCases)
    * __Purpose__: Demonstrate various joint usage with Cosserat Rod.
    * __Features__: FreeJoint, FixedJoint, HingeJoint, OneEndFixedRod, EndpointForcesSinusoidal
* [RigidBodyCases](./RigidBodyCases)
    * __Purpose__: Demonstrate usage of rigid body on simulation.
    * __Features__: Cylinder, Sphere
    * [RodRigidBodyContact](./RigidBodyCases/RodRigidBodyContact)
        * __Purpose__: Demonstrate contact between cylinder and rod, for different intial conditions.
        * __Features__: Cylinder, CosseratRods, RodCylinderContact
* [HelicalBucklingCase](./HelicalBucklingCase)
    * __Purpose__: Demonstrate helical buckling with extreme twisting boundary condition.
    * __Features__: HelicalBucklingBC
* [ContinuumFlagellaCase](./ContinuumFlagellaCase)
    * __Purpose__: Demonstrate flagella modeling using PyElastica.
    * __Features__: SlenderBodyTheory, MuscleTorques,
* [MuscularFlagella](./MuscularFlagella)
    * __Purpose__: Example of customizing [Joint module](./MuscularFlagella/connection_flagella.py) and [Force module](./MuscularFlagella/muscle_forces_flagella.py) to implement muscular flagella.
    * __Features__: MuscleForces(custom implemented)
* [RodContactCase](./RodContactCase)
    * [RodRodContact](./RodContactCase/RodRodContact)
        * __Purpose__: Demonstrates contact between two rods, for different initial conditions.
        * __Features__: CosseratRod, RodRodContact
    * [RodSelfContact](./RodContactCase/RodSelfContact)
        * [PlectonemesCase](./RodContactCase/RodSelfContact/PlectonemesCase)
            * __Purpose__: Demonstrates rod self contact with Plectoneme example, and how to use link-writhe-twist after simulation completed.
            * __Features__: CosseratRod, SelonoidsBC, RodSelfContact, Link-Writhe-Twist
        * [SolenoidsCase](./RodContactCase/RodSelfContact/SolenoidsCase)
            * __Purpose__: Demonstrates rod self contact with Solenoid example, and how to use link-writhe-twist after simulation completed.
            * __Features__: CosseratRod, SelonoidsBC, RodSelfContact, Link-Writhe-Twist
* [BoundaryConditionsCases](./BoundaryConditionsCases)
    * __Purpose__: Demonstrate the usage of boundary conditions for constraining the movement of the system.
    * __Features__: GeneralConstraint, CosseratRod
* [DynamicCantileverCase](./DynamicCantileverCase)
    * __Purpose__: Validation of dynamic cantilever vibration for multiple modes.
    * __Features__: CosseratRod, OneEndFixedRod
* [RingRodCase](./RingRodCase)
    * __Purpose__: Demonstrate simulation of ring rod.
    * __Features__: RingCosseratRod, OneEndFixedRod, GravityForce
* [CatenaryCase](./CatenaryCase)
    * __Purpose__: Demonstrate simulation of cosserat rod under gravity with fixed ends, compared with Catenary Analytical Solution from Routh, Edward John (1891). [<strong>"Chapter X: On Strings"</strong>](https://books.google.com/books?id=3N5JAAAAMAAJ&pg=PA315#v=onepage&q&f=false). A Treatise on Analytical Statics. University Press.
    * __Features__: CosseratRod, FixedConstraint, GravityForce
* [KnotCase](./KnotCase)
    * __Purpose__: Demonstrate simulation of rod forming a knot using a tip-pose control.
    * __Features__: CosseratRod, KnotTheory, FixedConstraint, RodSelfContact, Custom p-controller for SO3.

## Functional Examples

* [RestartExample](./RestartExample)
    * __Purpose__: Demonstrate the usage of restart module.
    * __Features__: save_state, load_state

## Advanced Cases

* [Elastica RL control](https://github.com/GazzolaLab/Elastica-RL-control) - Case presented in [<strong>Elastica: A compliant mechanics environment for soft robotic control</strong>](https://doi.org/10.1109/LRA.2021.3063698)
* [Gym Softrobot](https://github.com/skim0119/gym-softrobot) - Soft-robot control environment developed in OpenAI-gym format to study slender body control with reinforcement learning.

## Experimental Cases

* [ParallelConnectionExample](./ExperimentalCases/ParallelConnectionExample)
    * __Purpose__: Demonstrate the usage of parallel connection.
    * __Features__: connect two parallel rods



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>




.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Timoshenko beam validation case, for detailed explanation refer to Gazzola et. al. R. Soc. 2018  section 3.4.3">

.. only:: html

  .. image:: /_gallery/TimoshenkoBeamCase/images/thumb/sphx_glr_run_timoshenko_thumb.png
    :alt:

  :ref:`sphx_glr__gallery_TimoshenkoBeamCase_run_timoshenko.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Timoshenko Beam</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>




.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="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.">

.. only:: html

  .. image:: /_gallery/AxialStretchingCase/images/thumb/sphx_glr_run_axial_stretching_thumb.png
    :alt:

  :ref:`sphx_glr__gallery_AxialStretchingCase_run_axial_stretching.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Axial Stretching</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>




.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This script simulates the formation of an overhand knot in a soft rod. It demonstrates how to create a controller to manipulate a node on the rod, which can be used for tasks like trajectory tracing or proportional control.">

.. only:: html

  .. image:: /_gallery/KnotCase/images/thumb/sphx_glr_run_knot_simulation_thumb.png
    :alt:

  :ref:`sphx_glr__gallery_KnotCase_run_knot_simulation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Knot Simulation</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>




.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This case simulates a rod hanging under its own weight, forming a catenary curve. The rod is fixed at both ends and is allowed to settle into its equilibrium position.">

.. only:: html

  .. image:: /_gallery/CatenaryCase/images/thumb/sphx_glr_run_catenary_thumb.png
    :alt:

  :ref:`sphx_glr__gallery_CatenaryCase_run_catenary.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Catenary</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>




.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This case simulates the motion of a rod that is initially shaped like a 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.">

.. only:: html

  .. image:: /_gallery/ButterflyCase/images/thumb/sphx_glr_run_butterfly_thumb.png
    :alt:

  :ref:`sphx_glr__gallery_ButterflyCase_run_butterfly.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Butterfly</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>




.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Snake friction case from X. Zhang et. al. Nat. Comm. 2021">

.. only:: html

  .. image:: /_gallery/ContinuumSnakeCase/images/thumb/sphx_glr_run-continuum-snake_thumb.png
    :alt:

  :ref:`sphx_glr__gallery_ContinuumSnakeCase_run-continuum-snake.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Continuum Snake</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /_gallery/TimoshenkoBeamCase/index.rst
   /_gallery/AxialStretchingCase/index.rst
   /_gallery/KnotCase/index.rst
   /_gallery/CatenaryCase/index.rst
   /_gallery/ButterflyCase/index.rst
   /_gallery/ContinuumSnakeCase/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples as source code: _gallery.zip </_gallery/_gallery.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: _gallery_jupyter.zip </_gallery/_gallery_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_