neml2::math Namespace Reference

Namespaces
namespace	linalg

Classes
struct	ConstantTensors
	A helper class to hold static data of type torch::Tensor. More...

Functions
Tensor	full_to_reduced (const Tensor &full, const torch::Tensor &rmap, const torch::Tensor &rfactors, Size dim=0)
	Generic function to reduce two axes to one with some map.
Tensor	reduced_to_full (const Tensor &reduced, const torch::Tensor &rmap, const torch::Tensor &rfactors, Size dim=0)
	Convert a Tensor from reduced notation to full notation.
Tensor	full_to_mandel (const Tensor &full, Size dim=0)
	Convert a Tensor from full notation to Mandel notation.
Tensor	mandel_to_full (const Tensor &mandel, Size dim=0)
	Convert a Tensor from Mandel notation to full notation.
Tensor	full_to_skew (const Tensor &full, Size dim=0)
	Convert a Tensor from full notation to skew vector notation.
Tensor	skew_to_full (const Tensor &skew, Size dim=0)
	Convert a Tensor from skew vector notation to full notation.
Tensor	jacrev (const Tensor &y, const Tensor &x, bool retain_graph=false, bool create_graph=false, bool allow_unused=false)
	Use automatic differentiation (AD) to calculate the derivatives of a Tensor w.r.t. another Tensor.
Tensor	base_diag_embed (const Tensor &a, Size offset, Size d1, Size d2)
SR2	skew_and_sym_to_sym (const SR2 &e, const WR2 &w)
	Product w_ik e_kj - e_ik w_kj with e SR2 and w WR2.
SSR4	d_skew_and_sym_to_sym_d_sym (const WR2 &w)
	Derivative of w_ik e_kj - e_ik w_kj wrt. e.
SWR4	d_skew_and_sym_to_sym_d_skew (const SR2 &e)
	Derivative of w_ik e_kj - e_ik w_kj wrt. w.
WR2	multiply_and_make_skew (const SR2 &a, const SR2 &b)
	Shortcut product a_ik b_kj - b_ik a_kj with both SR2.
WSR4	d_multiply_and_make_skew_d_first (const SR2 &b)
	Derivative of a_ik b_kj - b_ik a_kj wrt a.
WSR4	d_multiply_and_make_skew_d_second (const SR2 &a)
	Derivative of a_ik b_kj - b_ik a_kj wrt b.
Tensor	base_cat (const std::vector< Tensor > &tensors, Size d)
Tensor	base_stack (const std::vector< Tensor > &tensors, Size d)
Tensor	base_sum (const Tensor &a, Size d)
Tensor	base_mean (const Tensor &a, Size d)
Tensor	pow (const Real &a, const Tensor &n)
Tensor	pow (const Tensor &a, const Tensor &n)
Scalar	minimum (const Scalar &a, const Scalar &b)
	Minimum between two scalars.
Tensor	bmm (const Tensor &a, const Tensor &b)
	Batched matrix-matrix product.
Tensor	bmv (const Tensor &a, const Tensor &v)
	Batched matrix-vector product.
Tensor	bvv (const Tensor &a, const Tensor &b)
	Batched vector-vector (dot) product.
