Add Rotation class with docs and bindings by chemiskyy · Pull Request #66 · 3MAH/simcoon

chemiskyy · 2026-02-04T17:04:01Z

This pull request introduces a major enhancement to Simcoon 2.0 by adding a comprehensive new 3D rotation library centered around a Rotation class, with full Python bindings and extensive documentation. The changes improve both the C++ and Python APIs, update the documentation to reflect the new capabilities, and ensure the new class is tested and integrated throughout the build system.

Rotation Library Addition and Integration:

Introduced a new Rotation class for 3D rotations, using unit quaternions internally for stability and efficiency, with support for various representations (Euler angles, rotation matrices, quaternions, rotation vectors, axis-angle), composition, interpolation (SLERP), and Voigt notation transformations. The class is available in both C++ and Python APIs. [1] [2]
Registered the Rotation class in the Python bindings via pybind11, including the new wrapper source and header files in the build system for both C++ and Python modules. [1] [2] [3] [4]
Added unit tests for the new Rotation class to the test suite.

Documentation Updates:

Added a comprehensive new documentation page (doc_rotation.rst) detailing the Rotation class, its API, usage examples, and practical applications in continuum mechanics.
Updated the continuum mechanics and maths documentation to reference and describe the new rotation tools, and added the new page to the documentation index. [1] [2]
Updated the C++ API documentation to include the new rotation module, and provided a summary of new features in Simcoon 2.0, highlighting the enhanced rotation capabilities. [1] [2]Introduce a new Rotation subsystem: adds a C++ Rotation class (include/.../rotation_class.hpp and src/Simulation/Maths/rotation_class.cpp) implementing quaternion-based 3D rotations, Voigt operations, Euler conventions, SLERP, and apply methods for vectors/tensors. Add Python bindings (pybind11) and headers in simcoon-python-builder, update its CMake to build the rotation_class wrapper, and extend the python module registration. Add comprehensive documentation pages (continuum mechanics and C++ API) and index updates. Include a unit test (test/Libraries/Maths/TRotationClass.cpp) and adjust top-level CMakeLists where needed. This patch adds rotation functionality, docs, bindings, and tests to enable quaternion-based rotation operations from C++ and Python.

Introduce a new Rotation subsystem: adds a C++ Rotation class (include/.../rotation_class.hpp and src/Simulation/Maths/rotation_class.cpp) implementing quaternion-based 3D rotations, Voigt operations, Euler conventions, SLERP, and apply methods for vectors/tensors. Add Python bindings (pybind11) and headers in simcoon-python-builder, update its CMake to build the rotation_class wrapper, and extend the python module registration. Add comprehensive documentation pages (continuum mechanics and C++ API) and index updates. Include a unit test (test/Libraries/Maths/TRotationClass.cpp) and adjust top-level CMakeLists where needed. This patch adds rotation functionality, docs, bindings, and tests to enable quaternion-based rotation operations from C++ and Python.

Add input validation helpers in the Python wrapper (validate_vector_size, validate_matrix_size) and apply them to rotation bindings to ensure correct array shapes. Add SciPy interoperability: Rotation.from_scipy and to_scipy methods with docs and conversions via quaternions. Replace uses of legacy sim_pi/sim_iota with simcoon::pi and simcoon::iota across Rotation implementation and update tests accordingly to use the centralized constants. This improves robustness of the Python API and unifies constant usage in the core code and tests.

Expand rotation Python docs with Scipy interoperability, active vs passive rotation conventions, input validation guidance, and notes on quaternion equivalence. Fix cross‑references in C++ API docs to point to the correct continuum_mechanics doc pages. Rename test file to Trotation_class.cpp, update CMakeLists, and add comprehensive Rotation unit tests (tensor/stiffness/compliance behavior, factory methods, Euler conventions, round‑trip and gimbal‑lock cases) to improve coverage and verify correctness.

include/simcoon/Simulation/Maths/rotation_class.hpp

Rename ambiguous as_QS/as_QE to explicit as_voigt_stress_rotation/as_voigt_strain_rotation and add apply_localization_strain/apply_localization_stress to Rotation API. Update implementation, header, Python bindings, documentation and tests to use the new names and to expose rotation of localization tensors (QE·A·QS^T and QS·B·QE^T). Refactor callers (ellipsoid_multi, state_variables*, etc.) to use Rotation::from_euler and the new apply_* methods instead of ad-hoc rotate_* helpers; add necessary includes and input validation for 6×6 tensors. Add unit tests verifying consistency with existing fillQS/fillQE/rotateA/rotateB functions and update docs to reflect the new API and examples.

Remove default values for Euler convention and active/passive flags across rotation APIs and pybind bindings to force callers to specify convention and mode. Updated C++ headers (rotation.hpp, rotation_class.hpp) and Python wrappers to make conv and active mandatory, adjusted pybind registrations in python_module.cpp and rotation_class.cpp, and updated tests (Trotation.cpp) to pass explicit arguments. Also add simcoon_docs rotation docstrings (doc_rotation.hpp) and hook them into module definitions for improved Python documentation.

