Skip to content

Commit

Permalink
Major docs update
Browse files Browse the repository at this point in the history
  • Loading branch information
flferretti committed Oct 17, 2023
1 parent 4039df1 commit 2df8611
Show file tree
Hide file tree
Showing 17 changed files with 88 additions and 108 deletions.
34 changes: 30 additions & 4 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@
copyright = "2022, Artificial and Mechanical Intelligence"
author = "Artificial and Mechanical Intelligence"

release = "__version__"
version = "main (" + __version__ + ")"
release = f"{__version__}"
version = f"main ({__version__})"

# -- General configuration

Expand All @@ -33,11 +33,16 @@
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.intersphinx",
"sphinx_rtd_theme",
"sphinx_autodoc_typehints",
"sphinx.ext.mathjax",
"sphinx.ext.ifconfig",
"sphinx.ext.viewcode",
"sphinx_rtd_theme",
"sphinx.ext.napoleon",
"sphinx_autodoc_typehints",
"sphinx_multiversion",
# "sphinx_fontawesome",
# "breathe",
# "sphinx_tabs.tabs",
]

# -- Options for intersphinx extension
Expand All @@ -50,6 +55,27 @@

exclude_patterns = ["_build"]

autodoc_typehints = "signature"

# autodoc_default_options = {
# "members": True,
# "undoc-members": True,
# "member-order": "bysource",
# }

# # Napoleon settings
# napoleon_google_docstring = True
# napoleon_numpy_docstring = True
# napoleon_include_init_with_doc = False
# napoleon_include_private_with_doc = False
# napoleon_include_special_with_doc = False
# napoleon_use_admonition_for_examples = False
# napoleon_use_admonition_for_notes = False
# napoleon_use_admonition_for_references = False
# napoleon_use_ivar = True
# napoleon_use_param = True
# napoleon_use_rtype = True

# -- Options for HTML output

html_theme = "sphinx_rtd_theme"
Expand Down
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Planned features:
modules/parsers
modules/simulation
modules/utils
modules/typing


Credits
Expand Down
4 changes: 0 additions & 4 deletions docs/modules/parsers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,12 @@ Parsers

.. automodule:: jaxsim.parsers.descriptions.collision
:members:
:inherited-members:

.. automodule:: jaxsim.parsers.descriptions.joint
:members:
:inherited-members:

.. automodule:: jaxsim.parsers.descriptions.link
:members:
:inherited-members:

.. automodule:: jaxsim.parsers.descriptions.model
:members:
:inherited-members:
3 changes: 2 additions & 1 deletion docs/modules/physics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ Algos
.. autofunction:: jaxsim.physics.algos.aba.aba

.. autofunction:: jaxsim.physics.algos.crba.crba


.. autofunction:: jaxsim.physics.algos.forward_kinematics.forward_kinematics

Expand All @@ -34,6 +33,8 @@ Algos
:members:
:inherited-members:

.. _model:

Model
-----

Expand Down
35 changes: 35 additions & 0 deletions docs/modules/typing.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
.. _typing:


Typing
======

.. autoclass:: jaxsim.typing.PyTree
:undoc-members:

.. autoclass:: jaxsim.typing.Tensor
:undoc-members:

.. autoclass:: jaxsim.typing.Matrix
:undoc-members:

.. autoclass:: jaxsim.typing.Bool

.. autoclass:: jaxsim.typing.Int

.. autoclass:: jaxsim.typing.Float

.. autoclass:: jaxsim.typing.Vector
:undoc-members:

.. autoclass:: jaxsim.typing.FloatJax

.. autoclass:: jaxsim.typing.IntJax

.. autoclass:: jaxsim.typing.ArrayJax

.. autoclass:: jaxsim.typing.TensorJax

.. autoclass:: jaxsim.typing.VectorJax

.. autoclass:: jaxsim.typing.MatrixJax
6 changes: 5 additions & 1 deletion docs/modules/utils.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,8 @@ Utils

.. automodule:: jaxsim.utils
:members:
:inherited-members:
:inherited-members:

.. autoclass:: jaxsim.utils.JaxsimDataclass
:members:
:inherited-members:
8 changes: 0 additions & 8 deletions src/jaxsim/math/skew.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,6 @@
class Skew:
"""
A utility class for skew-symmetric matrix operations.
Methods:
wedge(vector: jtp.Vector) -> jtp.Matrix:
Compute the skew-symmetric matrix (wedge operator) of a 3D vector.
vee(matrix: jtp.Matrix) -> jtp.Vector:
Extract the 3D vector from a skew-symmetric matrix (vee operator).
"""

