Metadata-Version: 2.5
Name: screws
Version: 0.10.0
Summary: Robotics in Python built on screw theory: kinematics, dynamics, formulas, pictures and a CoppeliaSim bridge
Project-URL: Homepage, https://github.com/ricopicone/screws
Project-URL: Documentation, https://ricopicone.github.io/screws/
Project-URL: Issues, https://github.com/ricopicone/screws/issues
Project-URL: Changelog, https://github.com/ricopicone/screws/blob/main/CHANGELOG.md
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
Keywords: Modern Robotics,dynamics,kinematics,product of exponentials,robotics,screw theory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: sympy>=1.12
Provides-Extra: coppelia
Requires-Dist: coppeliasim-zmqremoteapi-client==2.0.4; extra == 'coppelia'
Provides-Extra: plot
Requires-Dist: ipywidgets>=8; extra == 'plot'
Requires-Dist: matplotlib>=3.9; extra == 'plot'
Provides-Extra: video
Requires-Dist: imageio-ffmpeg>=0.4; extra == 'video'
Requires-Dist: imageio>=2.31; extra == 'video'
Description-Content-Type: text/markdown

# screws

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23873253.svg)](https://doi.org/10.5281/zenodo.23873253)

Robotics in Python, built on screw theory: every rigid-body motion is a screw motion, the
exponential of a twist, and an open chain is a product of such exponentials. Kinematics,
Jacobians and dynamics all follow from that. The notation is that of Lynch and Park,
*Modern Robotics* (MR).

- **The mathematics.** Rotations and rigid-body motions with their exponentials and
  logarithms; twists, wrenches and adjoints; forward and inverse kinematics; space and body
  Jacobians; manipulability and force ellipsoids; Newton-Euler dynamics; trajectories.
- **Robots.** A `Robot` class that carries M, the screw axes and the link inertias, a URDF
  loader, and three robots ready to use: a UR5, an RRP arm and a planar 2R arm.
- **Formulas.** `screws.symbolic` does the same computations in SymPy, so the product of
  exponentials, the Jacobians and the equations of motion come out in the joint variables.
- **Pictures.** `screws.viz` draws a robot with its screw axes, animates screw motions, and
  shows Jacobians and manipulability ellipsoids, still or while the robot moves, with joint
  sliders in a notebook.
- **Simulation.** `screws.coppelia` drives CoppeliaSim: read a robot off a scene, command it
  by position, velocity or torque, log and plot the run, and record a movie.
- **Checks.** `screws.testing` compares your own implementation of a function with the
  library's.

[![A UR5 in CoppeliaSim, driven by screws, swings a putter through a golf ball and sinks the putt](https://ricopicone.github.io/screws/media/putt.gif)](https://ricopicone.github.io/screws/examples/)

A UR5 sinks a putt in CoppeliaSim, driven through `screws.coppelia`. The package's own
pictures, of screw axes, screw motions, Jacobians and manipulability ellipsoids, are on the
**[Examples](https://ricopicone.github.io/screws/examples/)** page, each with the lines that draw it.

`screws` started from the MR code library, and all of that library is still here: each
function under a snake_case name, with MR's name kept as an alias
(`screws.FKinSpace is screws.fk_space`). The tests run every example in MR's docstrings
through those aliases.

## Install

One or the other:

```
uv add screws                 # the mathematics only; numpy and SymPy are the dependencies
uv add "screws[coppelia]"     # the same, plus the CoppeliaSim ZMQ remote API client
```

Extras for the bridge: `screws[plot]` (matplotlib, for `Log.plot`) and `screws[video]`
(imageio and ffmpeg, for `Recorder`). `uv add "screws[coppelia,plot,video]"` takes all three.

## Four lines

```python
import screws

ur5 = screws.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
```

## Documentation

The guide and the API reference are at <https://ricopicone.github.io/screws/>:

- **[Examples](https://ricopicone.github.io/screws/examples/)**: what the package draws, with the code under each picture
- [Kinematics and the Robot class](https://ricopicone.github.io/screws/guide/kinematics/), [dynamics and trajectories](https://ricopicone.github.io/screws/guide/dynamics/),
  and [checking your own code](https://ricopicone.github.io/screws/guide/checking/) against the library
- [Formulas](https://ricopicone.github.io/screws/guide/formulas/): the same computations in SymPy
- Pictures: [the screw axes](https://ricopicone.github.io/screws/guide/pictures/screw-axes/),
  [screw motions](https://ricopicone.github.io/screws/guide/pictures/screw-motions/), and
  [Jacobians and manipulability ellipsoids](https://ricopicone.github.io/screws/guide/pictures/jacobians/)
- [CoppeliaSim](https://ricopicone.github.io/screws/guide/coppelia/): driving the simulator, and a UR5 that putts
- [MR's names](https://ricopicone.github.io/screws/guide/names/) beside the `screws` names

## Help, contributing and citing

Questions and bug reports go in the [issues](https://github.com/ricopicone/screws/issues);
how to report one well, and how to propose a change, is in
[CONTRIBUTING.md](https://github.com/ricopicone/screws/blob/main/CONTRIBUTING.md). What each release changed is in
[CHANGELOG.md](https://github.com/ricopicone/screws/blob/main/CHANGELOG.md). To cite `screws`, use [CITATION.cff](https://github.com/ricopicone/screws/blob/main/CITATION.cff), or
GitHub's "Cite this repository" button, which reads it. Zenodo archives every release:
the DOI [10.5281/zenodo.23873253](https://doi.org/10.5281/zenodo.23873253) stands for `screws` as a whole and leads to
the latest version, and each version has a DOI of its own on that page.

## 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`](https://github.com/ricopicone/screws/blob/main/LICENSE).
