klampt.math.autodiff.geometry_ad module

Klampt geometry AD functions:

Function	Derivative	Notes
BoxPointMargin	Y	margin[bmin,bmax](x) -> R
BoxPointDistance	1	D[bmin,bmax](x) -> R
BoxPointClosest	Y	CP[bmin,bmax](x) -> R^n
sphere_point_distance	Y	D(c,r,x) -> R
sphere_point_closest	Y	CP(c,r,x) -> R^n
sphere_sphere_distance	Y	D(c1,r1,c2,r2) -> R
sphere_sphere_closest	Y	CP(c1,r1,c2,r2) -> R^n
GeomPointDistance	1	D[geom](Tgeom,pt) -> R
GeomSphereDistance	1	D[geom](Tgeom,c,r) -> R
GeomPointClosest	1	CP[geom](Tgeom,pt) -> R^3
GeomGeomDistance	1	D[geom1,geom2](Tgeom1,Tgeom2) -> R
GeomGeomClosest	1	CPs[geom1,geom2](Tgeom1,Tgeom2) -> R^6
GeomRayCast	1	RC[geom](Tgeom,s,d) -> R
MinDistance	1	Faster than min XYDistance()

Note that all the GeomX functions’ derivatives should depend on the local shape of the geometry, but we don’t actually take that into account, so their analytical derivatives may not be accurate. For example, if the closest point to x on a triangle mesh lies on a vertex, then its derivative w.r.t. x is 0. If it lies on an edge, then it depends on the edge direction. If it lies on a face, then it depends on the face’s normal. Future versions may support such reasoning.

Classes:

BoxPointClosest(bmin, bmax)	Returns the closest point to x within the bounding box [bmin,bmax].
BoxPointDistance(bmin, bmax)	Returns the (signed) distance of a point x to a bounding box [bmin,bmax].
BoxPointMargin(bmin, bmax)	Returns the inner margin of a point x inside a bounding box [bmin,bmax].
GeomGeomDistance(geom1, geom2[, name1, …])	Autodiff wrapper of Geometry3D.distance.
GeomPointClosest(geom[, name])	Autodiff wrapper of Geometry3D.distance_point(x).cp1.
GeomPointDistance(geom[, name, relErr, …])	Autodiff wrapper of Geometry3D.distance_point.
GeomRayCast(geom[, name])	Autodiff wrapper of Geometry3D.rayCast.
GeomSphereDistance(geom[, name, relErr, …])	Autodiff wrapper of Geometry3D.distance_point(c)-r.
MinDistance(geometries[, pairs, names, …])	Autodiff function that is equivalent to minimum(D1(…),…,DM(…)) but is faster due to the use of upper bounding and order caching.

Functions:

sphere_point_closest(c, r, x)	Autodiff function CP(c,r,x) giving the closest point from a sphere with center c and radius r to a point x
sphere_point_distance(c, r, x)	Autodiff function D(c,r,x) giving the distance from a sphere with center c and radius r to a point x
sphere_sphere_closest(c1, r1, c2, r2)	Autodiff function CP(c1,r1,c2,r2)->R^2n giving the closest points between a sphere with center c1, radius r1 to a sphere with center c2, radius r2.
sphere_sphere_distance(c1, r1, c2, r2)	Autodiff function D(c1,r1,c2,r2) giving the distance from a sphere with center c1, radius r1 to a sphere with center c2, radius r2.

class klampt.math.autodiff.geometry_ad.BoxPointClosest(bmin, bmax)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Returns the closest point to x within the bounding box [bmin,bmax].

Methods:

eval(x)	Evaluates the application of the function to the given (instantiated) arguments.
gen_derivative(arg, x)	Generalized derivative that allows higher-order derivatives to be taken.
jvp(arg, dx, x)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

eval(x)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

gen_derivative(arg, x)

Generalized derivative that allows higher-order derivatives to be taken.

Parameters

• arg (list) – Indicates the order of derivatives to be taken. For example, to take the 2nd derivative w.r.t. x0,x1, arg = [0,1] should be specified.

• args (list of ndarrays) – arguments for the function.

Returns

