Reforge Cloud Identification API Reference (Internal)

process_calibration_data.py

process_calibration_data / ProcessCalibrationData bindings

Loads identification data, generates calibration maps, and trains map-fitting neural nets. Maps are saved under the data folder; trained models are stored in models/<robot_name>_robot_predictor_<ctrl_config>_numAxes<axes>. Returns the count of calibration maps processed.

:param data_path: Root folder containing identification CSV/NPY/NPZ files.
:param poses: Number of polar poses executed during identification.
:param axes: Number of commanded axes per pose.
:optional param robot_name: Robot identifier used for map/model filenames; defaults to "test".
:optional param file_format: Data file type ("csv", "npz", "npy"); defaults to "csv".
:optional param num_joints: Number of joints in the robot; defaults to 6.
:optional param min_freq: Lowest excitation frequency [Hz]; defaults to 0.5.
:optional param max_freq: Highest excitation frequency [Hz]; defaults to 20.0.
:optional param freq_space: Frequency spacing [Hz]; defaults to 0.5.
:optional param max_disp: Maximum sine stroke [rad]; defaults to pi/36.
:optional param dwell: Dwell time between sweeps [s]; defaults to 0.0.
:optional param Ts: Sampling period [s]; defaults to 0.004.
:optional param sysid_type: System ID mode ("sine" implemented; "bcb" throws); defaults to "sine".
:optional param ctrl_config: Controller configuration ("joint"|"task"); defaults to "joint".
:optional param max_acc: Maximum acceleration limit [rad/s^2]; defaults to 2.0.
:optional param max_vel: Maximum velocity limit [rad/s]; defaults to 18.0.
:optional param sine_cycles: Sine cycles per frequency; defaults to 5.
:optional param sensor: Output sensor used ("ToolAcc"|"JointPos"); defaults to "ToolAcc".
:optional param start_pose: Starting pose index (useful when resuming); defaults to 0.
:optional param max_map_size: Maximum poses per saved calibration map chunk; defaults to 12.
:optional param saved_maps: If True, skip generation and load existing .npz/.pkl maps from disk.
:optional param fine_tune: If True, stop after writing calibration maps (no model training).
:returns: Integer count of calibration maps processed.

ProcessCalibrationDataCLI(args: List[str]) -> int

Convenience wrapper to parse CLI arguments (same as process_calibration_data) and execute processing.

def generate_calibration_models(cloud_folder: str, fine_tune: bool = False) -> str

Python helper that reads identification_parameters.csv in a cloud data folder, infers run settings, and calls process_calibration_data. Returns the cloud models folder path provided by the binding.

:param cloud_folder: Cloud folder that contains identification_parameters.csv and calibration data.
:optional param fine_tune: If True, only build calibration maps for fine-tuning and skip training.

SineSweepReader class

def init(data_folder: str, num_poses: int, num_axes: int, robot_name: str, data_format: str, num_joints: int, min_freq: float, max_freq: float, freq_space: float, max_disp: float, dwell: float, Ts: float, ctrl_config: str, max_acc: float, max_vel: float, sine_cycles: int, max_map_size: int)

Prepares a reader for sine-sweep identification datasets (CSV/NPY/NPZ). Stores the run configuration used when generating maps.

def get_calibration_maps() -> List[str]

Generates calibration maps by segmenting sine sweeps, extracting dynamics via MapGeneration, and saving per-batch .npz maps. Returns the saved map file paths.

def reset_calibration_maps() -> None

Clears any cached map paths prior to regeneration.

def compute_num_maps() -> int

Computes how many map files will be produced based on poses and max_map_size.

def parse_data(filename: str) -> List[List[float]]

Lightweight CSV parser that returns numeric rows for test/utility usage.

def load_csv(filename: str) -> numpy.ndarray

Loads a CSV file into an Eigen/numpy matrix for downstream processing.

def load_npz(filename: str) -> Dict[str, numpy.ndarray]

Reads a .npz archive and returns a dict of arrays by key name.

def load_npy(filename: str) -> numpy.ndarray

Loads a single .npy array file into an Eigen/numpy matrix.

MapGeneration module

CalibrationMap class

def init(num_positions: int, axes_commanded: int, num_joints: int)

Allocates storage for pose/axis dynamics parameters and trainer features.

def generateCalibrationMap(robot_input: numpy.ndarray, robot_output: numpy.ndarray, input_Ts: float, output_Ts: float, max_freq_fit: float = 15.0, gravity_comp: bool = False, shift_store_position: int = 0) -> None

Fits transfer functions in the frequency domain for a full dataset and stores mode parameters and features into the map.

:param robot_input: Input joint commands.
:param robot_output: Measured outputs (e.g., accelerations).
:param input_Ts: Input sampling time [s].
:param output_Ts: Output sampling time [s].
:optional param max_freq_fit: Maximum frequency to fit [Hz].
:optional param gravity_comp: Whether to enable gravity compensation.
:optional param shift_store_position: Row offset when storing results.