constexpr Real	mandel_factor (Size i)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	batch_cat (const std::vector< T > &tensors, Size d=0)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	batch_stack (const std::vector< T > &tensors, Size d=0)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	batch_sum (const T &a, Size d=0)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	batch_mean (const T &a, Size d=0)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	pow (const T &a, const Real &n)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	sign (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	cosh (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	sinh (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	tanh (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	arccos (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	arcsin (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	where (const torch::Tensor &condition, const T &a, const T &b)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	heaviside (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	macaulay (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	dmacaulay (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	sqrt (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	exp (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	abs (const T &a)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	diff (const T &a, Size n=1, Size dim=-1)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	batch_diag_embed (const T &a, Size offset=0, Size d1=-2, Size d2=-1)
template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
T	log (const T &a)
template<class Derived , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<Derived>, Derived>>>
Derived	pow (const Derived &a, const Scalar &n)

Variables
constexpr Real	eps = std::numeric_limits<at::scalar_value_type<Real>::type>::epsilon()
constexpr Real	sqrt2 = 1.4142135623730951
constexpr Real	invsqrt2 = 0.7071067811865475
constexpr std::array< std::array< Size, 3 >, 3 >	mandel_reverse_index
constexpr std::array< std::array< Size, 2 >, 6 >	mandel_index
constexpr std::array< std::array< Size, 3 >, 3 >	skew_reverse_index
constexpr std::array< std::array< Real, 3 >, 3 >	skew_factor

Function Documentation

abs()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T abs

(

const T &

a

)

arccos()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T arccos

(

const T &

a

)

arcsin()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T arcsin

(

const T &

a

)

base_cat()

neml2::Tensor base_cat	(	const std::vector< Tensor > &	tensors,
		Size	d )

base_diag_embed()

Tensor base_diag_embed	(	const Tensor &	a,
		Size	offset,
		Size	d1,
		Size	d2 )

base_mean()

neml2::Tensor base_mean	(	const Tensor &	a,
		Size	d )

base_stack()

neml2::Tensor base_stack	(	const std::vector< Tensor > &	tensors,
		Size	d )

base_sum()

neml2::Tensor base_sum	(	const Tensor &	a,
		Size	d )

batch_cat()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T batch_cat	(	const std::vector< T > &	tensors,
		Size	d = 0 )

batch_diag_embed()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T batch_diag_embed	(	const T &	a,
		Size	offset = 0,
		Size	d1 = -2,
		Size	d2 = -1 )

batch_mean()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T batch_mean	(	const T &	a,
		Size	d = 0 )

batch_stack()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T batch_stack	(	const std::vector< T > &	tensors,
		Size	d = 0 )

batch_sum()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T batch_sum	(	const T &	a,
		Size	d = 0 )

bmm()

Tensor bmm	(	const Tensor &	a,
		const Tensor &	b )

Batched matrix-matrix product.

The input matrices a and b must have exactly 2 base dimensions. The batch shapes must broadcast.

bmv()

Tensor bmv	(	const Tensor &	a,
		const Tensor &	v )

Batched matrix-vector product.

The input tensor a must have exactly 2 base dimensions. The input tensor v must have exactly 1 base dimension. The batch shapes must broadcast.

bvv()

Tensor bvv	(	const Tensor &	a,
		const Tensor &	b )

Batched vector-vector (dot) product.

The input tensor a must have exactly 1 base dimension. The input tensor b must have exactly 1 base dimension. The batch shapes must broadcast.

cosh()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T cosh

(

const T &

a

)

d_multiply_and_make_skew_d_first()

WSR4 d_multiply_and_make_skew_d_first

(

const SR2 &

b

)

Derivative of a_ik b_kj - b_ik a_kj wrt a.

d_multiply_and_make_skew_d_second()

WSR4 d_multiply_and_make_skew_d_second

(

const SR2 &

a

)

Derivative of a_ik b_kj - b_ik a_kj wrt b.

d_skew_and_sym_to_sym_d_skew()

SWR4 d_skew_and_sym_to_sym_d_skew

(

const SR2 &

e

)

Derivative of w_ik e_kj - e_ik w_kj wrt. w.

d_skew_and_sym_to_sym_d_sym()

SSR4 d_skew_and_sym_to_sym_d_sym

(

const WR2 &

w

)

Derivative of w_ik e_kj - e_ik w_kj wrt. e.

diff()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T diff	(	const T &	a,
		Size	n = 1,
		Size	dim = -1 )

dmacaulay()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T dmacaulay

(

const T &

a

)

exp()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T exp

(

const T &

a

)

full_to_mandel()

Tensor full_to_mandel	(	const Tensor &	full,
		Size	dim = 0 )

Convert a Tensor from full notation to Mandel notation.

The tensor in full notation full can have arbitrary batch shape. The optional argument dim denotes the base dimension starting from which the conversion should take place.

For example, a full tensor has shape (2, 3, 1, 5; 2, 9, 3, 3, 2, 3) where the semicolon separates batch and base shapes. The symmetric axes have base dim 2 and 3. After converting to Mandel notation, the resulting tensor will have shape (2, 3, 1, 5; 2, 9, 6, 2, 3). Note how the shape of the symmetric dimensions (3, 3) becomes (6). In this example, the base dim (the second argument to this function) should be 2.

Parameters

full	The input tensor in full notation
dim	The base dimension where the symmetric axes start

Returns

Tensor The resulting tensor using Mandel notation to represent the symmetric axes.

full_to_reduced()

Tensor full_to_reduced	(	const Tensor &	full,
		const torch::Tensor &	rmap,
		const torch::Tensor &	rfactors,
		Size	dim = 0 )

Generic function to reduce two axes to one with some map.

The tensor in full notation full can have arbitrary batch shape. The optional argument dim denotes the base dimension starting from which the conversion should take place.

The function will reduce the two axis at the desired location down to one, using the provided maps.

For example, a full tensor has shape (2, 3, 1, 5; 2, 9, 3, 3, 2, 3) where the semicolon separates batch and base shapes. The reduction axes have base dim 2 and 3. After applying the reduction, the resulting tensor will have shape (2, 3, 1, 5; 2, 9, X, 2, 3) where X is the reduced shape. In this example, the base dim (the second argument to this function) should be 2.

Parameters

full	The input tensor in full notation
rmap	The reduction map
rfactors	The reduction factors
dim	The base dimension where the reduced axes start

Returns

Tensor The reduced tensor

full_to_skew()

Tensor full_to_skew	(	const Tensor &	full,
		Size	dim = 0 )

Convert a Tensor from full notation to skew vector notation.

The tensor in full notation full can have arbitrary batch shape. The optional argument dim denotes the base dimension starting from which the conversion should take place.

For example, a full tensor has shape (2, 3, 1, 5; 2, 9, 3, 3, 2, 3) where the semicolon separates batch and base shapes. The symmetric axes have base dim 2 and 3. After converting to skew notation, the resulting tensor will have shape (2, 3, 1, 5; 2, 9, 3, 2, 3). Note how the shape of the symmetric dimensions (3, 3) becomes (3). In this example, the base dim (the second argument to this function) should be 2.

Parameters

full	The input tensor in full notation
dim	The base dimension where the symmetric axes start

Returns

Tensor The resulting tensor using skew notation to represent the skew-symmetric axes.

heaviside()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T heaviside

(

const T &

a

)

This is (almost) equivalent to Torch's heaviside, except that the Torch's version is not differentiable (back-propagatable). I said "almost" because torch::heaviside allows you to set the return value in the case of input == 0. Our implementation always return 0.5 when the input == 0.

jacrev()

Tensor jacrev	(	const Tensor &	y,
		const Tensor &	x,
		bool	retain_graph = false,
		bool	create_graph = false,
		bool	allow_unused = false )

Use automatic differentiation (AD) to calculate the derivatives of a Tensor w.r.t. another Tensor.

Warning

Torch (and hence NEML2) AD wasn't designed to compute the full Jacobian from the very beginning. Using this method to calculate the full Jacobian is inefficient and is subjected to some restrictions on batch shapes.

Parameters

y	The Tensor to to be differentiated
x	The argument to take derivatives with respect to
retain_graph	Whether to retain the computation graph (necessary if y has base storage size ‍1)
create_graph	Whether to create the computation graph (necessary if you want to differentiate the returned Jacobian)
allow_unused	Whether to allow unused input argument x

Returns

Tensor \(\partial y/\partial p\)

log()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T log

(

const T &

a

)

macaulay()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T macaulay

(

const T &

a

)

mandel_factor()

constexpr Real mandel_factor ( Size i )

inlineconstexpr

mandel_to_full()

Tensor mandel_to_full	(	const Tensor &	mandel,
		Size	dim = 0 )

Convert a Tensor from Mandel notation to full notation.

See full_to_mandel for a detailed explanation.

Parameters

mandel	The input tensor in Mandel notation
dim	The base dimension where the symmetric axes start

Returns

Tensor The resulting tensor in full notation.

minimum()

Scalar minimum	(	const Scalar &	a,
		const Scalar &	b )

Minimum between two scalars.

multiply_and_make_skew()

WR2 multiply_and_make_skew	(	const SR2 &	a,
		const SR2 &	b )

Shortcut product a_ik b_kj - b_ik a_kj with both SR2.

pow() [1/4]

template<class Derived , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<Derived>, Derived>>>

Derived pow	(	const Derived &	a,
		const Scalar &	n )

pow() [2/4]

Tensor pow	(	const Real &	a,
		const Tensor &	n )

pow() [3/4]

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T pow	(	const T &	a,
		const Real &	n )

pow() [4/4]

Tensor pow	(	const Tensor &	a,
		const Tensor &	n )

reduced_to_full()

Tensor reduced_to_full	(	const Tensor &	reduced,
		const torch::Tensor &	rmap,
		const torch::Tensor &	rfactors,
		Size	dim = 0 )

Convert a Tensor from reduced notation to full notation.

See full_to_reduced for a detailed explanation.

Parameters

reduced	The input tensor in reduced notation
rmap	The unreduction map
rfactors	The unreduction factors
dim	The base dimension where the reduced axes start

Returns

Tensor The resulting tensor in full notation.

sign()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T sign

(

const T &

a

)

sinh()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T sinh

(

const T &

a

)

skew_and_sym_to_sym()

SR2 skew_and_sym_to_sym	(	const SR2 &	e,
		const WR2 &	w )

Product w_ik e_kj - e_ik w_kj with e SR2 and w WR2.

skew_to_full()

Tensor skew_to_full	(	const Tensor &	skew,
		Size	dim = 0 )

Convert a Tensor from skew vector notation to full notation.

See full_to_skew for a detailed explanation.

Parameters

skew	The input tensor in skew notation
dim	The base dimension where the symmetric axes start

Returns

Tensor The resulting tensor in full notation.

sqrt()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T sqrt

(

const T &

a

)

tanh()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T tanh

(

const T &

a

)

where()

template<class T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>

T where	(	const torch::Tensor &	condition,
		const T &	a,
		const T &	b )

Variable Documentation

eps

constexpr Real eps = std::numeric_limits<at::scalar_value_type<Real>::type>::epsilon()

constexpr

invsqrt2

constexpr Real invsqrt2 = 0.7071067811865475

constexpr

mandel_index

constexpr std::array<std::array<Size, 2>, 6> mandel_index

constexpr

Initial value:

{std::array<Size, 2>{0, 0},
                                                          std::array<Size, 2>{1, 1},
                                                          std::array<Size, 2>{2, 2},
                                                          std::array<Size, 2>{1, 2},
                                                          std::array<Size, 2>{0, 2},
                                                          std::array<Size, 2>{0, 1}}

mandel_reverse_index

constexpr std::array<std::array<Size, 3>, 3> mandel_reverse_index

constexpr

Initial value:

{
    std::array<Size, 3>{0, 5, 4}, std::array<Size, 3>{5, 1, 3}, std::array<Size, 3>{4, 3, 2}}

skew_factor

constexpr std::array<std::array<Real, 3>, 3> skew_factor

constexpr

Initial value:

{std::array<Real, 3>{0.0, -1.0, 1.0},
                                                         std::array<Real, 3>{1.0, 0.0, -1.0},
                                                         std::array<Real, 3>{-1.0, 1.0, 0.0}}

skew_reverse_index

constexpr std::array<std::array<Size, 3>, 3> skew_reverse_index

constexpr

Initial value:

{
    std::array<Size, 3>{0, 2, 1}, std::array<Size, 3>{2, 0, 0}, std::array<Size, 3>{1, 0, 0}}

sqrt2

constexpr Real sqrt2 = 1.4142135623730951

constexpr