FAQ & Troubleshooting¶

Installation¶

`pip install figaroh` fails to build, or optimization scripts complain about missing solvers¶

Optimal configuration/trajectory generation uses cyipopt (a wrapper around the IPOPT solver), which needs system libraries that aren't pulled in by pip alone:

# Debian/Ubuntu
sudo apt-get install -y pkg-config coinor-libipopt-dev libblas-dev liblapack-dev
pip install cyipopt picos cvxpy

If you use conda, some robotics dependencies are easier to get from conda-forge:

conda install -c conda-forge pinocchio cyipopt

Do I need MuJoCo, Genesis, or Isaac Sim installed?¶

No — Pinocchio is the only always-available backend and FIGAROH's core algorithms don't require the others. Install mujoco, genesis-world, or Isaac Sim only if you actually want that backend; figaroh.backends.list_backends() reports what's currently available in your environment.

Configuration¶

What happened to the legacy flat format?¶

It was removed in 1.0; use the unified format — it supports extends: template inheritance, so a robot config only states what's actually robot-specific. Loading an old flat config raises an error naming the converter, python -m figaroh.utils.config_migration. The examples in figaroh-examples all use the unified format.

My robot config isn't picking up template defaults¶

Check that extends: is a path relative to the config file itself, not the working directory — e.g. extends: "../../templates/manipulator_robot.yaml" from examples/my_robot/config/. Also remember list-valued keys (like markers) are replaced, not merged, when both the template and the robot config define them — see override rules.

Calibration & Identification¶

Calibration/identification isn't converging¶

Check your initial parameter guesses and joint limits in the config first — most non-convergence traces back to a bad initial guess or an over-constrained problem, not the solver itself.

My calibration fits the training postures well but predicts new postures badly¶

Usually too many parameters for what the postures excite: estimating weakly excited corrections freely fits noise. Check the number of measurements per estimated parameter, then try an estimation method that accounts for excitation (excitation, map, map_cv, cv_subset) and compare them on held-out postures. See Choosing what to estimate.

The calibrated parameter set differs between my laptop and CI¶

With the default structural method, ties in the structural QR are broken by floating-point details, so the selected parameters can differ between platforms (figaroh-plus#113). The non-structural methods select on the measured postures in a fixed order; map and map_cv select nothing. See Calibration estimation methods.

Identification results have high uncertainty or fail `verify()`¶

This is almost always a data-quality problem, not an algorithm problem:

Was the trajectory actually "exciting"? See Optimal Experiment Design — an ill-conditioned trajectory will identify poorly no matter how good the solver is.
Is the signal-to-noise ratio adequate? Try enabling decimate=True or tightening the Butterworth cutoff frequency in signal_processing.
Do you have a genuinely held-out validation_data_file configured? A run with no validation data skips (not fails) the validation-based checks in verify() — see thresholds.

Why did a metric get skipped instead of failed in my verification report?¶

A threshold whose metric can't be computed — typically because no validation_data_file is configured — is skipped rather than counted as a failure. An empty check list counts as passed since there's nothing to fail on. See Reporting & Verification.

Examples¶

Where are the runnable robot examples?¶

In the separate figaroh-examples repository, not in this one — see the Examples Gallery. figaroh (this repo) is the library; figaroh-examples has the data, URDFs, and per-robot scripts.

How do I add support for a new robot?¶

Scaffold it from the TIAGo example:

cd figaroh-examples/examples
./create_example.sh <robot_name>

Then implement a BaseCalibration/BaseIdentification subclass under utils/, and point its config at the matching template.