turtlend 0.1.0__tar.gz

turtlend-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Eric G. Suchanek, PhD
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

turtlend-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: turtlend
+Version: 0.1.0
+Summary: A turtle that carries its own orthonormal frame through 3- or N-dimensional space
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: turtle,turtle-geometry,coordinate-frame,givens-rotation,n-dimensional,manifold,embedding,molecular-modeling
+Author: Eric G. Suchanek, PhD
+Author-email: suchanek@flux-frontiers.com
+Requires-Python: >=3.12,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: numpy (>=1.26)
+Project-URL: Documentation, https://flux-frontiers.github.io/turtlend/
+Project-URL: Homepage, https://github.com/Flux-Frontiers/turtlend
+Project-URL: Issues, https://github.com/Flux-Frontiers/turtlend/issues
+Project-URL: Repository, https://github.com/Flux-Frontiers/turtlend
+Description-Content-Type: text/markdown
+
+# turtlend
+
+A turtle that carries its own orthonormal frame through 3- or N-dimensional space.
+
+`turtlend` provides three classes and depends only on NumPy:
+
+- `TurtleND` holds a position and an orthonormal frame in N dimensions. It moves
+  along its heading and rotates in the plane of any two basis vectors.
+- `Turtle3D` is the three-dimensional turtle that `TurtleND` generalizes. It
+  builds molecular geometry from bond lengths, bond angles and dihedral angles.
+- `Vector3D` is the vector class that `Turtle3D` uses, with helper functions
+  for angles, dihedrals and distances.
+
+`Turtle3D` began as C code written in 1990 and was ported to Python for
+[proteusPy](https://github.com/suchanek/proteusPy). `TurtleND` was written for
+[WaveRider](https://github.com/Flux-Frontiers/waverider). Both packages carried
+their own copies of these modules. This package is the single source for both.
+
+## Install
+
+```bash
+pip install turtlend
+```
+
+`turtlend` requires Python 3.12 or 3.13.
+
+## Move a turtle in N dimensions
+
+All angles are in degrees.
+
+```python
+from turtlend import TurtleND
+
+turtle = TurtleND(ndim=5)
+turtle.move(1.0)             # along the heading, frame[0]
+turtle.rotate(90.0, 0, 3)    # in the plane of basis vectors 0 and 3
+turtle.move(1.0)
+
+print(turtle.position)       # position in global coordinates
+print(turtle.heading)        # frame[0]
+```
+
+In three or more dimensions, `roll`, `pitch`, `yaw` and `turn` are named cases
+of `rotate` and follow the `Turtle3D` conventions.
+
+To convert a vector between the global frame and the turtle's frame, call
+`to_local` or `to_global`.
+
+## Record a path
+
+To record each position the turtle visits, set `recording` to `True`:
+
+```python
+turtle.recording = True
+turtle.move(1.0)
+turtle.turn(30.0)
+turtle.move(1.0)
+
+path = turtle.tape           # list of position arrays
+turtle.reset_tape()
+```
+
+## Add a dimension to a live turtle
+
+`expand_dim` grows the position and the frame from N to N+1 dimensions and
+returns the index of the new axis. The existing basis vectors are unchanged.
+
+```python
+axis = turtle.expand_dim(label="time")
+turtle.orient_in_time(axis)  # heading becomes the negative unit vector of that axis
+```
+
+`orient_in_time` points the heading along the negative direction of the axis.
+To rotate the heading toward an arbitrary direction, call `orient_toward`.
+
+## Use the 3-D turtle
+
+```python
+from turtlend import Turtle3D
+
+turtle = Turtle3D()
+turtle.move(1.53)
+turtle.turn(109.5)
+turtle.roll(60.0)
+```
+
+To place the turtle on a protein backbone, call `orient_from_backbone` with
+the N, CA, CB and C atom positions as NumPy arrays.
+
+## Develop
+
+```bash
+poetry install --with dev
+poetry run pytest
+```
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).
+

turtlend-0.1.0/README.md

@@ -0,0 +1,99 @@
+# turtlend
+
+A turtle that carries its own orthonormal frame through 3- or N-dimensional space.
+
+`turtlend` provides three classes and depends only on NumPy:
+
+- `TurtleND` holds a position and an orthonormal frame in N dimensions. It moves
+  along its heading and rotates in the plane of any two basis vectors.
+- `Turtle3D` is the three-dimensional turtle that `TurtleND` generalizes. It
+  builds molecular geometry from bond lengths, bond angles and dihedral angles.
+- `Vector3D` is the vector class that `Turtle3D` uses, with helper functions
+  for angles, dihedrals and distances.
+
+`Turtle3D` began as C code written in 1990 and was ported to Python for
+[proteusPy](https://github.com/suchanek/proteusPy). `TurtleND` was written for
+[WaveRider](https://github.com/Flux-Frontiers/waverider). Both packages carried
+their own copies of these modules. This package is the single source for both.
+
+## Install
+
+```bash
+pip install turtlend
+```
+
+`turtlend` requires Python 3.12 or 3.13.
+
+## Move a turtle in N dimensions
+
+All angles are in degrees.
+
+```python
+from turtlend import TurtleND
+
+turtle = TurtleND(ndim=5)
+turtle.move(1.0)             # along the heading, frame[0]
+turtle.rotate(90.0, 0, 3)    # in the plane of basis vectors 0 and 3
+turtle.move(1.0)
+
+print(turtle.position)       # position in global coordinates
+print(turtle.heading)        # frame[0]
+```
+
+In three or more dimensions, `roll`, `pitch`, `yaw` and `turn` are named cases
+of `rotate` and follow the `Turtle3D` conventions.
+
+To convert a vector between the global frame and the turtle's frame, call
+`to_local` or `to_global`.
+
+## Record a path
+
+To record each position the turtle visits, set `recording` to `True`:
+
+```python
+turtle.recording = True
+turtle.move(1.0)
+turtle.turn(30.0)
+turtle.move(1.0)
+
+path = turtle.tape           # list of position arrays
+turtle.reset_tape()
+```
+
+## Add a dimension to a live turtle
+
+`expand_dim` grows the position and the frame from N to N+1 dimensions and
+returns the index of the new axis. The existing basis vectors are unchanged.
+
+```python
+axis = turtle.expand_dim(label="time")
+turtle.orient_in_time(axis)  # heading becomes the negative unit vector of that axis
+```
+
+`orient_in_time` points the heading along the negative direction of the axis.
+To rotate the heading toward an arbitrary direction, call `orient_toward`.
+
+## Use the 3-D turtle
+
+```python
+from turtlend import Turtle3D
+
+turtle = Turtle3D()
+turtle.move(1.53)
+turtle.turn(109.5)
+turtle.roll(60.0)
+```
+
+To place the turtle on a protein backbone, call `orient_from_backbone` with
+the N, CA, CB and C atom positions as NumPy arrays.
+
+## Develop
+
+```bash
+poetry install --with dev
+poetry run pytest
+```
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).

turtlend-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+# pyproject.toml -- turtlend package configuration
+#
+# Author: Eric G. Suchanek, PhD
+#
+# Install
+# -------
+#   poetry install --with dev          package + test and lint tooling
+#   poetry install --with docs         + mkdocs, to build the Pages site
+#   pip install -e .                   package only
+#
+# Run tests
+# ---------
+#   poetry install --with dev          prerequisite
+#   pytest                             uses [tool.pytest.ini_options]
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "turtlend", from = "src" }]
+
+[project]
+name = "turtlend"
+version = "0.1.0"
+description = "A turtle that carries its own orthonormal frame through 3- or N-dimensional space"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Eric G. Suchanek, PhD", email = "suchanek@flux-frontiers.com" }]
+keywords = [
+    "turtle",
+    "turtle-geometry",
+    "coordinate-frame",
+    "givens-rotation",
+    "n-dimensional",
+    "manifold",
+    "embedding",
+    "molecular-modeling",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12,<3.14"
+
+# numpy is the whole runtime. waverider and proteusPy both depend on this
+# package, so anything added here lands in both of their locks.
+dependencies = ["numpy>=1.26"]
+
+[project.urls]
+Homepage = "https://github.com/Flux-Frontiers/turtlend"
+Repository = "https://github.com/Flux-Frontiers/turtlend"
+Documentation = "https://flux-frontiers.github.io/turtlend/"
+Issues = "https://github.com/Flux-Frontiers/turtlend/issues"
+
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=9.0.3"
+pytest-cov = ">=5.0"
+ruff = ">=0.15"
+ty = ">=0.0.41"
+pre-commit = ">=4.5.1"
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+mkdocs-material = ">=9.5"
+mkdocstrings = { version = ">=0.26", extras = ["python"] }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --cov=turtlend --cov-report=term-missing --cov-fail-under=80"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+# Turtle3D.new() takes Vector3D defaults. It normalizes them into new vectors
+# and never mutates or stores the defaults, so the shared instances are safe.
+"src/turtlend/turtle3D.py" = ["B008"]
+
+[tool.pycodekg]
+exclude = ["tests"]
+include = ["src"]

turtlend-0.1.0/src/turtlend/__init__.py

@@ -0,0 +1,43 @@
+"""
+turtlend: a turtle that carries its own coordinate frame, in 3 or N dimensions.
+
+``TurtleND`` holds a position and an orthonormal frame in N-dimensional space.
+It moves along its heading and rotates in the plane of any two basis vectors.
+``Turtle3D`` is the three-dimensional original it generalizes, and ``Vector3D``
+is the vector class ``Turtle3D`` is built on.
+
+Author: Eric G. Suchanek, PhD
+Affiliation: Flux-Frontiers, https://github.com/Flux-Frontiers
+License: BSD-3-Clause
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .turtle3D import ORIENT_BACKBONE, ORIENT_SIDECHAIN, Turtle3D
+from .turtleND import TurtleND
+from .vector3D import (
+    Vector3D,
+    calc_angle,
+    calc_dihedral,
+    calculate_bond_angle,
+    distance3d,
+    rms_difference,
+)
+
+try:
+    __version__ = version("turtlend")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ORIENT_BACKBONE",
+    "ORIENT_SIDECHAIN",
+    "Turtle3D",
+    "TurtleND",
+    "Vector3D",
+    "calc_angle",
+    "calc_dihedral",
+    "calculate_bond_angle",
+    "distance3d",
+    "rms_difference",
+]