Merge pull request #69 from GazzolaLab/update-0.2.2

Release 0.2.2

.coveragerc

@@ -15,6 +15,6 @@ omit =
     elastica/systems/analytical.py
     # omit deprecation warning message
     elastica/_elastica_numpy.py
-    # omit experimental
+    # omit experimental modules
     elastica/experimental/*
 	setup.py

CONTRIBUTING.md

@@ -98,7 +98,7 @@ Once you find the issue that you are interested in, please leave a comment that
 If you leave some questions in the comment, we will provide more detailed descriptions.
 
 You are also welcomed to help us pushing this project further. 
-Please don't hesitate improving documentation or code-coverage.
+Please don't hesitate improving [documentation](https://github.com/GazzolaLab/PyElastica/tree/master/docs) or code-coverage.
 
 ### Side projects
 
@@ -155,7 +155,11 @@ In order to format the code:
 
 ### Documentation styleguide
 
-We follow [NumPy documentation guidelines](https://numpydoc.readthedocs.io/en/latest/format.html) for PyElastica documentation.
+We follow [NumPy documentation guidelines][numpydoc-guideline] for PyElastica documentation.
+If you are interested in contributing or modifying the documentation, please refer to the [docs-readme][docs-readme] file.
 
 [beginner]: https://github.com/GazzolaLab/PyElastica/labels/good%20first%20issue
 [help-wanted]: https://github.com/GazzolaLab/PyElastica/labels/help%20wanted
+
+[numpydoc-guideline]: https://numpydoc.readthedocs.io/en/latest/format.html
+[docs-readme]: https://github.com/GazzolaLab/PyElastica/blob/master/docs/README.md

RELEASE.md

@@ -1,3 +1,18 @@
+# Release Note (version 0.2.2)
+
+## Developer Note
+
+The major documentation update is finished in this version.
+Constraint and finalize module are refactored to enhance readability.
+
+## Notable Changes
+- #64: Core wrapper redesign. The finalizing code is refactored for easier integration.
+- #65: Documentation update.
+- #56: Constraint module has been refactored to include proper abstract base class. Additionally, new `FixedConstraint` is added for generalized fixed boundary condition.
+- More test cases are added to increase code-coverage.
+
+---
+
 # Release Note (version 0.2.1)
 
 ## Developer Note

docs/README.md

@@ -0,0 +1,61 @@
+# Elastica Documentation
+
+We use [`Sphinx`](https://www.sphinx-doc.org/en/master/) and [`ReadtheDocs`](https://readthedocs.org/) to organize our [documentation page](https://docs.cosseratrods.org/en/latest/).
+
+In addition, we utilize the following extensions to enhance the documentation :coffee:
+- `numpydoc`: We favor [numpy documentation style](https://numpydoc.readthedocs.io/en/latest/format.html) for API documentation.
+- `myst_parser`: We like to write documentation and guidelines in `markdown` format.
+
+## Build documentation
+
+The `sphinx` is already initialized in `docs` directory. In order to build the documentation, you will need additional packages listed in `docs/requirements.txt`.
+
+```bash
+pip install sphinx sphinx_rtd_theme myst-parser numpydoc
+cd docs
+make clean
+make html
+```
+
+Once the documentation building is done, open `docs/_build/html/index.html` to view.
+
+Use `make help` for other options.
+
+# Contribution
+
+The documentation-related commits will be collected in the branch `doc_**` separate from `master` branch, and merged into `master` collectively. Ideally, the updates in the documentation branch will seek upcoming version update (i.e. `update-**` branch) and merged shortly after the version release. If an update is critical and urgent, create PR directly to `master` branch.
+
+## User Guide
+
+User guidelines and tutorials are written in `.rst` or `.md` format.
+These files will be managed in `docs` directory.
+
+> In the future, a separate `asset` branch will be created to keep images and other binary files.
+
+## API documentation
+
+The docstring for function or modules are automatically parsed using `sphinx`+`numpydoc`.
+Any inline function description, such as 
+
+```py
+""" This is the form of a docstring.
+
+... description
+
+Attributes
+----------
+x : type
+    x description
+y : type
+    y description
+
+"""
+```
+
+will be parsed and displayed in API documentation. See `numpydoc` for more details.
+
+## ReadtheDocs
+
+`ReadtheDocs` runs `sphinx` internally and maintain the documentation website. We will always activate the `stable` and `latest` version, and few past-documentations will also be available for the support.
+
+@nmnaughton and @skim449 has access to the `ReadtheDocs` account.

docs/_static/css/logo.css

@@ -0,0 +1,8 @@
+/* 
+ * To resize and re-factor the design parameters for logo
+ * https://stackoverflow.com/questions/59215996/how-to-add-a-logo-to-my-readthedocs-logo-rendering-at-0px-wide
+ * */
+.wy-side-nav-search .wy-dropdown > a img.logo, .wy-side-nav-search > a img.logo {
+        width: 175px;
+        height: 80px;
+    }