Docs updated to remove references to a "default" Euler convention and require the convention to be specified in examples. In rotation.cpp, the previous behavior of printing an error and falling back to default axes has been replaced with throwing std::invalid_argument when an invalid Euler convention is supplied (message lists supported conventions). This enforces explicit, valid conventions and prevents silent fallback. Affected files: docs/continuum_mechanics/functions/doc_rotation.rst, docs/cpp_api/simulation/rotation.rst, src/Simulation/Maths/rotation.cpp.

Rename and reorganize rotation-related documentation to match updated API names and types. Key changes: - Replace old function names with clearer ones: rotateL/rotateM -> rotate_stiffness/rotate_compliance; apply_localization_* -> apply_*_concentration; rotate_l2g_*/g2l_* functions replaced by *_R and *_angle variants. - Update free-function autodoc/doxygen entries and Python autofunction names accordingly. - Change C++ include references from rotation_class.hpp to rotation.hpp and document new Rotation construction functions (Rotation::from_euler, Rotation::from_axis_angle). - Update examples to use Rotation::from_euler or pass a Rotation matrix to free functions. These edits align the docs with the refactored rotation API and clarify naming (strain/stress concentration vs localization).

Rename and reorganize rotation-related Python wrappers and docs for clarity and vectorized usage. Replaced legacy fillR/fillQS/fillQE and rotateL/M/A/B/l2g/g2l APIs with clearer functions (rotate_stiffness_*, rotate_compliance_*, rotate_strain_concentration_*, rotate_stress_concentration_*, rotate_strain_*, rotate_stress_*), updated wrapper implementations to use descriptive variable names and support batched (ndim==2) inputs, and adjusted Rotation class method names (apply_localization_* -> apply_*_concentration). Also updated example docs to use simcoon.Rotation.from_axis_angle(...). Modified files: include/docs/Libraries/Maths/doc_rotation.hpp, include/simcoon/python_wrappers/Libraries/Maths/rotation.hpp, src/python_wrappers/Libraries/Maths/rotation.cpp, src/python_wrappers/Libraries/Maths/rotation_class.cpp, src/python_wrappers/python_module.cpp.

Introduce a unified Rotation class into rotation.hpp (merged from the removed rotation_class.hpp) providing quaternion-based factories, conversions, and apply methods for vectors, tensors and Voigt-notation quantities. Rename and refactor many legacy free functions (fillR / fillQS / fillQE / rotateL / rotateM / rotateA / rotateB / etc.) to clearer APIs (rotate_vec/rotate_mat, rotate_stress, rotate_strain, rotate_stiffness, rotate_compliance, rotate_strain_concentration, rotate_stress_concentration, etc.). Update the Python example to use sim.Rotation.from_axis_angle / from_euler and the new rotate_* function names. Remove the standalone rotation_class header and corresponding legacy sources to consolidate rotation functionality; this is a breaking API change that modernizes rotation handling and exposes richer functionality (quaternions, Euler, rotvec, Voigt helpers, slerp, composition, etc.).

Replace legacy rotation helpers with the new Rotation class methods across the codebase and tests. Updates include: using Rotation::from_euler / from_matrix and its apply_* helpers (apply_stiffness, apply_compliance, apply_strain/apply_stress, apply_strain_concentration/apply_stress_concentration) instead of free functions like rotateL, rotateM, rotateA, rotate_g2l_L, rotate_g2l_stress, rotate_l2g_A, fillR, fillQE/QS, etc. Remove includes of rotation_class.hpp where no longer needed. Adjusted unit tests to construct expected rotations via the Rotation API and to validate transformations by applying rotations to vectors/matrices rather than calling the old utility functions. Changes touch continuum mechanics, homogenization, micromechanics schemes, phase state variables, and math tests to unify on the new rotation interface and improve consistency.

kmarchais · 2026-02-06T14:21:54Z

examples/continuum_mechanics/rotation.py

This should be updated too?

kmarchais · 2026-02-06T14:22:02Z

examples/continuum_mechanics/rotation.py

kmarchais · 2026-02-06T14:24:24Z

simcoon-python-builder/include/simcoon/docs/Libraries/Maths/doc_rotation.hpp

Is this still up to date?

It is not!, will be removed in a next commit

kmarchais · 2026-02-06T14:25:06Z

simcoon-python-builder/include/simcoon/python_wrappers/Libraries/Maths/rotation.hpp

Up-to-date?

All file will be removed in a forthcoming commit

kmarchais · 2026-02-06T14:25:31Z

simcoon-python-builder/include/simcoon/python_wrappers/Libraries/Maths/rotation.hpp

Up-to-date?

same, all these functions should disappear, not more _R or _angle

kmarchais · 2026-02-06T14:26:26Z

simcoon-python-builder/src/python_wrappers/Libraries/Maths/rotation.cpp

Up-to-date?

The file will disappear

kmarchais · 2026-02-06T14:27:03Z

simcoon-python-builder/src/python_wrappers/python_module.cpp

Up-to-date?

Same, all these functions are to be removed

test/Libraries/Maths/Trotation.cpp

kmarchais · 2026-02-06T14:30:29Z