@staticmethod
Expand Down
4 changes: 2 additions & 2 deletions src/jaxsim/parsers/descriptions/joint.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ class JointType(enum.IntEnum):
"""
Enumeration of joint types for robot joints.
Attributes:
Args:
F: Fixed joint (no movement).
R: Revolute joint (rotation).
P: Prismatic joint (translation).
Expand Down Expand Up @@ -44,7 +44,7 @@ class JointDescriptor:
"""
Description of a joint type with a specific code.
Attributes:
Args:
code (JointType): The code representing the joint type.
"""
Expand Down
5 changes: 0 additions & 5 deletions src/jaxsim/parsers/descriptions/link.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,6 @@ class LinkDescription(JaxsimDataclass):
parent (Optional[LinkDescription]): The parent link of this link.
pose (jtp.Matrix): The pose transformation matrix of the link.
children (List[LinkDescription]): List of child links.
Methods:
lump_with(link: LinkDescription, lumped_H_removed: jtp.Matrix) -> LinkDescription:
Combine the current link with another link, preserving mass and inertia.
"""

name: Static[str]
Expand Down
7 changes: 0 additions & 7 deletions src/jaxsim/parsers/descriptions/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,6 @@ class ModelDescription(KinematicGraph):
name (str): The name of the model.
fixed_base (bool): Indicates whether the model has a fixed base.
collision_shapes (List[CollisionShape]): List of collision shapes associated with the model.
Methods:
build_model_from(...): Build a model description from provided components.
reduce(...): Reduce the model by removing specified joints.
update_collision_shape_of_link(...): Enable or disable collision shapes associated with a link.
collision_shape_of_link(...): Get the collision shape associated with a specific link.
all_enabled_collidable_points(...): Get all enabled collidable points in the model.
"""

name: str = None
Expand Down
16 changes: 9 additions & 7 deletions src/jaxsim/physics/algos/aba.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
from __future__ import annotations

from typing import Tuple

import jax
Expand All @@ -24,15 +26,15 @@ def aba(
Articulated Body Algorithm (ABA) algorithm for forward dynamics.
Args:
model (PhysicsModel): The physics model of the articulated body or robot.
xfb (jtp.Vector): The floating base state vector containing quaternion (4D) and position (3D).
q (jtp.Vector): Joint positions (Generalized coordinates).
qd (jtp.Vector): Joint velocities.
tau (jtp.Vector): Joint torques or forces.
f_ext (jtp.Matrix, optional): External forces and torques acting on each link. Defaults to None.
model: The physics model of the articulated body or robot.
xfb: The floating base state vector containing quaternion (4D) and position (3D).
q: Joint positions (Generalized coordinates).
qd: Joint velocities.
tau: Joint torques or forces.
f_ext: External forces and torques acting on each link. Defaults to None.
Returns:
Tuple[jtp.Vector, jtp.Vector]: A tuple containing the resulting base acceleration (in inertial-fixed representation)
A tuple containing the resulting base acceleration (in inertial-fixed representation)
and joint accelerations.
Note:
Expand Down
10 changes: 0 additions & 10 deletions src/jaxsim/physics/algos/soft_contacts.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,6 @@ class SoftContactsState:
Attributes:
tangential_deformation (jtp.Matrix): The tangential deformation of the material at each collidable point.
Methods:
zero(physics_model: "jaxsim.physics.model.physics_model.PhysicsModel") -> SoftContactsState:
Modify the SoftContactsState instance imposing zero tangential deformation.
valid(physics_model: "jaxsim.physics.model.physics_model.PhysicsModel") -> bool:
Check if the soft contacts state has valid shape.
replace(validate: bool = True, kwargs) -> SoftContactsState:
Replace attributes of the soft contacts state.
"""

