Skip to content

Releases: sigmapointlabs/se3-ad-recipes

Release list

se3-ad-recipes v1.0.0

se3-ad-recipes v1.0.0 Latest
Latest

Choose a tag to compare

View all tags
@fkuehnel fkuehnel released this 17 Jun 02:14
v1.0.0
1ec3e0c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

se3-ad-recipes v1.0.0 🎉

The first SemVer-stable release.

This release recasts the public surface around a curated, opaque-typed API — so you get safe-by-construction group types and a clear stability contract — while keeping the raw, paper-aligned modules around for reproducibility.

✨ Highlights

A three-tier API with explicit stability guarantees

Pick the highest tier that meets your needs:

Tier Modules Scalar Stability
Application api::{pose, extended_pose, quaternion_pose, rotation, types} f64 SemVer-stable; breaking changes are rare and major-only
Expert api::expert::{so3, se3, se23, quat_se3, projective, linalg, types, ad} generic T: AD Standard SemVer (additions minor, renames/removals major)
Raw so3_adsafe, se3_adsafe, … generic T: AD No promise — escape hatch only

Opaque group types you can't misuse

Pose, ExtendedPose, and QuatPose enforce their invariants (RᵀR = I, det R = +1, unit-norm quaternions) so the API simply can't produce an invalid value.

use se3_ad_recipes::prelude::*;

let pose = Pose::exp(&[0.0, 0.0, 0.1, 1.0, 0.0, 0.0]);

let world = pose.act(&[0.5, 0.0, 0.0]);

let jac = right_point_action_jacobian(&pose, &[0.5, 0.0, 0.0]);

  • Validated ingestion — from_rotation_translation checks orthogonality, determinant, and finiteness.
  • Trust-me path — from_parts_unchecked skips the check when you have an independent guarantee.

New higher-order derivative entry points (expert tier)

  • se3::right_jacobian_derivative — the full [Mat6G<T>; 6] derivative tensor.
  • se3::right_jacobian_directional_derivative — one contracted 6×6 slice, ideal for Hessian-vector products.
  • Companion inverse variants for both.

➕ Also added

  • prelude sized to the most common NLS-loop call sites — without flooding your namespace.
  • Optional serde feature (off by default) with stable, opaque on-disk shapes that deserialize through the validated constructors — so bad data can't yield a bad pose.
  • const fn identity constructors for all three pose types.
  • #[must_use] on pose types and value-returning functions.
  • #[non_exhaustive] on every error enum, so future variants ship in minor releases.
  • rust-version = "1.85" declared, matching edition = "2024".

🔧 Changed

  • Raw paper-aligned modules are now #[doc(hidden)] — still pub for source compatibility, just out of the generated docs.
  • The application tier owns the canonical fixed-size type aliases; crate::Mat3 & friends are now doc-hidden re-exports.
  • The criterion bench is gated behind the new bench-support feature, removing it from the default consumer surface.

🗑️ Removed

  • No public-surface removals. Redundant method+free-function pairs from earlier in the cycle never shipped; the method form is canonical.

📖 Stability commitment

Both the application and expert tiers are SemVer-stable. The application tier holds the stricter contract — breaking changes there should be exceptionally rare and well-motivated. Raw modules carry no stability promise and exist only as an escape hatch.

See the api module's rustdoc for the full contract.

Assets 2
Loading

v0.1.0 — Initial release (arXiv:2605.02252)

v0.1.0 — Initial release (arXiv:2605.02252)

Choose a tag to compare

View all tags
@fkuehnel fkuehnel released this 08 May 02:16
v0.1.0
41adeec

First tagged release of the SE(3) AD recipes. This version reproduces Table I of the companion paper "Exact Higher-Order Derivatives for SE(3) via Analytical/AD Methods" (arXiv:2605.02252).

What's included

  • Eight independent ways to compute the same 6×6 SE(3) NLL Hessian, benchmarked end-to-end against a nested-AD oracle.
  • AD-safe SO(3) / SE(3) primitives via the s = θ² recipe and fused scalar atoms (β̄, D̃, β̄', cos(θ/2), sin(θ/2)/θ).
  • The §IV.A polynomial-depletion trap and §IV.B singular-pair trap reproduced as failing tests, demonstrating exactly where naïve recipes break under nested AD.
  • Automatic forward-over-reverse Hessian via custom adr_n6 reverse tape — no analytical gradient required.

Reproducing Table I

cargo test --release --lib readme_table_i_is_up_to_date

The Time column is machine-dependent. Refresh it locally with:

UPDATE_README=1 cargo test --release --lib readme_table_i_is_up_to_date

Running the benchmark

cargo bench --bench nll_hessian -- --quick    # ~90 s
cargo bench --bench nll_hessian               # full criterion run, ~3 min

Citation

If you use this code, please cite the companion preprint:

@article{Kuehnel_2026,
  author = {Kuehnel, Frank O.},
  title  = {Exact Higher-Order Derivatives for SE(3) via Analytical/AD Methods},
  year   = {2026},
  doi    = {10.48550/arXiv.2605.02252},
  url    = {https://arxiv.org/abs/2605.02252}
}

Requirements

  • Rust 1.85+ (stable, edition 2024)
  • No runtime dependencies; criterion is the only dev-dependency

License

Dual-licensed under MIT or Apache-2.0 at your option.

Loading