imt-ring 1.6.3__tar.gz → 1.6.5__tar.gz

{imt_ring-1.6.3 → imt_ring-1.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: imt-ring
-Version: 1.6.3
+Version: 1.6.5
 Summary: RING: Recurrent Inertial Graph-based Estimator
 Author-email: Simon Bachhuber <simon.bachhuber@fau.de>
 Project-URL: Homepage, https://github.com/SimiPixel/ring
@@ -60,6 +60,36 @@ pip install --upgrade "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-re
 
 Available [here](https://simipixel.github.io/ring/).
 
+## Quickstart Example
+```python
+import ring
+import numpy as np
+
+T  : int       = 30        # sequence length     [s]
+Ts : float     = 0.01      # sampling interval   [s]
+B  : int       = 1         # batch size
+lam: list[int] = [0, 1, 2] # parent array
+N  : int       = len(lam)  # number of bodies
+T_i: int       = int(T/Ts) # number of timesteps
+
+X              = np.zeros((B, T_i, N, 9))
+# where X is structured as follows:
+# X[..., :3]   = acc
+# X[..., 3:6]  = gyr
+# X[..., 6:9]  = jointaxis
+
+# let's assume we have an IMU on each outer segment of the
+# three-segment kinematic chain
+X[..., 0, :3]  = acc_segment1
+X[..., 2, :3]  = acc_segment3
+X[..., 0, 3:6] = gyr_segment1
+X[..., 2, 3:6] = gyr_segment3
+
+ringnet = ring.RING(lam, Ts)
+yhat, _ = ringnet.apply(X)
+# yhat: unit quaternions, shape = (B, T_i, N, 4)
+```
+
 ### Known fixes
 
 #### Offscreen rendering with Mujoco

{imt_ring-1.6.3 → imt_ring-1.6.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "imt-ring"
-version = "1.6.3"
+version = "1.6.5"
 authors = [
   { name="Simon Bachhuber", email="simon.bachhuber@fau.de" },
 ]

{imt_ring-1.6.3 → imt_ring-1.6.5}/readme.md

@@ -22,6 +22,36 @@ pip install --upgrade "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-re
 
 Available [here](https://simipixel.github.io/ring/).
 
+## Quickstart Example
+```python
+import ring
+import numpy as np
+
+T  : int       = 30        # sequence length     [s]
+Ts : float     = 0.01      # sampling interval   [s]
+B  : int       = 1         # batch size
+lam: list[int] = [0, 1, 2] # parent array
+N  : int       = len(lam)  # number of bodies
+T_i: int       = int(T/Ts) # number of timesteps
+
+X              = np.zeros((B, T_i, N, 9))
+# where X is structured as follows:
+# X[..., :3]   = acc
+# X[..., 3:6]  = gyr
+# X[..., 6:9]  = jointaxis
+
+# let's assume we have an IMU on each outer segment of the
+# three-segment kinematic chain
+X[..., 0, :3]  = acc_segment1
+X[..., 2, :3]  = acc_segment3
+X[..., 0, 3:6] = gyr_segment1
+X[..., 2, 3:6] = gyr_segment3
+
+ringnet = ring.RING(lam, Ts)
+yhat, _ = ringnet.apply(X)
+# yhat: unit quaternions, shape = (B, T_i, N, 4)
+```
+
 ### Known fixes
 
 #### Offscreen rendering with Mujoco

{imt_ring-1.6.3 → imt_ring-1.6.5}/src/imt_ring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: imt-ring
-Version: 1.6.3
+Version: 1.6.5
 Summary: RING: Recurrent Inertial Graph-based Estimator
 Author-email: Simon Bachhuber <simon.bachhuber@fau.de>
 Project-URL: Homepage, https://github.com/SimiPixel/ring
@@ -60,6 +60,36 @@ pip install --upgrade "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-re
 
 Available [here](https://simipixel.github.io/ring/).
 
+## Quickstart Example
+```python
+import ring
+import numpy as np
+
+T  : int       = 30        # sequence length     [s]
+Ts : float     = 0.01      # sampling interval   [s]
+B  : int       = 1         # batch size
+lam: list[int] = [0, 1, 2] # parent array
+N  : int       = len(lam)  # number of bodies
+T_i: int       = int(T/Ts) # number of timesteps
+
+X              = np.zeros((B, T_i, N, 9))
+# where X is structured as follows:
+# X[..., :3]   = acc
+# X[..., 3:6]  = gyr
+# X[..., 6:9]  = jointaxis
+
+# let's assume we have an IMU on each outer segment of the
+# three-segment kinematic chain
+X[..., 0, :3]  = acc_segment1
+X[..., 2, :3]  = acc_segment3
+X[..., 0, 3:6] = gyr_segment1
+X[..., 2, 3:6] = gyr_segment3
+
+ringnet = ring.RING(lam, Ts)
+yhat, _ = ringnet.apply(X)
+# yhat: unit quaternions, shape = (B, T_i, N, 4)
+```
+
 ### Known fixes
 
 #### Offscreen rendering with Mujoco

{imt_ring-1.6.3 → imt_ring-1.6.5}/src/ring/__init__.py

@@ -20,52 +20,55 @@ from .base import System
 from .base import Transform
 
 
-def RING(lam: list[int] | None, Ts: float | None, **kwargs):
+def RING(lam: list[int] | None, Ts: float | None, **kwargs) -> ml.AbstractFilter:
     """Creates the RING network.
 
     Params:
         lam: parent array, if `None` must be given via `ringnet.apply(..., lam=lam)`
         Ts : sampling interval of IMU data; time delta in seconds
 
-    Usage:
-    >>> import ring
-    >>> import numpy as np
-    >>>
-    >>> T  : int       = 30        # sequence length     [s]
-    >>> Ts : float     = 0.01      # sampling interval   [s]
-    >>> B  : int       = 1         # batch size
-    >>> lam: list[int] = [0, 1, 2] # parent array
-    >>> N  : int       = len(lam)  # number of bodies
-    >>> T_i: int       = int(T/Ts) # number of timesteps
-    >>>
-    >>> X = np.zeros((B, T_i, N, 9))
-    >>> # where X is structured as follows:
-    >>> # X[..., :3]  = acc
-    >>> # X[..., 3:6] = gyr
-    >>> # X[..., 6:9] = jointaxis
-    >>>
-    >>> # let's assume we have an IMU on each outer segment of the
-    >>> # three-segment kinematic chain
-    >>> X[:, :, 0, :3]  = acc_segment1
-    >>> X[:, :, 2, :3]  = acc_segment3
-    >>> X[:, :, 0, 3:6] = gyr_segment1
-    >>> X[:, :, 2, 3:6] = gyr_segment3
-    >>>
-    >>> ringnet = ring.RING(lam, Ts)
-    >>>
-    >>> yhat, _ = ringnet.apply(X)
-    >>> # yhat : unit quaternions, shape = (B, T_i, N, 4)
-    >>> # yhat[b, :, i] is the orientation from body `i` to parent body `lam[i]`
-    >>>
-    >>> # use `jax.jit` to compile the forward pass
-    >>> jit_apply = jax.jit(ringnet.apply)
-    >>> yhat, _ = jit_apply(X)
-    >>>
-    >>> # manually pass in and out the hidden state like so
-    >>> initial_state = None
-    >>> yhat, state = ringnet.apply(X, state=initial_state)
-    >>> # state: final hidden state, shape = (B, N, 2*H)
-
+    Returns:
+        ring.ml.AbstractFilter: An instantiation of `ring.ml.ringnet.RING` with trained
+            parameters.
+
+    Examples:
+        >>> import ring
+        >>> import numpy as np
+        >>>
+        >>> T  : int       = 30        # sequence length     [s]
+        >>> Ts : float     = 0.01      # sampling interval   [s]
+        >>> B  : int       = 1         # batch size
+        >>> lam: list[int] = [0, 1, 2] # parent array
+        >>> N  : int       = len(lam)  # number of bodies
+        >>> T_i: int       = int(T/Ts) # number of timesteps
+        >>>
+        >>> X = np.zeros((B, T_i, N, 9))
+        >>> # where X is structured as follows:
+        >>> # X[..., :3]  = acc
+        >>> # X[..., 3:6] = gyr
+        >>> # X[..., 6:9] = jointaxis
+        >>>
+        >>> # let's assume we have an IMU on each outer segment of the
+        >>> # three-segment kinematic chain
+        >>> X[:, :, 0, :3]  = acc_segment1
+        >>> X[:, :, 2, :3]  = acc_segment3
+        >>> X[:, :, 0, 3:6] = gyr_segment1
+        >>> X[:, :, 2, 3:6] = gyr_segment3
+        >>>
+        >>> ringnet = ring.RING(lam, Ts)
+        >>>
+        >>> yhat, _ = ringnet.apply(X)
+        >>> # yhat : unit quaternions, shape = (B, T_i, N, 4)
+        >>> # yhat[b, :, i] is the orientation from body `i` to parent body `lam[i]`
+        >>>
+        >>> # use `jax.jit` to compile the forward pass
+        >>> jit_apply = jax.jit(ringnet.apply)
+        >>> yhat, _ = jit_apply(X)
+        >>>
+        >>> # manually pass in and out the hidden state like so
+        >>> initial_state = None
+        >>> yhat, state = ringnet.apply(X, state=initial_state)
+        >>> # state: final hidden state, shape = (B, N, 2*H)
     """
     from pathlib import Path
     import warnings

{imt_ring-1.6.3 → imt_ring-1.6.5}/src/ring/algorithms/dynamics.py

@@ -303,6 +303,7 @@ def step(
     taus: Optional[jax.Array] = None,
     n_substeps: int = 1,
 ) -> base.State:
+    "Steps the dynamics. Returns the state of next timestep."
     assert sys.q_size() == state.q.size
     if taus is None:
         taus = jnp.zeros_like(state.qd)

{imt_ring-1.6.3 → imt_ring-1.6.5}/src/ring/algorithms/generator/base.py

@@ -4,6 +4,7 @@ import warnings
 
 import jax
 import jax.numpy as jnp
+import numpy as np
 import tree_utils
 
 from ring import base
@@ -47,6 +48,7 @@ class RCMG:
         cor: bool = False,
         disable_tqdm: bool = False,
     ) -> None:
+        "Random Chain Motion Generator"
 
         sys, config = utils.to_list(sys), utils.to_list(config)
         sys_ml = sys[0] if sys_ml is None else sys_ml
@@ -141,7 +143,9 @@ class RCMG:
 
         return n_calls
 
-    def to_list(self, sizes: int | list[int] = 1, seed: int = 1):
+    def to_list(
+        self, sizes: int | list[int] = 1, seed: int = 1
+    ) -> list[tree_utils.PyTree[np.ndarray]]:
         "Returns list of unbatched sequences as numpy arrays."
         repeats = self._compute_repeats(sizes)
         sizes = list(jnp.array(repeats) * jnp.array(self._size_of_generators))
@@ -170,7 +174,7 @@ class RCMG:
         seed: int = 1,
         overwrite: bool = True,
     ) -> None:
-        data = tree_utils.tree_batch(self.to_list(sizes, seed))
+        data = tree_utils.tree_batch(self.to_list(sizes, seed), backend="numpy")
         utils.pickle_save(data, path, overwrite=overwrite)
 
     def to_eager_gen(

{imt_ring-1.6.3 → imt_ring-1.6.5}/src/ring/base.py

@@ -113,7 +113,9 @@ class _Base:
 class Transform(_Base):
     """Represents the Transformation from Plücker A to Plücker B,
     where B is located relative to A at `pos` in frame A and `rot` is the
-    relative quaternion from A to B."""
+    relative quaternion from A to B.
+    Create using `Transform.create(pos=..., rot=...)
+    """
 
     pos: Vector
     rot: Quaternion
@@ -399,6 +401,7 @@ QD_WIDTHS = {
 
 @struct.dataclass
 class System(_Base):
+    "System object. Create using `System.create(path_xml)`"
     link_parents: list[int] = struct.field(False)
     links: Link
     link_types: list[str] = struct.field(False)

{imt_ring-1.6.3 → imt_ring-1.6.5}/src/ring/ml/ringnet.py

@@ -200,6 +200,7 @@ class RING(ml_base.AbstractFilter):
         forward_factory=make_ring,
         **kwargs,
     ):
+        "Untrained RING network"
         self.forward_lam_factory = partial(forward_factory, **kwargs)
         self.params = self._load_params(params)
         self.lam = lam

{imt_ring-1.6.3 → imt_ring-1.6.5}/src/ring/utils/utils.py

@@ -210,8 +210,9 @@ def replace_elements_w_nans(
         if _is_nan(ele, i):
             while True:
                 j = random.choice(include_elements)
-                if not _is_nan(list_of_data[j], j):
-                    ele = list_of_data[j]
+                ele_j = list_of_data[j]
+                if not _is_nan(ele_j, j):
+                    ele = pytree_deepcopy(ele_j)
                     break
         list_of_data_nonan.append(ele)
     return list_of_data_nonan