src/Simulation/Maths/rotation.cpp

@@ -75,16 +116,16 @@ mat fillR(const double &alpha, const int &axis, const bool &active) {
            break;
        }
        default: {
-            cout << "Please choose the axis 1,2 or 3\n";
+            throw invalid_argument("Please choose the axis 1, 2 or 3");
        }
    }
    return R;
 }

-mat fillR(const double &psi, const double &theta, const double &phi, const bool &active, const std::string &conv) {
-    
+// Internal: Generate a 3x3 rotation matrix using Euler angles
+mat fillR_euler_internal(const double &psi, const double &theta, const double &phi, const bool &active, const std::string &conv) {


Remaining R notations?

the file will disappear

kmarchais

Probably there are still a few notations left to modify unless this is intentional

Remove the legacy Python bindings and documentation for the standalone rotation free-functions and migrate examples/docs to use the Rotation class API. Changes: - Docs: updated docs/continuum_mechanics/functions/doc_rotation.rst and docs/cpp_api/simulation/rotation.rst to remove free-function sections and emphasize the Rotation class. - Examples: examples/continuum_mechanics/rotation.py rewritten to use simcoon.Rotation (from_axis_angle/from_euler and apply/apply_tensor/apply_stress/etc.) instead of the rotate_* free functions. - Python bindings: deleted simcoon-python-builder/include/simcoon/docs/Libraries/Maths/doc_rotation.hpp, include/simcoon/python_wrappers/Libraries/Maths/rotation.hpp and src/python_wrappers/Libraries/Maths/rotation.cpp; removed their registration from python_module.cpp. - Build: simcoon-python-builder/CMakeLists.txt no longer compiles src/python_wrappers/Libraries/Maths/rotation.cpp. Rationale: consolidate the public Python API around the object-oriented Rotation class and remove duplicated/free-function Python wrappers while keeping the Rotation class binding and C++ API intact.

Rename the Rotation pybind11 wrapper files and update references: rotation_class.hpp -> rotation.hpp and rotation_class.cpp -> rotation.cpp. Rename the registration function register_rotation_class -> register_rotation and update its declaration, definition, includes, and the call in python_module.cpp. Update CMakeLists.txt to build src/python_wrappers/Libraries/Maths/rotation.cpp. This unifies the wrapper naming and keeps module registration consistent.

Make simcoon.Rotation a subclass of scipy.spatial.transform.Rotation and add full scipy interoperability. Adds a pure-Python simcoon.rotation.Rotation wrapper that inherits scipy Rotation and delegates mechanics operations (apply_stress/strain/stiffness/etc.) to the C++ backend via a new _CppRotation interface. The C++ pybind wrapper was adjusted to expose simcoon::Rotation as _CppRotation and to accept plain scipy-like Rotation objects (duck-typed via as_quat) for composition, slerp and equality. Updated package metadata to require scipy, refreshed docs and examples to use scipy Euler conventions and show interoperability, and added comprehensive tests for type identity, mechanics methods, scipy upgrades, and C++ handling of scipy objects. Also import Rotation in __init__ to override the star-imported C++ class.

chemiskyy marked this pull request as draft February 4, 2026 17:04

chemiskyy added 2 commits February 5, 2026 16:28

kmarchais reviewed Feb 5, 2026

View reviewed changes

include/simcoon/Simulation/Maths/rotation_class.hpp Outdated Show resolved Hide resolved

kmarchais approved these changes Feb 5, 2026

View reviewed changes

chemiskyy marked this pull request as ready for review February 5, 2026 22:13

chemiskyy added 2 commits February 6, 2026 09:45

chemiskyy added the enhancement New feature or request label Feb 6, 2026

chemiskyy added 5 commits February 6, 2026 15:09

Update CMakeLists.txt

f958165

kmarchais reviewed Feb 6, 2026

View reviewed changes

examples/continuum_mechanics/rotation.py Outdated

Comment on lines 160 to 165

Copy link

Member

kmarchais Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be updated too?

kmarchais reviewed Feb 6, 2026

View reviewed changes

examples/continuum_mechanics/rotation.py Outdated

Comment on lines 194 to 195

Copy link

Member

kmarchais Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This too?

kmarchais reviewed Feb 6, 2026

View reviewed changes

test/Libraries/Maths/Trotation.cpp Show resolved Hide resolved

kmarchais reviewed Feb 6, 2026

View reviewed changes

kmarchais requested changes Feb 6, 2026

View reviewed changes

chemiskyy added 2 commits February 6, 2026 16:53

kmarchais approved these changes Feb 7, 2026

View reviewed changes

chemiskyy added this to simcoon 2.0 Feb 7, 2026

github-project-automation bot moved this to Backlog in simcoon 2.0 Feb 7, 2026

chemiskyy added 5 commits February 13, 2026 11:36

Update rotation.rst

475b5bd

Update rotation.cpp

62742fd

Update test_rotation.py

e660088

Update doc_rotation.rst

092bfbe

Conversation

chemiskyy commented Feb 4, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chemiskyy Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kmarchais left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

chemiskyy Feb 6, 2026 •

edited

Loading