docs/advanced/LocalizedForceTorque.md

@@ -0,0 +1,58 @@
+# Localized Force and Torque
+
+> Originated by the investigation in the [issue #39](https://github.com/GazzolaLab/PyElastica/issues/39)
+
+## Discussion
+
+In elastica, __a force is applied on a node__ while __a torque is applied on an element__.
+For example, a localized force `EndpointForce` is applied only on a node. However, we found that adding additional torque on a neighboring elements, such that the torque represent a local moment induced by the point-force, could yield better convergence.
+We haven't found any evidence (yet) that this actually changes the steady-state configuration and kinematics, since it is two different implementation of the same point-load.
+We suspect the improvement by adding additional torque is due to explicitly giving the force-boundary condition that match the final internal-stress state.
+
+## Comparison
+
+Factoring the additional-torque on a neighboring element leads to slightly better error estimates for the Timoshenko beam example. The results are condensed here.
+With new implementation, we achieved the same error with less number of discretization, but it also requires additional torque computation.
+
+![image](https://github.com/GazzolaLab/PyElastica/blob/assets/docs/assets/plot/error_EndpointForcesWithTorques.png?raw=true)
+
+## Modified Implementation
+
+```py
+class EndpointForcesWithTorques(NoForces):
+    """
+    This class applies constant forces on the endpoint nodes.
+    """
+
+    def __init__(self, end_force, ramp_up_time=0.0):
+        """
+
+        Parameters
+        ----------
+        start_force: numpy.ndarray
+            2D (dim, 1) array containing data with 'float' type.
+            Force applied to first node of the rod-like object.
+        end_force: numpy.ndarray
+            2D (dim, 1) array containing data with 'float' type.
+            Force applied to last node of the rod-like object.
+        ramp_up_time: float
+            Applied forces are ramped up until ramp up time.
+
+        """
+        self.end_force = end_force
+        assert ramp_up_time >= 0.0
+        self.ramp_up_time = ramp_up_time
+
+    def apply_forces(self, system, time=0.0):
+        factor = min(1.0, time / self.ramp_up_time)
+        self.external_forces[..., -1] += self.end_force * factor
+
+    def apply_torques(self, system, time: np.float64 = 0.0):
+        factor = min(1.0, time / self.ramp_up_time)
+        arm_length = system.lengths[...,-1]
+        director = system.director_collection[..., -1]
+        self.external_torques[..., -1] += np.cross(
+            [0.0, 0.0, 0.5 * arm_length], director @ self.end_force
+        )
+
+```

docs/advanced/PackageDesign.md

@@ -0,0 +1,8 @@
+# Code Design: Mixin and Composition
+
+Elastica package follows Mixin and composition design patterns that may be unfamiliar to users. Here is a collection of references that introduce the package design.
+
+## References
+
+- [stackoverflow discussion on Mixin](https://stackoverflow.com/questions/533631/what-is-a-mixin-and-why-are-they-useful)
+- [example of Mixin: python collections](https://docs.python.org/dev/library/collections.abc.html)

docs/api/callback.rst

@@ -0,0 +1,33 @@
+Callback Functions
+===================
+
+.. _constraints:
+
+.. automodule::  elastica.callback_functions
+
+Description
+-----------
+
+The frequency at which you have your callback function save data will depend on what information you need from the simulation. Excessive call backs can cause performance penalties, however, it is rarely necessary to make call backs at a frequency that this becomes a problem. We have found that making a call back roughly every 100 iterations has a negligible performance penalty. 
+
+Currently, all data saved from call back functions is saved in memory. If you have many rods or are running for a long time, you may want to consider editing the call back function to write the saved data to disk so you do not run out of memory during the simulation.
+
+.. autosummary::
+   :nosignatures:
+
+   CallBackBaseClass
+   ExportCallBack
+   MyCallBack
+
+Built-in Constraints
+--------------------
+
+.. autoclass:: CallBackBaseClass
+   :special-members: __init__
+
+.. autoclass:: ExportCallBack
+   :special-members: __init__
+
+.. autoclass:: MyCallBack
+   :special-members: __init__
+

docs/api/connections.rst

@@ -0,0 +1,51 @@
+Connections / Contact / Joints
+==============================
+
+.. _connections:
+
+.. automodule:: elastica.joint
+
+Description
+-----------
+
+.. rubric:: Available Connection/Contact/Joints
+
+.. autosummary::
+   :nosignatures:
+
+   FreeJoint
+   ExternalContact
+   FixedJoint
+   HingeJoint
+   SelfContact
+
+Compatibility
+~~~~~~~~~~~~~
+
+=============================== ==== =========== 
+Connection / Contact / Joints   Rod  Rigid Body
+=============================== ==== =========== 
+FreeJoint                       ✅   ✅
+ExternalContact                 ✅   ❌
+FixedJoint                      ✅   ✅
+HingeJoint                      ✅   ❌
+SelfContact                     ✅   ❌
+=============================== ==== =========== 
+
+Built-in Connection / Contact / Joint
+-------------------------------------
+
+.. autoclass:: FreeJoint
+   :special-members: __init__
+
+.. autoclass:: ExternalContact
+   :special-members: __init__
+
+.. autoclass:: FixedJoint
+   :special-members: __init__
+
+.. autoclass:: HingeJoint
+   :special-members: __init__
+
+.. autoclass:: SelfContact
+   :special-members: __init__

docs/api/constraints.rst

@@ -0,0 +1,73 @@
+Constraints
+===========
+
+.. _constraints:
+
+.. automodule::  elastica.boundary_conditions
+
+Description
+-----------
+
+Constraints are equivalent to displacement boundary condition.
+
+.. rubric:: Available Constraint
+
+.. autosummary::
+   :nosignatures:
+
+   ConstraintBase
+   FreeBC
+   OneEndFixedBC
+   FixedConstraint
+   HelicalBucklingBC
+   FreeRod
+   OneEndFixedRod
+
+Compatibility
+~~~~~~~~~~~~~
+
+=============================== ==== =========== 
+Constraint / Boundary Condition Rod  Rigid Body  
+=============================== ==== =========== 
+FreeBC                           ✅   ✅
+OneEndFixedBC                    ✅   ✅
+FixedConstraint                  ✅   ✅
+HelicalBucklingBC                ✅   ❌
+=============================== ==== =========== 
+
+Examples
+--------
+
+.. note::
+   PyElastica package provides basic built-in constraints, and we expect use to adapt their own boundary condition from our examples.
+
+Customizing boundary condition examples:
+
+- `Flexible Swinging Pendulum <https://github.com/GazzolaLab/PyElastica/tree/master/examples/FlexibleSwingingPendulumCase>`_
+- `Plectonemes <https://github.com/GazzolaLab/PyElastica/tree/master/examples/RodContactCase/RodSelfContact/PlectonemesCase>`_
+- `Solenoids <https://github.com/GazzolaLab/PyElastica/tree/master/examples/RodContactCase/RodSelfContact/SolenoidsCase>`_
+
+
+Built-in Constraints
+--------------------
+
+.. autoclass:: ConstraintBase
+   :inherited-members:
+   :undoc-members:
+   :exclude-members: 
+   :show-inheritance:
+
+.. autoclass:: FreeBC
+
+.. autoclass:: OneEndFixedBC
+   :special-members: __init__
+
+.. autoclass:: FixedConstraint
+   :special-members: __init__
+
+.. autoclass:: HelicalBucklingBC
+   :special-members: __init__
+
+.. autoclass:: FreeRod
+
+.. autoclass:: OneEndFixedRod