Reforge Core SDK
Use the Reforge Core SDK on your robot.
reforge_core.calibration.api
ReforgeAPIManager class
Coordinate calibration data upload and model retrieval.
def __init__(reforge_api_token: str, robot_id: str) -> None
Initialize the API manager with credentials and robot identity.
Args:
reforge_api_token: API token for cloud authentication.
robot_id: Identifier for the robot.
Side Effects:
Stores credentials in the instance.
Raises:
None.
Preconditions:
`reforge_api_token` and `robot_id` are non-empty strings.
def upload_data_to_cloud(zip_file_path: str) -> tuple[str, float]
Upload zipped calibration data to the cloud and return the data handle.
Args:
zip_file_path: Path to a `.zip` file containing calibration data.
Returns:
`tuple[str, float]` containing:
- data_id returned by the cloud upload endpoint
- upload duration in seconds
Raises:
FileNotFoundError: If `zip_file_path` does not exist.
ValueError: If `zip_file_path` is not a zip file or response is invalid.
RuntimeError: If request fails or the server returns an error.
def run_cloud_model_generation(data_folder: str, delete_temp_file: bool = False, fine_tune: bool = False) -> None
Run cloud identification/fine-tuning and save returned models locally.
Args:
data_folder: Path to calibration data folder (or zip) to upload.
delete_temp_file: If `True`, delete temporary zip created locally after upload.
fine_tune: If `True`, trigger fine-tuning job; otherwise trigger identification.
Returns:
`None`.
Side Effects:
Uploads data to cloud, creates and polls a remote job, downloads model artifact,
and writes extracted models to local storage.
Raises:
FileNotFoundError: If upload input cannot be found.
ValueError: If cloud payloads are missing required fields.
RuntimeError: If upload/job/download requests fail.
TimeoutError: If job does not complete within timeout.
OSError: If local file operations fail.
Preconditions:
`data_folder` exists and contains valid calibration data.
reforge_core.control.python.base_shaper
BaseShaper class
Shape scalar commands with a time-varying ZVD impulse response.
def __init__(Ts: float) -> None
Initialize the shaper state and history buffers.
Args:
Ts: Controller sampling period [s].
Returns:
`None`.
Side Effects:
Allocates internal buffers and stores shaper configuration.
Raises:
ValueError: If `Ts <= 0`.
Preconditions:
None.
def shape_sample(x_i: float, frf_params: np.ndarray) -> tuple[float, float, float]
Shape one sample and estimate shaped velocity and acceleration.
Args:
x_i: Raw command sample [joint unit].
frf_params: Modal parameters shaped `(m, 2)` as `[wn, zeta]` where
`wn` is in [rad/s] and `zeta` is unitless.
Returns:
`tuple[float, float, float]` containing `(y, y_dot, y_ddot)` in
`[joint unit]`, `[joint unit/s]`, and `[joint unit/s^2]`.
Side Effects:
Updates impulse response, input ring buffer, and derivative histories.
Raises:
ValueError: If `frf_params` is empty or not shaped `(m, 2)`.
Preconditions:
`frf_params` rows contain physically valid modal parameters.
def shape_trajectory(x: np.ndarray, varying_params: list[np.ndarray] | np.ndarray, *, reset: bool = True) -> tuple[np.ndarray, np.ndarray, np.ndarray]
Shape a full 1D trajectory using per-sample modal parameters.
Args:
x: Raw command trajectory of shape `(N,)` [joint unit].
varying_params: Either one `(m, 2)` array, one list entry `(m, 2)`, or
an `(N, m, 2)` array providing `[wn, zeta]` at each sample.
reset: Whether to reset internal state before processing.
Returns:
`tuple[np.ndarray, np.ndarray, np.ndarray]` as `(y, y_dot, y_ddot)`,
each shape `(N,)` in `[joint unit]`, `[joint unit/s]`, and `[joint unit/s^2]`.
Side Effects:
Mutates internal buffers unless `reset=False` continues an existing stream.
Raises:
ValueError: If trajectory or modal parameters are malformed.
Preconditions:
`x` is finite and modal parameters are physically valid.
def finalize() -> list[tuple[float, float, float]]
Flush delayed shaper output by holding the last raw command.
Args:
None.
Returns:
`list[tuple[float, float, float]]` delayed `(y, y_dot, y_ddot)` samples.
Side Effects:
Advances input/output history buffers.
Raises:
None.
Preconditions:
None.
def reset_state() -> None
Reset shaper state to a passthrough configuration.
Args:
None.
Returns:
`None`.
Side Effects:
Reinitializes impulse response and all signal/history buffers.
Raises:
None.
Preconditions:
None.
reforge_core.control.python.covalent_wrapper
Python implementation of the map-based shaper pipeline.
RobotState dataclass
Represent robot state required for shaper inference.
Args:
joint_angles: Joint angles `[num_joints]` in radians.
tcp_position: Optional tool center point position `[x, y, z]` in meters.
Side Effects:
None.
Raises:
None.
Preconditions:
Arrays are finite and ordered to match model joint/axis conventions.
ShapedSample dataclass
Hold shaped command values for a single control sample.
Args:
positions: Shaped joint positions `[num_joints]` in radians.
velocities: Shaped joint velocities `[num_joints]` in radians/s.
accelerations: Shaped joint accelerations `[num_joints]` in radians/s^2.
Side Effects:
None.
Raises:
None.
Preconditions:
Arrays align with the same joint ordering.
ShapedTrajectory dataclass
Store shaped trajectory arrays and time stamps.
Args:
positions: Shaped positions `[N, num_joints]` in radians.
velocities: Shaped velocities `[N, num_joints]` in radians/s.
accelerations: Shaped accelerations `[N, num_joints]` in radians/s^2.
time: Time vector `[N]` in seconds.
Side Effects:
None.
Raises:
None.
Preconditions:
All arrays share the same sample count `N`.
ShaperInterface class
Run map-based modal inference and apply per-axis input shaping.
def __init__(sample_time: float, model_directory: str, python_src_root: str, urdf_filepath: str, num_axes: int = 3, side_length: float = 0.0007, base_height: float = 0.364, num_joints: int = 6, prob_thresh: float = 0.5) -> None
Initialize model inference and per-axis shapers.
Args:
sample_time: Controller sample period [s].
model_directory: Directory containing `axis*_model.pt` files.
python_src_root: Source root path to add to import path.
urdf_filepath: URDF path for robot dynamics.
num_axes: Number of shaped axes.
side_length: Side-length geometry parameter [m].
base_height: Base-height geometry parameter [m].
num_joints: Number of robot joints.
prob_thresh: Threshold for two-mode shaper selection.
Returns:
`None`.
Side Effects:
Mutates `sys.path` and loads model/dynamics resources.
Raises:
ValueError: If dimensions or sample time are invalid.
Preconditions:
`urdf_filepath` and model files exist and are readable.
def reset() -> None
Reset internal shaper states and stream continuity markers.
Args:
None.
Returns:
`None`.
Side Effects:
Replaces per-axis shaper objects and clears stream cache.
Raises:
None.
Preconditions:
None.
def compute_forward_kinematics(joint_angles: np.ndarray) -> np.ndarray
Compute TCP position from joint angles.
Args:
joint_angles: Joint angles `[num_joints]` in radians.
Returns:
`np.ndarray` TCP position `[x, y, z]` in meters.
Side Effects:
None.
Raises:
RuntimeError: If dynamics backend forward kinematics fails.
Preconditions:
`joint_angles` matches model joint count.
def compute_inertia(joint_angles: np.ndarray) -> np.ndarray
Compute diagonal joint inertia terms from mass matrix.
Args:
joint_angles: Joint angles `[num_joints]` in radians.
Returns:
`np.ndarray` diagonal inertia terms `[num_joints]`.
Side Effects:
None.
Raises:
RuntimeError: If dynamics backend mass matrix calculation fails.
Preconditions:
`joint_angles` matches model joint count.
def cartesian_to_polar(xyz: np.ndarray) -> tuple[float, float]
Convert Cartesian TCP position into (v, r) map features.
Args:
xyz: Cartesian TCP coordinates `[x, y, z]` in meters.
Returns:
`tuple[float, float]` as `(v, r)` where `v` is angle [rad] and `r` is radius [m].
Side Effects:
None.
Raises:
ValueError: If `xyz` is not a 3-vector.
Preconditions:
`xyz` is finite.
def compute_nn_inputs(state: RobotState) -> tuple[float, float, np.ndarray]
Build map-network inputs from current robot state.
Args:
state: Current robot state.
Returns:
`tuple[float, float, np.ndarray]` as `(v_rad, r_m, inertia_vector)`.
Side Effects:
Prints one warning line when fallback base-rotation logic is used.
Raises:
RuntimeError: If dynamics calls fail and no fallback path can recover.
Preconditions:
`state.joint_angles` matches configured `num_joints`.
def shape_sample(command: np.ndarray, state: RobotState, command_dot: np.ndarray | None = None, command_ddot: np.ndarray | None = None) -> ShapedSample
Shape one command sample across all configured shaped axes.
Args:
command: Joint command `[num_joints]` in radians.
state: RobotState object for feature calculation.
command_dot: Optional command velocity `[num_joints]` in radians/s.
command_ddot: Optional command acceleration `[num_joints]` in radians/s^2.
Returns:
`ShapedSample` containing shaped position/velocity/acceleration vectors.
Side Effects:
Updates per-axis shaper state and stream cache.
Raises:
ValueError: If command vector shapes are invalid.
Preconditions:
Model inference backend is initialized.
def shape_trajectory(command: np.ndarray, states: list[RobotState], command_dot: np.ndarray | None = None, command_ddot: np.ndarray | None = None, time_vector: list[float] | None = None) -> ShapedTrajectory
Shape a full joint trajectory and append tail samples for delay flush.
Args:
command: Command trajectory `[N, num_joints]` in radians.
states: RobotState list length `N` or empty list for command-only shaping.
command_dot: Optional velocity trajectory `[N, num_joints]` in radians/s.
command_ddot: Optional acceleration trajectory `[N, num_joints]` in radians/s^2.
time_vector: Optional sample times `[N]` in seconds.
Returns:
`ShapedTrajectory` containing shaped outputs and final flush tail.
Side Effects:
Mutates shaper internal history and stream continuity cache.
Raises:
ValueError: If command/state/derivative shapes are inconsistent.
Preconditions:
Dynamics backend and map models are initialized.
reforge_core.control.covalent (C++ binding)
C++ backed shaper interface exposed as Python module covalent. If you want to use the compiled C++ controller (without a Python binding), please contact us.
RobotState struct
Robot state used for inference.
Properties:
joint_angles: Current joint configuration [rad] (1 x num_joints).
tcp_position: Optional TCP position [m] (1 x 3).
ShapedSample struct
Holds one shaped joint command.
Properties:
positions: Shaped joint positions [rad].
velocities: Shaped joint velocities [rad/s].
accelerations: Shaped joint accelerations [rad/s^2].
ShapedTrajectory struct
Holds a shaped trajectory with timing.
Properties:
positions: (num_samples, num_joints).
velocities: (num_samples, num_joints).
accelerations: (num_samples, num_joints).
time: Vector of sample timestamps [s].
ShaperInterface class
Run map-based modal inference and apply per-axis input shaping.
def __init__(sample_time: float, model_directory: str, python_src_root: str, urdf_filepath: str, side_length: float = NaN, base_height: float = NaN, num_axes: int = 0, num_joints: int = 0, prob_thresh: float = 0.5)
Construct and initialize the map-backed multi-axis shaper interface.
Args:
sample_time: Controller sample period [s].
model_directory: Directory containing per-axis NN model files.
python_src_root: Source root inserted into Python `sys.path`.
urdf_filepath: URDF path used to build dynamics metadata.
side_length: Optional geometry side-length [m]; `NaN` resolves from defaults.
base_height: Optional geometry base-height [m]; `NaN` resolves from defaults.
num_axes: Optional number of shaped axes; non-positive resolves from defaults.
num_joints: Optional number of robot joints; non-positive resolves from defaults.
prob_thresh: Threshold for selecting one-mode vs two-mode shaping.
Side Effects:
Initializes embedded Python usage, loads URDF-derived dynamics, and loads NN models.
Raises:
ValueError: If dimensions/sample time/URDF joint count are invalid.
RuntimeError: If dynamics or map model initialization fails.
Preconditions:
Model files and URDF are accessible from provided paths.
def shape_sample(command, state, command_dot=None, command_ddot=None) -> ShapedSample
Shape one joint command sample using map-inferred vibration modes.
Args:
command: Joint position command vector `[num_joints]` in radians.
state: RobotState object for feature extraction; may omit TCP position.
command_dot: Optional commanded joint velocity `[num_joints]` in rad/s.
command_ddot: Optional commanded joint acceleration `[num_joints]` in rad/s^2.
Returns:
`ShapedSample` containing shaped position, velocity, and acceleration vectors.
Side Effects:
Updates per-axis shaper state and cached last input vectors used for stream continuity.
Raises:
ValueError: If command or derivative vector lengths mismatch configuration.
Preconditions:
Interface has been initialized with valid dynamics and map models.
def shape_trajectory(command, states, command_dot=None, command_ddot=None, time_vector=None) -> ShapedTrajectory
Shape a full joint trajectory and append per-axis finalize tails.
Args:
command: Joint position trajectory `[N x num_joints]` in radians.
states: Optional per-sample RobotStates; when empty, states are derived from `command`.
command_dot: Optional velocity trajectory `[N x num_joints]` in rad/s.
command_ddot: Optional acceleration trajectory `[N x num_joints]` in rad/s^2.
time_vector: Optional sample timestamps `[N]` in seconds.
Returns:
`ShapedTrajectory` with shaped samples plus any appended delay-flush tail samples.
Side Effects:
May reset shapers when continuity checks fail; consumes finalize tails from each axis.
Raises:
ValueError: If trajectory/state/derivative/time dimensions are inconsistent.
Preconditions:
Trajectory has at least one row and `num_joints` columns.
def finalize() -> list[ShapedSample]
Finalize each axis shaper and return synchronized tail samples.
Args:
None.
Returns:
`std::vector<ShapedSample>` tail sequence after stream completion.
Side Effects:
Consumes per-axis shaper tail state.
Raises:
None.
Preconditions:
Shapers have been initialized.
def reset() -> None
Reset all per-axis shaper state and clear continuity markers.
Args:
None.
Returns:
None.
Side Effects:
Reconstructs each `BaseShaper` instance and clears cached last input vectors.
Raises:
None.
Preconditions:
Interface has been constructed.