screws 0.1.0__tar.gz

screws-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run pytest -q

screws-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+# Runs when a version tag is pushed (git tag v0.1.0 && git push --tags).
+# Publishes with PyPI trusted publishing (OIDC) when the project has this workflow
+# registered as a publisher; otherwise falls back to the PYPI_API_TOKEN repository secret.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Check that the tag matches the package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv run --no-project python -c 'import tomllib,sys; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          test "$tag" = "$version" || { echo "tag v$tag != pyproject version $version"; exit 1; }
+          grep -q "__version__ = \"$version\"" screws/_version.py || { echo "_version.py disagrees"; exit 1; }
+      - run: uv sync --all-extras
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # trusted publishing
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

screws-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.superpowers/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

screws-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Rico Picone
+
+Portions of this software are derived from the Modern Robotics code library
+(https://github.com/NxRLab/ModernRobotics),
+Copyright (c) 2018 Huan Weng, Bill Hunt, Jarvis Schultz, Mikhail Todes,
+distributed under the same MIT License reproduced below.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

screws-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: screws
+Version: 0.1.0
+Summary: Screw-theory robotics: the Modern Robotics library, reorganised, with a CoppeliaSim bridge
+Author: Rico Picone
+License: MIT License
+        
+        Copyright (c) 2026 Rico Picone
+        
+        Portions of this software are derived from the Modern Robotics code library
+        (https://github.com/NxRLab/ModernRobotics),
+        Copyright (c) 2018 Huan Weng, Bill Hunt, Jarvis Schultz, Mikhail Todes,
+        distributed under the same MIT License reproduced below.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: coppelia
+Requires-Dist: coppeliasim-zmqremoteapi-client==2.0.4; extra == 'coppelia'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# screws
+
+Screw-theory robotics in Python, after Lynch and Park, *Modern Robotics* (MR).
+`screws` is the MR code library reorganised: the same mathematics under
+snake_case names, MR's own names kept as aliases, a `Robot` class, a URDF
+loader, robots that ship ready to use, and a bridge to CoppeliaSim.
+
+## Install
+
+```
+uv add screws                 # the mathematics: numpy is the only dependency
+uv add "screws[coppelia]"     # plus the CoppeliaSim ZMQ remote API client
+```
+
+## Four lines
+
+```python
+import screws as sc
+
+ur5 = sc.robots.ur5()                              # M, screw axes, inertias from the textbook's URDF
+T = ur5.fk([0.3, -1.2, 0.8, -0.4, 1.1, 0.2])         # a reachable, non-singular pose
+result = ur5.ik(T, theta0=[0.1, -1.4, 0.1, 0.1, 1.4, 0.1])   # result.theta, result.converged, result.history
+```
+
+The free functions are the reference implementation and read as the book does:
+`sc.exp6(sc.vec_to_se3(S * theta))` is $e^{[\mathcal{S}]\theta}$, `sc.fk_space(M, S, theta)`
+is the space form of the product of exponentials, and `sc.FKinSpace` is the very same
+function under MR's name.
+
+Screw-axis lists are **6xn, one axis per column**, as MR writes them. Nothing guesses the
+orientation (a 6x6 array is ambiguous for a six-axis arm), so hand entry goes through a
+sequence of 6-vectors: `sc.Robot.from_screw_axes(M, [S1, S2, ...])`.
+
+## Check your own code against the library
+
+```python
+import numpy as np
+import screws as sc
+
+def my_exp6(se3mat): ...                          # your implementation
+
+rng = np.random.default_rng(0)
+cases = [sc.vec_to_se3(rng.normal(size=6)) for _ in range(20)]
+sc.testing.check(my_exp6, sc.exp6, cases)          # raises on the first disagreement
+```
+
+## CoppeliaSim
+
+Works with CoppeliaSim 4.9 or later through the ZMQ remote API (0.1 verified on 4.10.0).
+
+```python
+from screws.coppelia import Scene
+
+with Scene() as scene:                 # connects to localhost:23000 in stepping mode
+    arm = scene.arm("/UR5")            # the joints under that tree, base to tip
+    robot = arm.robot()                # a screws.Robot read off the scene at zero
+    arm.mode("position")
+    log = scene.run(lambda t, theta, dtheta: theta_desired(t), duration=5.0, arm=arm)
+log.plot()
+```
+
+`Scene` owns the connection and the clock (`start`, `step`, `stop`, `time`, `dt`,
+`frame`, `show_frame`). `Arm` reads (`theta`, `dtheta`, `tau`, `tip_frame`) and commands
+in one of three modes (`position`, `velocity`, `torque`), or `teleport`s without physics
+to animate an IK history. `Arm.robot()` derives M and the screw axes from the scene's
+joint frames (omega is the joint's z axis, v = -omega x q). Scene inertias arrive in 0.2.
+
+## Two UR5s
+
+`sc.robots.ur5()` is built from the URDF the textbook prints in section 4.2: the
+manufacturer's lengths and the printed inertias, the closest published match to the
+simulator's model. `sc.robots.ur5(source="textbook")` is the rounded table of MR Figure
+4.6 with no inertias. They differ in the third decimal of the $v$ entries, and the course
+notes' problems ask why.
+
+## Names
+
+| Modern Robotics | `screws` |
+|---|---|
+| `NearZero` | `near_zero` |
+| `Normalize` | `normalize` |
+| `RotInv` | `rot_inv` |
+| `VecToso3` | `vec_to_so3` |
+| `so3ToVec` | `so3_to_vec` |
+| `AxisAng3` | `axis_angle3` |
+| `MatrixExp3` | `exp3` |
+| `MatrixLog3` | `log3` |
+| `RpToTrans` | `rp_to_transform` |
+| `TransToRp` | `transform_to_rp` |
+| `TransInv` | `transform_inv` |
+| `VecTose3` | `vec_to_se3` |
+| `se3ToVec` | `se3_to_vec` |
+| `Adjoint` | `adjoint` |
+| `ScrewToAxis` | `screw_axis` |
+| `AxisAng6` | `axis_angle6` |
+| `MatrixExp6` | `exp6` |
+| `MatrixLog6` | `log6` |
+| `ProjectToSO3` | `project_so3` |
+| `ProjectToSE3` | `project_se3` |
+| `DistanceToSO3` | `distance_so3` |
+| `DistanceToSE3` | `distance_se3` |
+| `TestIfSO3` | `is_so3` |
+| `TestIfSE3` | `is_se3` |
+| `FKinBody` | `fk_body` |
+| `FKinSpace` | `fk_space` |
+| `JacobianBody` | `jacobian_body` |
+| `JacobianSpace` | `jacobian_space` |
+| `IKinBody` | `ik_body` |
+| `IKinSpace` | `ik_space` |
+
+Where a screws function's signature matches MR's, the alias **is** that function
+(`sc.FKinSpace is sc.fk_space`). `IKinBody` and `IKinSpace` are thin wrappers that return
+MR's `(thetalist, success)` tuple; the primaries return an `IKResult` with the iteration
+history. No deprecation warnings, ever.
+
+## Licence
+
+MIT. Portions derived from the Modern Robotics code library, copyright 2018 Huan Weng,
+Bill Hunt, Jarvis Schultz and Mikhail Todes, MIT licence; see `LICENSE`.

screws-0.1.0/README.md

@@ -0,0 +1,119 @@
+# screws
+
+Screw-theory robotics in Python, after Lynch and Park, *Modern Robotics* (MR).
+`screws` is the MR code library reorganised: the same mathematics under
+snake_case names, MR's own names kept as aliases, a `Robot` class, a URDF
+loader, robots that ship ready to use, and a bridge to CoppeliaSim.
+
+## Install
+
+```
+uv add screws                 # the mathematics: numpy is the only dependency
+uv add "screws[coppelia]"     # plus the CoppeliaSim ZMQ remote API client
+```
+
+## Four lines
+
+```python
+import screws as sc
+
+ur5 = sc.robots.ur5()                              # M, screw axes, inertias from the textbook's URDF
+T = ur5.fk([0.3, -1.2, 0.8, -0.4, 1.1, 0.2])         # a reachable, non-singular pose
+result = ur5.ik(T, theta0=[0.1, -1.4, 0.1, 0.1, 1.4, 0.1])   # result.theta, result.converged, result.history
+```
+
+The free functions are the reference implementation and read as the book does:
+`sc.exp6(sc.vec_to_se3(S * theta))` is $e^{[\mathcal{S}]\theta}$, `sc.fk_space(M, S, theta)`
+is the space form of the product of exponentials, and `sc.FKinSpace` is the very same
+function under MR's name.
+
+Screw-axis lists are **6xn, one axis per column**, as MR writes them. Nothing guesses the
+orientation (a 6x6 array is ambiguous for a six-axis arm), so hand entry goes through a
+sequence of 6-vectors: `sc.Robot.from_screw_axes(M, [S1, S2, ...])`.
+
+## Check your own code against the library
+
+```python
+import numpy as np
+import screws as sc
+
+def my_exp6(se3mat): ...                          # your implementation
+
+rng = np.random.default_rng(0)
+cases = [sc.vec_to_se3(rng.normal(size=6)) for _ in range(20)]
+sc.testing.check(my_exp6, sc.exp6, cases)          # raises on the first disagreement
+```
+
+## CoppeliaSim
+
+Works with CoppeliaSim 4.9 or later through the ZMQ remote API (0.1 verified on 4.10.0).
+
+```python
+from screws.coppelia import Scene
+
+with Scene() as scene:                 # connects to localhost:23000 in stepping mode
+    arm = scene.arm("/UR5")            # the joints under that tree, base to tip
+    robot = arm.robot()                # a screws.Robot read off the scene at zero
+    arm.mode("position")
+    log = scene.run(lambda t, theta, dtheta: theta_desired(t), duration=5.0, arm=arm)
+log.plot()
+```
+
+`Scene` owns the connection and the clock (`start`, `step`, `stop`, `time`, `dt`,
+`frame`, `show_frame`). `Arm` reads (`theta`, `dtheta`, `tau`, `tip_frame`) and commands
+in one of three modes (`position`, `velocity`, `torque`), or `teleport`s without physics
+to animate an IK history. `Arm.robot()` derives M and the screw axes from the scene's
+joint frames (omega is the joint's z axis, v = -omega x q). Scene inertias arrive in 0.2.
+
+## Two UR5s
+
+`sc.robots.ur5()` is built from the URDF the textbook prints in section 4.2: the
+manufacturer's lengths and the printed inertias, the closest published match to the
+simulator's model. `sc.robots.ur5(source="textbook")` is the rounded table of MR Figure
+4.6 with no inertias. They differ in the third decimal of the $v$ entries, and the course
+notes' problems ask why.
+
+## Names
+
+| Modern Robotics | `screws` |
+|---|---|
+| `NearZero` | `near_zero` |
+| `Normalize` | `normalize` |
+| `RotInv` | `rot_inv` |
+| `VecToso3` | `vec_to_so3` |
+| `so3ToVec` | `so3_to_vec` |
+| `AxisAng3` | `axis_angle3` |
+| `MatrixExp3` | `exp3` |
+| `MatrixLog3` | `log3` |
+| `RpToTrans` | `rp_to_transform` |
+| `TransToRp` | `transform_to_rp` |
+| `TransInv` | `transform_inv` |
+| `VecTose3` | `vec_to_se3` |
+| `se3ToVec` | `se3_to_vec` |
+| `Adjoint` | `adjoint` |
+| `ScrewToAxis` | `screw_axis` |
+| `AxisAng6` | `axis_angle6` |
+| `MatrixExp6` | `exp6` |
+| `MatrixLog6` | `log6` |
+| `ProjectToSO3` | `project_so3` |
+| `ProjectToSE3` | `project_se3` |
+| `DistanceToSO3` | `distance_so3` |
+| `DistanceToSE3` | `distance_se3` |
+| `TestIfSO3` | `is_so3` |
+| `TestIfSE3` | `is_se3` |
+| `FKinBody` | `fk_body` |
+| `FKinSpace` | `fk_space` |
+| `JacobianBody` | `jacobian_body` |
+| `JacobianSpace` | `jacobian_space` |
+| `IKinBody` | `ik_body` |
+| `IKinSpace` | `ik_space` |
+
+Where a screws function's signature matches MR's, the alias **is** that function
+(`sc.FKinSpace is sc.fk_space`). `IKinBody` and `IKinSpace` are thin wrappers that return
+MR's `(thetalist, success)` tuple; the primaries return an `IKResult` with the iteration
+history. No deprecation warnings, ever.
+
+## Licence
+
+MIT. Portions derived from the Modern Robotics code library, copyright 2018 Huan Weng,
+Bill Hunt, Jarvis Schultz and Mikhail Todes, MIT licence; see `LICENSE`.

screws-0.1.0/docs/RELEASING.md

@@ -0,0 +1,21 @@
+# Releasing screws
+
+1. `uv run ruff check .` and `uv run pytest -q` are clean.
+2. With CoppeliaSim open (4.9 or later; 0.1 was verified on 4.10.0) and the stock UR5 model
+   loaded at `/UR5` (Model browser > robots > non-mobile > UR5.ttm; no tip dummy needed),
+   run the simulator tests: `SCREWS_COPPELIASIM=1 uv run pytest -q -m coppelia`.
+   If a run is killed mid-way the simulation can be left waiting on a dead stepping
+   client; `Scene.start()` stops such a simulation first, so a rerun recovers by itself.
+3. Bump the version in `screws/_version.py` and `pyproject.toml` (they must agree;
+   `tests/test_readme_table.py` pins the release number).
+4. If `screws/aliases.py` changed, regenerate the README table with
+   `uv run python tools/print_alias_table.py` and paste it under "Names".
+5. If the `modern_robotics` dev pin changed, re-harvest the docstring examples:
+   `uv run python tools/harvest_mr_examples.py`.
+6. Commit, then tag and push the tag: `git tag v<version> && git push origin v<version>`.
+   The `Publish to PyPI` workflow (`.github/workflows/publish.yml`) checks that the tag
+   matches `pyproject.toml` and `_version.py`, runs the suite, builds, and uploads.
+   It uses the `PYPI_API_TOKEN` repository secret when set, else PyPI trusted publishing
+   (register the workflow as a publisher for `screws` on pypi.org, environment `pypi`).
+   Fallback by hand: `uv build && uvx twine upload dist/*` (`uv publish` ignores `~/.pypirc`).
+7. Watch it: `gh run watch`. Then pin the new version in the course repo.