A tensor of shape (n_out,n_in(arg[0]),..., n_in(arg[-1]).

If the generalized derivative is not implemented, raise a NotImplementedError.

If the generalized derivative is zero, can just return 0 (the integer) regardless of the size of the result.

Return type

ndarray

jvp(arg, dx, x)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

class klampt.math.autodiff.geometry_ad.BoxPointDistance(bmin, bmax)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Returns the (signed) distance of a point x to a bounding box [bmin,bmax]. The result is positive outside, and negative inside.

Methods:

eval(x)	Evaluates the application of the function to the given (instantiated) arguments.
jvp(arg, dx, x)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

eval(x)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

jvp(arg, dx, x)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

class klampt.math.autodiff.geometry_ad.BoxPointMargin(bmin, bmax)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Returns the inner margin of a point x inside a bounding box [bmin,bmax]. I.e., the minimum distance to the box boundaries, which is positive inside and negative outside.

Methods:

eval(x)	Evaluates the application of the function to the given (instantiated) arguments.
gen_derivative(arg, x)	Generalized derivative that allows higher-order derivatives to be taken.
jvp(arg, dx, x)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

eval(x)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

gen_derivative(arg, x)

Generalized derivative that allows higher-order derivatives to be taken.

Parameters

• arg (list) – Indicates the order of derivatives to be taken. For example, to take the 2nd derivative w.r.t. x0,x1, arg = [0,1] should be specified.

• args (list of ndarrays) – arguments for the function.

Returns

A tensor of shape (n_out,n_in(arg[0]),..., n_in(arg[-1]).

If the generalized derivative is not implemented, raise a NotImplementedError.

If the generalized derivative is zero, can just return 0 (the integer) regardless of the size of the result.

Return type

ndarray

jvp(arg, dx, x)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

class klampt.math.autodiff.geometry_ad.GeomGeomDistance(geom1, geom2, name1=None, name2=None, relErr=None, absErr=None, upperBound=None)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Autodiff wrapper of Geometry3D.distance. This is a function D(Tgeom1,Tgeom2) where Tgeom1 and Tgeom2 are the transforms of each geometry.

Note

This caches the result of eval(). If you change the geometry’s transform between eval(T1,T2) and eval(T1,T2_prime), then incorrect results will be returned.

Methods:

argname(arg)	Returns a descriptive string for argument #arg
eval(T1, T2)	Evaluates the application of the function to the given (instantiated) arguments.
jvp(arg, darg, T1, T2)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

argname(arg)

Returns a descriptive string for argument #arg

eval(T1, T2)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

jvp(arg, darg, T1, T2)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

class klampt.math.autodiff.geometry_ad.GeomPointClosest(geom, name=None)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Autodiff wrapper of Geometry3D.distance_point(x).cp1. This is a function CP(Tgeom,x) where Tgeom is the transform of the geometry

Note

This caches the result of eval(). If you change the geometry’s transform between eval(T,x) and eval(T,y), then incorrect results will be returned.

Methods:

argname(arg)	Returns a descriptive string for argument #arg
eval(T, x)	Evaluates the application of the function to the given (instantiated) arguments.
jvp(arg, darg, T, x)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

argname(arg)

Returns a descriptive string for argument #arg

eval(T, x)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

jvp(arg, darg, T, x)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

class klampt.math.autodiff.geometry_ad.GeomPointDistance(geom, name=None, relErr=None, absErr=None, upperBound=None)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Autodiff wrapper of Geometry3D.distance_point. This is a function D(Tgeom,x) where Tgeom is the transform of the geometry.

Note that this will make various assumptions about the local geometry shape, and how the closest point varies w.r.t. changes in Tgeom or x.

Note

This caches the result of eval(). If you change the geometry’s transform between eval(T,x) and eval(T,y), then incorrect results will be returned.

Methods:

argname(arg)	Returns a descriptive string for argument #arg
eval(T, x)	Evaluates the application of the function to the given (instantiated) arguments.
jvp(arg, darg, T, x)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

argname(arg)

Returns a descriptive string for argument #arg

eval(T, x)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

jvp(arg, darg, T, x)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

class klampt.math.autodiff.geometry_ad.GeomRayCast(geom, name=None)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Autodiff wrapper of Geometry3D.rayCast. This is a function RC(Tgeom,s,d) where Tgeom is the transform of the geometry, s is the ray source, and d is the ray direction.

Note

This caches the result of eval(). If you change the geometry’s transform between eval(T,s,d) and eval(T,sprime,dprime), then incorrect results will be returned.

Methods:

argname(arg)	Returns a descriptive string for argument #arg
eval(T, s, d)	Evaluates the application of the function to the given (instantiated) arguments.
jvp(arg, darg, T, s, d)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

argname(arg)

Returns a descriptive string for argument #arg

eval(T, s, d)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

jvp(arg, darg, T, s, d)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

class klampt.math.autodiff.geometry_ad.GeomSphereDistance(geom, name=None, relErr=None, absErr=None, upperBound=None)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Autodiff wrapper of Geometry3D.distance_point(c)-r. This is a function D(Tgeom,c,r) where Tgeom is the transform of the geometry.

See GeomPointClosest for a description of the arguments.

Methods:

argname(arg)	Returns a descriptive string for argument #arg
eval(T, c, r)	Evaluates the application of the function to the given (instantiated) arguments.
jvp(arg, darg, T, c, r)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

argname(arg)

Returns a descriptive string for argument #arg

eval(T, c, r)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

jvp(arg, darg, T, c, r)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

class klampt.math.autodiff.geometry_ad.MinDistance(geometries, pairs='all', names=None, relErr=None, absErr=None, upperBound=None)

Bases: klampt.math.autodiff.ad.ADFunctionInterface

Autodiff function that is equivalent to minimum(D1(…),…,DM(…)) but is faster due to the use of upper bounding and order caching. Upper bounding does early-stopping for distance calculation if it is found that

Di are functions of the form XYDistance. They are defined by a pair of geometries and are auto-determined by the geometry types.

Each argument to this function is a configuration of the corresponding geometry in the geometries list.

Note

This caches the result of eval(). If you change a geometry’s transform between eval(…) and eval(…), then incorrect results will be returned.

Parameters

• geometries (list) – a list of Geometry3D’s, points given as 3-vectors, or spheres given as (3-vector,scalar) pairs.

• pairs (list, optional) – if ‘all’, all pairs of geometries are tested. otherwise, this is a list of pairs of ints giving the indices of geometries to be tested against one another.

• names (list of str, optional) – if given, the geometries will be named for more informative print statements.

• relErr (float, optional) – passed to the DistanceQuerySettings objects used in distance queries.

• absErr (float, optional) – passed to the DistanceQuerySettings objects used in distance queries.

• upperBound (float, optional) – passed to the DistanceQuerySettings objects used in distance queries. If the minimum distance is greater than this value, this value will be returned.

Methods:

argname(arg)	Returns a descriptive string for argument #arg
eval(*args)	Evaluates the application of the function to the given (instantiated) arguments.
jvp(arg, darg, *args)	Performs a Jacobian-vector product for argument #arg.
n_args()	Returns the number of arguments.
n_in(arg)	Returns the number of entries in argument #arg.
n_out()	Returns the number of entries in the output of the function.

argname(arg)

Returns a descriptive string for argument #arg

eval(*args)

Evaluates the application of the function to the given (instantiated) arguments.

Parameters

args (list) – a list of arguments, which are either ndarrays or scalars.

jvp(arg, darg, *args)

Performs a Jacobian-vector product for argument #arg.

Parameters

• arg (int) – A value from 0,…,self.n_args()-1 indicating that we wish to calculate df/dx_arg * darg.

• darg (ndarray) – the derivative of x_arg w.r.t some other parameter. Must have darg.shape = (self.n_in(arg),).

• args (list of ndarrays) – arguments for the function.

Returns

A numpy array of length self.n_out()

If the derivative is not implemented, raise a NotImplementedError.

Return type

ndarray

n_args()

Returns the number of arguments.

n_in(arg)

Returns the number of entries in argument #arg. If 1, this can either be a 1-D vector or a scalar. If -1, the function can accept a variable sized argument.

n_out()

Returns the number of entries in the output of the function. If -1, this can output a variable sized argument.

klampt.math.autodiff.geometry_ad.sphere_point_closest(c, r, x)

Autodiff function CP(c,r,x) giving the closest point from a sphere with center c and radius r to a point x

klampt.math.autodiff.geometry_ad.sphere_point_distance(c, r, x)

Autodiff function D(c,r,x) giving the distance from a sphere with center c and radius r to a point x

klampt.math.autodiff.geometry_ad.sphere_sphere_closest(c1, r1, c2, r2)

Autodiff function CP(c1,r1,c2,r2)->R^2n giving the closest points between a sphere with center c1, radius r1 to a sphere with center c2, radius r2. The two points are stacked into a length 2n vector.

klampt.math.autodiff.geometry_ad.sphere_sphere_distance(c1, r1, c2, r2)

Autodiff function D(c1,r1,c2,r2) giving the distance from a sphere with center c1, radius r1 to a sphere with center c2, radius r2.