tangential_deformation: jtp.Matrix
Expand Down
5 changes: 0 additions & 5 deletions src/jaxsim/physics/model/ground_contact.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,6 @@ class GroundContact:
Attributes:
point (npt.NDArray): An array of shape (3, N) representing the 3D positions of collidable points.
body (Static[npt.NDArray]): An array of integers representing the indices of the bodies (links) associated with each collidable point.
Methods:
build_from(model_description: ModelDescription) -> GroundContact:
A static method to build a GroundContact object from a ModelDescription instance.
It extracts collidable points' positions and their associated bodies from the model description.
"""

point: npt.NDArray = dataclasses.field(default_factory=lambda: jnp.array([]))
Expand Down
34 changes: 0 additions & 34 deletions src/jaxsim/physics/model/physics_model.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,40 +34,6 @@ class PhysicsModel(JaxsimDataclass):
is_floating_base (Static[bool]): A flag indicating whether the model has a floating base (default: False).
gc (GroundContact): The ground contact points of the model (default: empty GroundContact instance).
description (Static[jaxsim.parsers.descriptions.model.ModelDescription]): A description of the model (default: None).
Methods:
build_from(
model_description: jaxsim.parsers.descriptions.model.ModelDescription,
gravity: jtp.Vector = default_gravity()
) -> PhysicsModel:
Create a PhysicsModel instance from a model description and gravity vector.
dofs() -> int:
Get the number of degrees of freedom (DOFs) in the model.
set_gravity(gravity: jtp.Vector) -> None:
Set the gravity vector for the model.
parent_array() -> jtp.Vector:
Get the parent array (λ(i)) for the model.
support_body_array(body_index: jtp.Int) -> jtp.Vector:
Get an array of body indices (κ(i)) that support the specified body.
tree_transforms() -> jtp.Array:
Get an array of tree transforms (pre(i)_X_λ(i)) for all bodies.
spatial_inertias() -> jtp.Array:
Get an array of spatial inertias (M_links) for all bodies.
jtype(joint_index: int) -> JointType:
Get the joint type for the specified joint index.
joint_transforms(q: jtp.Vector) -> jtp.Array:
Compute joint transforms (Xj) for the given joint positions (q).
motion_subspaces(q: jtp.Vector) -> jtp.Array:
Compute motion subspaces (SS) for the given joint positions (q).
"""

NB: Static[int]
Expand Down
17 changes: 0 additions & 17 deletions src/jaxsim/physics/model/physics_model_state.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,23 +21,6 @@ class PhysicsModelState(JaxsimDataclass):
base_quaternion (jtp.Vector): An array representing the base quaternion (default: [1.0, 0, 0, 0]).
base_linear_velocity (jtp.Vector): An array representing the base linear velocity (default: zeros).
base_angular_velocity (jtp.Vector): An array representing the base angular velocity (default: zeros).
Methods:
zero(physics_model: "jaxsim.physics.model.physics_model.PhysicsModel") -> PhysicsModelState:
Create a zero-initialized PhysicsModelState for the given physics model.
position() -> jtp.Vector:
Get the full state vector, including joint positions, joint velocities, base position, and base quaternion.
velocity() -> jtp.Vector:
Get the full velocity vector, including base linear velocity, base angular velocity, and joint velocities.
xfb() -> jtp.Vector:
Get the full state vector in the "xfb" format, which includes base quaternion, base position, base angular
velocity, and base linear velocity.
valid(physics_model: "jaxsim.physics.model.physics_model.PhysicsModel") -> bool:
Check if the state has valid shapes for the given physics model.
"""

# Joint state
Expand Down
6 changes: 4 additions & 2 deletions src/jaxsim/simulation/simulator.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
from __future__ import annotations

import dataclasses
import functools
import pathlib
Expand Down Expand Up @@ -389,9 +391,9 @@ def step(self, clear_inputs: bool = False) -> Dict[str, StepData]:
def step_over_horizon(
self,
horizon_steps: jtp.Int,
callback_handler: Union["scb.SimulatorCallback", "scb.CallbackHandler"] = None,
callback_handler: Union[scb.SimulatorCallback, scb.CallbackHandler] = None,
clear_inputs: jtp.Bool = False,
) -> Union["JaxSim", Tuple["JaxSim", Tuple["scb.SimulatorCallback", jtp.PyTree]]]:
) -> Union[JaxSim, Tuple[JaxSim, Tuple[scb.SimulatorCallback, jtp.PyTree]]]:
"""
Advance the simulation by a given number of steps.
Expand Down
1 change: 0 additions & 1 deletion src/jaxsim/typing.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
from typing import Any, Dict, Hashable, List, NamedTuple, Tuple, Union

import jax.numpy as jnp
import numpy as np
import numpy.typing as npt
Expand Down

0 comments on commit 2df8611

Please sign in to comment.