def generate_from_pose(q_cmd: numpy.ndarray, tcp_acc: numpy.ndarray, input_Ts: float, output_Ts: float, segments: List[Tuple[int, int]], freq_cmd: List[float], robot_model, V_angle: float = 0.0, R_radius: float = 0.0, axis_commanded: int = 1, q0: List[float] = [], max_freq_fit: float = 15.0, gravity_comp: bool = False, store_row: int = 0, store_axis: int = 0) -> None

Processes a single pose/axis sine sweep: trims transient samples, computes FFTs, fits transfer functions, and stores primary/secondary mode parameters plus features (V, R, inertia) into the map.

:param q_cmd: Commanded joint positions [N x num_joints].
:param tcp_acc: TCP accelerations [N x 3].
:param input_Ts: Input sampling time [s].
:param output_Ts: Output sampling time [s].
:param segments: (start, end) indices for each sine segment.
:param freq_cmd: Commanded frequencies per segment [Hz].
:param robot_model: Python Dynamics model used for inertia/feature computation.
:param V_angle: Joint angle (radians) for the pose.
:param R_radius: Polar radius (meters) for the pose.
:param axis_commanded: 1-based axis index being excited.
:param q0: Initial joint configuration.
:optional param max_freq_fit: Maximum frequency to fit [Hz].
:optional param gravity_comp: Whether to enable gravity compensation.
:optional param store_row: Row index in the map to populate.
:optional param store_axis: Axis index in the map to populate.

Properties

allWn / allZeta / allWn2 / allZeta2: Pose-by-axis matrices of primary/secondary natural frequencies and damping ratios.
allInertia / allV / allR: Feature matrices of inertia, joint angle (rad), and radius (m).
sineSweepNumerators / sineSweepDenominators: Per-pose/axis transfer function coefficients captured during fitting.

def save_map(filename: str) -> None

Saves the calibration map in a binary format for legacy compatibility.

def load_map(filename: str) -> CalibrationMap

Static loader for binary calibration map files.

def save_npz(filename: str) -> None

Exports map data to a NumPy .npz archive for Python tooling.

def load_npz(filename: str) -> CalibrationMap

Static loader for .npz calibration maps.

MapFitter module

MapFitter class

def init(axes: int, input_features: int, hidden: List[int])

Creates per-axis ShaperNet models for predicting dynamics modes from features.

def train(features: List[Tensor], modes: List[Tensor], orders: List[Tensor], masks: List[Tensor], epochs: int = 200, lr: float = 1e-3) -> None

Trains one network per axis using BCE on order (second-mode present) and masked MSE on mode parameters.

:param features: Per-axis tensors shaped [N, 3] with [V_deg, R_mm, inertia].
:param modes: Per-axis tensors shaped [N, 4] with [wn1, lnζ1, wn2_or_0, lnζ2_or_0].
:param orders: Per-axis binary tensors [N, 1] flagging presence of a second mode.
:param masks: Per-axis tensors [N, 4] indicating valid elements in modes.
:optional param epochs: Training epochs per axis.
:optional param lr: Adam learning rate.

def infer(axis: int, feature: Tensor) -> Tuple[Tensor, Tensor]

Runs inference for a single axis, returning (order_prob, mode_params).

def infer_batch(features: Tensor) -> Tuple[Tensor, Tensor]

Runs batched inference across all axes. Expects features shaped [axes, 3]; returns stacked order probabilities [axes, 1] and mode parameters [axes, 4].

def save_models(directory: str) -> None

Writes per-axis PyTorch checkpoints (axisN_model.pt) to the target directory.

def load_models(directory: str) -> None

Loads saved model weights from a directory of axisN_model.pt files.

ModelLoader class

def load(directory: str, axes: int, input_features: int, hidden: List[int]) -> MapFitter

Constructs a MapFitter and loads weights from disk for immediate inference.

NPZMapLoader module

def LoadNPZTensorsFromNPZ(map_files: List[str], axes: int) -> LegacyTensors

Converts CalibrationMap .npz files (from save_npz) into per-axis tensors compatible with MapFitter training. Extracts features, targets, classification orders, and masks, generating dummy rows when an axis has no samples.

fine_tune_model.py

fine_tune_model / FineTuneModelGen bindings

Fine-tunes existing shaper models with additional calibration maps (.pkl or .npz). Loads models, builds training tensors from maps, runs extra epochs, and saves updated weights (default: fine_tuned_map).

:param model_file: Directory containing existing axisN_model.pt files.
:param maps: List of calibration map files to use for fine-tuning.
:optional param epochs: Number of fine-tuning epochs; defaults to 50 in the binding.
:optional param lr: Learning rate; defaults to 1e-4 in the binding.
:optional param save_file: Output directory for updated models; defaults to "fine_tuned_map".

def generate_fine_tuned_model(current_model_file: str, models_cloud_folder: str) -> str

Python helper that discovers map files under <models_cloud_folder>/maps, runs fine_tune_model, and saves updated models to <models_cloud_folder>/models. Returns the models folder path.