29 Numerics library [numerics]

29.1 General [numerics.general]

This Clause describes components that C++ programs may use to perform seminumerical operations.

The following subclauses describe components for complex number types, random number generation, numeric (n-at-a-time) arrays, generalized numeric algorithms, and mathematical constants and functions for floating-point types, as summarized in Table 120 .

Table 120: Numerics library summary [tab:numerics.summary]

🔗		Subclause	Header
🔗	[numeric.requirements]	Requirements
🔗	[cfenv]	Floating-point environment	<cfenv>
🔗	[complex.numbers]	Complex numbers	<complex>
🔗	[rand]	Random number generation	<random>
🔗	[numarray]	Numeric arrays	<valarray>
🔗	[c.math]	Mathematical functions for floating-point types	<cmath>, <cstdlib>
🔗	[numbers]	Numbers	<numbers>
🔗	[linalg]	Linear algebra	<linalg>

29.2 Numeric type requirements [numeric.requirements]

The complex and valarray components are parameterized by the type of information they contain and manipulate.

A C++ program shall instantiate these components only with a numeric type.

A numeric type is a cv-unqualified object type T that meets the Cpp17DefaultConstructible, Cpp17CopyConstructible, Cpp17CopyAssignable, and Cpp17Destructible requirements ([utility.arg.requirements]).245

If any operation on T throws an exception the effects are undefined.

In addition, many member and related functions of valarray<T> can be successfully instantiated and will exhibit well-defined behavior if and only if T meets additional requirements specified for each such member or related function.

[Example 1:

It is valid to instantiate valarray<complex>, but operator>() will not be successfully instantiated for valarray<complex> operands, since complex does not have any ordering operators.

— end example]

245)245)

In other words, value types.

These include arithmetic types, pointers, the library class complex, and instantiations of valarray for value types.

29.3 The floating-point environment [cfenv]

29.3.1 Header <cfenv> synopsis [cfenv.syn]

🔗

#define FE_ALL_EXCEPT see below #define FE_DIVBYZERO see below // optional #define FE_INEXACT see below // optional #define FE_INVALID see below // optional #define FE_OVERFLOW see below // optional #define FE_UNDERFLOW see below // optional #define FE_DOWNWARD see below // optional #define FE_TONEAREST see below // optional #define FE_TOWARDZERO see below // optional #define FE_UPWARD see below // optional #define FE_DFL_ENV see below namespace std { // types using fenv_t = object type; using fexcept_t = object type; // functions int feclearexcept(int except); int fegetexceptflag(fexcept_t* pflag, int except); int feraiseexcept(int except); int fesetexceptflag(const fexcept_t* pflag, int except); int fetestexcept(int except); int fegetround(); int fesetround(int mode); int fegetenv(fenv_t* penv); int feholdexcept(fenv_t* penv); int fesetenv(const fenv_t* penv); int feupdateenv(const fenv_t* penv); }

The contents and meaning of the header <cfenv> are the same as the C standard library header <fenv.h>.

[Note 1:

This document does not require an implementation to support the FENV_ACCESS pragma; it is implementation-defined ([cpp.pragma]) whether the pragma is supported.

As a consequence, it is implementation-defined whether these functions can be used to test floating-point status flags, set floating-point control modes, or run under non-default mode settings.

If the pragma is used to enable control over the floating-point environment, this document does not specify the effect on floating-point evaluation in constant expressions.

— end note]

29.3.2 Threads [cfenv.thread]

The floating-point environment has thread storage duration .

The initial state for a thread's floating-point environment is the state of the floating-point environment of the thread that constructs the corresponding thread object ([thread.thread.class]) or jthread object ([thread.jthread.class]) at the time it constructed the object.

[Note 1:

That is, the child thread gets the floating-point state of the parent thread at the time of the child's creation.

— end note]

A separate floating-point environment is maintained for each thread.

Each function accesses the environment corresponding to its calling thread.

29.4 Complex numbers [complex.numbers]

29.4.1 General [complex.numbers.general]

The header <complex> defines a class template, and numerous functions for representing and manipulating complex numbers.

The effect of instantiating the template complex for any type that is not a cv-unqualified floating-point type ([basic.fundamental]) is unspecified.

Specializations of complex for cv-unqualified floating-point types are trivially copyable literal types ([basic.types.general]).

If the result of a function is not mathematically defined or not in the range of representable values for its type, the behavior is undefined.

If z is an lvalue of type cv complex<T> then:

(4.1)
the expression reinterpret_cast<cv T(&)[2]>(z) is well-formed,
(4.2)
reinterpret_cast<cv T(&)[2]>(z)[0] designates the real part of z, and
(4.3)
reinterpret_cast<cv T(&)[2]>(z)[1] designates the imaginary part of z.

Moreover, if a is an expression of type cv complex<T>* and the expression a[i] is well-defined for an integer expression i, then:

(4.4)
reinterpret_cast<cv T*>(a)[2*i] designates the real part of a[i], and
(4.5)
reinterpret_cast<cv T*>(a)[2*i + 1] designates the imaginary part of a[i].

29.4.2 Header <complex> synopsis [complex.syn]

🔗

namespace std { // [complex], class template complex template<class T> class complex; // [complex.ops], operators template<class T> constexpr complex<T> operator+(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator+(const complex<T>&, const T&); template<class T> constexpr complex<T> operator+(const T&, const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&, const T&); template<class T> constexpr complex<T> operator-(const T&, const complex<T>&); template<class T> constexpr complex<T> operator*(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator*(const complex<T>&, const T&); template<class T> constexpr complex<T> operator*(const T&, const complex<T>&); template<class T> constexpr complex<T> operator/(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator/(const complex<T>&, const T&); template<class T> constexpr complex<T> operator/(const T&, const complex<T>&); template<class T> constexpr complex<T> operator+(const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&); template<class T> constexpr bool operator==(const complex<T>&, const complex<T>&); template<class T> constexpr bool operator==(const complex<T>&, const T&); template<class T, class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, complex<T>&); template<class T, class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const complex<T>&); // [complex.value.ops], values template<class T> constexpr T real(const complex<T>&); template<class T> constexpr T imag(const complex<T>&); template<class T> constexpr T abs(const complex<T>&); template<class T> constexpr T arg(const complex<T>&); template<class T> constexpr T norm(const complex<T>&); template<class T> constexpr complex<T> conj(const complex<T>&); template<class T> constexpr complex<T> proj(const complex<T>&); template<class T> constexpr complex<T> polar(const T&, const T& = T()); // [complex.transcendentals], transcendentals template<class T> constexpr complex<T> acos(const complex<T>&); template<class T> constexpr complex<T> asin(const complex<T>&); template<class T> constexpr complex<T> atan(const complex<T>&); template<class T> constexpr complex<T> acosh(const complex<T>&); template<class T> constexpr complex<T> asinh(const complex<T>&); template<class T> constexpr complex<T> atanh(const complex<T>&); template<class T> constexpr complex<T> cos (const complex<T>&); template<class T> constexpr complex<T> cosh (const complex<T>&); template<class T> constexpr complex<T> exp (const complex<T>&); template<class T> constexpr complex<T> log (const complex<T>&); template<class T> constexpr complex<T> log10(const complex<T>&); template<class T> constexpr complex<T> pow (const complex<T>&, const T&); template<class T> constexpr complex<T> pow (const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> pow (const T&, const complex<T>&); template<class T> constexpr complex<T> sin (const complex<T>&); template<class T> constexpr complex<T> sinh (const complex<T>&); template<class T> constexpr complex<T> sqrt (const complex<T>&); template<class T> constexpr complex<T> tan (const complex<T>&); template<class T> constexpr complex<T> tanh (const complex<T>&); // [complex.tuple], tuple interface template<class T> struct tuple_size; template<size_t I, class T> struct tuple_element; template<class T> struct tuple_size<complex<T>>; template<size_t I, class T> struct tuple_element<I, complex<T>>; template<size_t I, class T> constexpr T& get(complex<T>&) noexcept; template<size_t I, class T> constexpr T&& get(complex<T>&&) noexcept; template<size_t I, class T> constexpr const T& get(const complex<T>&) noexcept; template<size_t I, class T> constexpr const T&& get(const complex<T>&&) noexcept; // [complex.literals], complex literals inline namespace literals { inline namespace complex_literals { constexpr complex<long double> operator""il(long double); constexpr complex<long double> operator""il(unsigned long long); constexpr complex<double> operator""i(long double); constexpr complex<double> operator""i(unsigned long long); constexpr complex<float> operator""if(long double); constexpr complex<float> operator""if(unsigned long long); } } }

29.4.3 Class template complex [complex]

🔗

namespace std { template<class T> class complex { public: using value_type = T; constexpr complex(const T& re = T(), const T& im = T()); constexpr complex(const complex&) = default; template<class X> constexpr explicit(see below) complex(const complex<X>&); constexpr T real() const; constexpr void real(T); constexpr T imag() const; constexpr void imag(T); constexpr complex& operator= (const T&); constexpr complex& operator+=(const T&); constexpr complex& operator-=(const T&); constexpr complex& operator*=(const T&); constexpr complex& operator/=(const T&); constexpr complex& operator=(const complex&); template<class X> constexpr complex& operator= (const complex<X>&); template<class X> constexpr complex& operator+=(const complex<X>&); template<class X> constexpr complex& operator-=(const complex<X>&); template<class X> constexpr complex& operator*=(const complex<X>&); template<class X> constexpr complex& operator/=(const complex<X>&); }; }

The class complex describes an object that can store the Cartesian components, real() and imag(), of a complex number.

29.4.4 Member functions [complex.members]

🔗

constexpr complex(const T& re = T(), const T& im = T());

Postconditions: real() == re && imag() == im is true.

🔗

template<class X> constexpr explicit(see below) complex(const complex<X>& other);

Effects: Initializes the real part with other.real() and the imaginary part with other.imag().

Remarks: The expression inside explicit evaluates to false if and only if the floating-point conversion rank of T is greater than or equal to the floating-point conversion rank of X.

🔗

constexpr T real() const;

Returns: The value of the real component.

🔗

constexpr void real(T val);

Effects: Assigns val to the real component.

🔗

constexpr T imag() const;

Returns: The value of the imaginary component.

🔗

constexpr void imag(T val);

Effects: Assigns val to the imaginary component.

29.4.5 Member operators [complex.member.ops]

🔗

constexpr complex& operator+=(const T& rhs);

Effects: Adds the scalar value rhs to the real part of the complex value *this and stores the result in the real part of *this, leaving the imaginary part unchanged.

Returns: *this.

🔗

constexpr complex& operator-=(const T& rhs);

Effects: Subtracts the scalar value rhs from the real part of the complex value *this and stores the result in the real part of *this, leaving the imaginary part unchanged.

Returns: *this.

🔗

constexpr complex& operator*=(const T& rhs);

Effects: Multiplies the scalar value rhs by the complex value *this and stores the result in *this.

Returns: *this.

🔗

constexpr complex& operator/=(const T& rhs);

Effects: Divides the scalar value rhs into the complex value *this and stores the result in *this.

Returns: *this.

🔗

template<class X> constexpr complex& operator=(const complex<X>& rhs);

Effects: Assigns the value rhs.real() to the real part and the value rhs.imag() to the imaginary part of the complex value *this.

Returns: *this.

🔗

template<class X> constexpr complex& operator+=(const complex<X>& rhs);

Effects: Adds the complex value rhs to the complex value *this and stores the sum in *this.

Returns: *this.

🔗

template<class X> constexpr complex& operator-=(const complex<X>& rhs);

Effects: Subtracts the complex value rhs from the complex value *this and stores the difference in *this.

Returns: *this.

🔗

template<class X> constexpr complex& operator*=(const complex<X>& rhs);

Effects: Multiplies the complex value rhs by the complex value *this and stores the product in *this.

Returns: *this.

🔗

template<class X> constexpr complex& operator/=(const complex<X>& rhs);

Effects: Divides the complex value rhs into the complex value *this and stores the quotient in *this.

Returns: *this.

29.4.6 Non-member operations [complex.ops]

🔗

template<class T> constexpr complex<T> operator+(const complex<T>& lhs);

Returns: complex<T>(lhs).

🔗

template<class T> constexpr complex<T> operator+(const complex<T>& lhs, const complex<T>& rhs);
template<class T> constexpr complex<T> operator+(const complex<T>& lhs, const T& rhs);
template<class T> constexpr complex<T> operator+(const T& lhs, const complex<T>& rhs);

Returns: complex<T>(lhs) += rhs.

🔗

template<class T> constexpr complex<T> operator-(const complex<T>& lhs);

Returns: complex<T>(-lhs.real(),-lhs.imag()).

🔗

template<class T> constexpr complex<T> operator-(const complex<T>& lhs, const complex<T>& rhs);
template<class T> constexpr complex<T> operator-(const complex<T>& lhs, const T& rhs);
template<class T> constexpr complex<T> operator-(const T& lhs, const complex<T>& rhs);

Returns: complex<T>(lhs) -= rhs.

🔗

template<class T> constexpr complex<T> operator*(const complex<T>& lhs, const complex<T>& rhs);
template<class T> constexpr complex<T> operator*(const complex<T>& lhs, const T& rhs);
template<class T> constexpr complex<T> operator*(const T& lhs, const complex<T>& rhs);

Returns: complex<T>(lhs) *= rhs.

🔗

template<class T> constexpr complex<T> operator/(const complex<T>& lhs, const complex<T>& rhs);
template<class T> constexpr complex<T> operator/(const complex<T>& lhs, const T& rhs);
template<class T> constexpr complex<T> operator/(const T& lhs, const complex<T>& rhs);

Returns: complex<T>(lhs) /= rhs.

🔗

template<class T> constexpr bool operator==(const complex<T>& lhs, const complex<T>& rhs);
template<class T> constexpr bool operator==(const complex<T>& lhs, const T& rhs);

Returns: lhs.real() == rhs.real() && lhs.imag() == rhs.imag().

Remarks: The imaginary part is assumed to be T(), or 0.0, for the T arguments.

🔗

template<class T, class charT, class traits>
  basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, complex<T>& x);

Preconditions: The input values are convertible to T.

Effects: Extracts a complex number x of the form: u, (u), or (u,v), where u is the real part and v is the imaginary part ([istream.formatted]).

If bad input is encountered, calls is.setstate(ios_base::failbit) (which may throw ios_base::failure ([iostate.flags])).

Returns: is.

Remarks: This extraction is performed as a series of simpler extractions.

Therefore, the skipping of whitespace is specified to be the same for each of the simpler extractions.

🔗

template<class T, class charT, class traits>
  basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& o, const complex<T>& x);

Effects: Inserts the complex number x onto the stream o as if it were implemented as follows: basic_ostringstream<charT, traits> s; s.flags(o.flags()); s.imbue(o.getloc()); s.precision(o.precision()); s << '(' << x.real() << ',' << x.imag() << ')'; return o << s.str();

[Note 1:

In a locale in which comma is used as a decimal point character, the use of comma as a field separator can be ambiguous.

Inserting showpoint into the output stream forces all outputs to show an explicit decimal point character; as a result, all inserted sequences of complex numbers can be extracted unambiguously.

— end note]

29.4.7 Value operations [complex.value.ops]

🔗

template<class T> constexpr T real(const complex<T>& x);

Returns: x.real().

🔗

template<class T> constexpr T imag(const complex<T>& x);

Returns: x.imag().

🔗

template<class T> constexpr T abs(const complex<T>& x);

Returns: The magnitude of x.

🔗

template<class T> constexpr T arg(const complex<T>& x);

Returns: The phase angle of x, or atan2(imag(x), real(x)).

🔗

template<class T> constexpr T norm(const complex<T>& x);

Returns: The squared magnitude of x.

🔗

template<class T> constexpr complex<T> conj(const complex<T>& x);

Returns: The complex conjugate of x.

🔗

template<class T> constexpr complex<T> proj(const complex<T>& x);

Returns: The projection of x onto the Riemann sphere.

Remarks: Behaves the same as the C function cproj.

29.4.8 Transcendentals [complex.transcendentals]

🔗

template<class T> constexpr complex<T> acos(const complex<T>& x);

Returns: The complex arc cosine of x.

Remarks: Behaves the same as the C function cacos.

29.4.9 Tuple interface [complex.tuple]

🔗

template<class T>
struct tuple_size<complex<T>> : integral_constant<size_t, 2> {};

template<size_t I, class T>
struct tuple_element<I, complex<T>> {
  using type = T;
};

Mandates: I < 2 is true.

🔗

template<size_t I, class T>
  constexpr T& get(complex<T>& z) noexcept;
template<size_t I, class T>
  constexpr T&& get(complex<T>&& z) noexcept;
template<size_t I, class T>
  constexpr const T& get(const complex<T>& z) noexcept;
template<size_t I, class T>
  constexpr const T&& get(const complex<T>&& z) noexcept;

Mandates: I < 2 is true.

Returns: A reference to the real part of z if I == 0 is true, otherwise a reference to the imaginary part of z.

29.4.10 Additional overloads [cmplx.over]

The following function templates have additional constexpr overloads: arg norm conj proj imag real

The additional constexpr overloads are sufficient to ensure:

(2.1)
If the argument has a floating-point type T, then it is effectively cast to complex<T>.
(2.2)
Otherwise, if the argument has integer type, then it is effectively cast to complex<double>.

Function template pow has additional constexpr overloads sufficient to ensure, for a call with one argument of type complex<T1> and the other argument of type T2 or complex<T2>, both arguments are effectively cast to complex<common_type_t<T1, T2>>.

If common_type_t<T1, T2> is not well-formed, then the program is ill-formed.

29.4.11 Suffixes for complex number literals [complex.literals]

This subclause describes literal suffixes for constructing complex number literals.

The suffixes i, il, and if create complex numbers of the types complex<double>, complex<long double>, and complex<float> respectively, with their imaginary part denoted by the given literal number and the real part being zero.

🔗

constexpr complex<long double> operator""il(long double d);
constexpr complex<long double> operator""il(unsigned long long d);

Returns: complex<long double>{0.0L, static_cast<long double>(d)}.

🔗

constexpr complex<double> operator""i(long double d);
constexpr complex<double> operator""i(unsigned long long d);

Returns: complex<double>{0.0, static_cast<double>(d)}.

🔗

constexpr complex<float> operator""if(long double d);
constexpr complex<float> operator""if(unsigned long long d);

Returns: complex<float>{0.0f, static_cast<float>(d)}.

29.5 Random number generation [rand]

29.5.1 General [rand.general]

Subclause [rand] defines a facility for generating (pseudo-)random numbers.

In addition to a few utilities, four categories of entities are described: uniform random bit generators, random number engines, random number engine adaptors, and random number distributions.

These categorizations are applicable to types that meet the corresponding requirements, to objects instantiated from such types, and to templates producing such types when instantiated.

[Note 1:

These entities are specified in such a way as to permit the binding of any uniform random bit generator object e as the argument to any random number distribution object d, thus producing a zero-argument function object such as given by bind(d,e).

— end note]

Each of the entities specified in [rand] has an associated arithmetic type ([basic.fundamental]) identified as result_type.

With T as the result_type thus associated with such an entity, that entity is characterized:

(3.1)
as boolean or equivalently as boolean-valued, if T is bool;
(3.2)
otherwise as integral or equivalently as integer-valued, if numeric_limits<T>::is_integer is true;
(3.3)
otherwise as floating-point or equivalently as real-valued.

If integer-valued, an entity may optionally be further characterized as signed or unsigned, according to numeric_limits<T>::is_signed.

Unless otherwise specified, all descriptions of calculations in [rand] use mathematical real numbers.

Throughout [rand], the operators bitand, bitor, and xor denote the respective conventional bitwise operations.

Further:

(5.1)
the operator rshift denotes a bitwise right shift with zero-valued bits appearing in the high bits of the result, and
(5.2)
the operator ${l s h i f t}_{w}$ denotes a bitwise left shift with zero-valued bits appearing in the low bits of the result, and whose result is always taken modulo $2^{w}$ .

29.5.2 Header <random> synopsis [rand.synopsis]

#include <initializer_list> // see [initializer.list.syn] namespace std { // [rand.req.urng], uniform random bit generator requirements template<class G> concept uniform_random_bit_generator = see below; // [rand.eng.lcong], class template linear_congruential_engine template<class UIntType, UIntType a, UIntType c, UIntType m> class linear_congruential_engine; // [rand.eng.mers], class template mersenne_twister_engine template<class UIntType, size_t w, size_t n, size_t m, size_t r, UIntType a, size_t u, UIntType d, size_t s, UIntType b, size_t t, UIntType c, size_t l, UIntType f> class mersenne_twister_engine; // [rand.eng.sub], class template subtract_with_carry_engine template<class UIntType, size_t w, size_t s, size_t r> class subtract_with_carry_engine; // [rand.adapt.disc], class template discard_block_engine template<class Engine, size_t p, size_t r> class discard_block_engine; // [rand.adapt.ibits], class template independent_bits_engine template<class Engine, size_t w, class UIntType> class independent_bits_engine; // [rand.adapt.shuf], class template shuffle_order_engine template<class Engine, size_t k> class shuffle_order_engine; // [rand.eng.philox], class template philox_engine template<class UIntType, size_t w, size_t n, size_t r, UIntType... consts> class philox_engine; // [rand.predef], engines and engine adaptors with predefined parameters using minstd_rand0 = see below; using minstd_rand = see below; using mt19937 = see below; using mt19937_64 = see below; using ranlux24_base = see below; using ranlux48_base = see below; using ranlux24 = see below; using ranlux48 = see below; using knuth_b = see below; using philox4x32 = see below; using philox4x64 = see below; using default_random_engine = see below; // [rand.device], class random_device class random_device; // [rand.util.seedseq], class seed_seq class seed_seq; // [rand.util.canonical], function template generate_canonical template<class RealType, size_t digits, class URBG> RealType generate_canonical(URBG& g); namespace ranges { // [alg.rand.generate], generate_random template<class R, class G> requires output_range<R, invoke_result_t<G&>> && uniform_random_bit_generator<remove_cvref_t<G>> constexpr borrowed_iterator_t<R> generate_random(R&& r, G&& g); template<class G, output_iterator<invoke_result_t<G&>> O, sentinel_for<O> S> requires uniform_random_bit_generator<remove_cvref_t<G>> constexpr O generate_random(O first, S last, G&& g); template<class R, class G, class D> requires output_range<R, invoke_result_t<D&, G&>> && invocable<D&, G&> && uniform_random_bit_generator<remove_cvref_t<G>> constexpr borrowed_iterator_t<R> generate_random(R&& r, G&& g, D&& d); template<class G, class D, output_iterator<invoke_result_t<D&, G&>> O, sentinel_for<O> S> requires invocable<D&, G&> && uniform_random_bit_generator<remove_cvref_t<G>> constexpr O generate_random(O first, S last, G&& g, D&& d); } // [rand.dist.uni.int], class template uniform_int_distribution template<class IntType = int> class uniform_int_distribution; // [rand.dist.uni.real], class template uniform_real_distribution template<class RealType = double> class uniform_real_distribution; // [rand.dist.bern.bernoulli], class bernoulli_distribution class bernoulli_distribution; // [rand.dist.bern.bin], class template binomial_distribution template<class IntType = int> class binomial_distribution; // [rand.dist.bern.geo], class template geometric_distribution template<class IntType = int> class geometric_distribution; // [rand.dist.bern.negbin], class template negative_binomial_distribution template<class IntType = int> class negative_binomial_distribution; // [rand.dist.pois.poisson], class template poisson_distribution template<class IntType = int> class poisson_distribution; // [rand.dist.pois.exp], class template exponential_distribution template<class RealType = double> class exponential_distribution; // [rand.dist.pois.gamma], class template gamma_distribution template<class RealType = double> class gamma_distribution; // [rand.dist.pois.weibull], class template weibull_distribution template<class RealType = double> class weibull_distribution; // [rand.dist.pois.extreme], class template extreme_value_distribution template<class RealType = double> class extreme_value_distribution; // [rand.dist.norm.normal], class template normal_distribution template<class RealType = double> class normal_distribution; // [rand.dist.norm.lognormal], class template lognormal_distribution template<class RealType = double> class lognormal_distribution; // [rand.dist.norm.chisq], class template chi_squared_distribution template<class RealType = double> class chi_squared_distribution; // [rand.dist.norm.cauchy], class template cauchy_distribution template<class RealType = double> class cauchy_distribution; // [rand.dist.norm.f], class template fisher_f_distribution template<class RealType = double> class fisher_f_distribution; // [rand.dist.norm.t], class template student_t_distribution template<class RealType = double> class student_t_distribution; // [rand.dist.samp.discrete], class template discrete_distribution template<class IntType = int> class discrete_distribution; // [rand.dist.samp.pconst], class template piecewise_constant_distribution template<class RealType = double> class piecewise_constant_distribution; // [rand.dist.samp.plinear], class template piecewise_linear_distribution template<class RealType = double> class piecewise_linear_distribution; }

29.5.3 Requirements [rand.req]

29.5.3.1 General requirements [rand.req.genl]

Throughout [rand], the effect of instantiating a template:

(1.1)
that has a template type parameter named Sseq is undefined unless the corresponding template argument is cv-unqualified and meets the requirements of seed sequence .
(1.2)
that has a template type parameter named URBG is undefined unless the corresponding template argument is cv-unqualified and meets the requirements of uniform random bit generator .
(1.3)
that has a template type parameter named Engine is undefined unless the corresponding template argument is cv-unqualified and meets the requirements of random number engine .
(1.4)
that has a template type parameter named RealType is undefined unless the corresponding template argument is cv-unqualified and is one of float, double, or long double.
(1.5)
that has a template type parameter named IntType is undefined unless the corresponding template argument is cv-unqualified and is one of short, int, long, long long, unsigned short, unsigned int, unsigned long, or unsigned long long.
(1.6)
that has a template type parameter named UIntType is undefined unless the corresponding template argument is cv-unqualified and is one of unsigned short, unsigned int, unsigned long, or unsigned long long.

Throughout [rand], phrases of the form “x is an iterator of a specific kind” shall be interpreted as equivalent to the more formal requirement that “x is a value of a type meeting the requirements of the specified iterator type”.

Throughout [rand], any constructor that can be called with a single argument and that meets a requirement specified in this subclause shall be declared explicit.

29.5.3.2 Seed sequence requirements [rand.req.seedseq]

A seed sequence is an object that consumes a sequence of integer-valued data and produces a requested number of unsigned integer values i,

0 \leq i < 2^{32}

, based on the consumed data.

[Note 1:

Such an object provides a mechanism to avoid replication of streams of random variates.

This can be useful, for example, in applications requiring large numbers of random number engines.

— end note]

A class S meets the requirements of a seed sequence if the expressions shown in Table 121 are valid and have the indicated semantics, and if S also meets all other requirements of [rand.req.seedseq].

In Table 121 and throughout this subclause:

(2.1)
T is the type named by S's associated result_type;
(2.2)
q is a value of type S and r is a value of type S or const S;
(2.3)
ib and ie are input iterators with an unsigned integer value_type of at least 32 bits;
(2.4)
rb and re are mutable random access iterators with an unsigned integer value_type of at least 32 bits;
(2.5)
ob is an output iterator; and
(2.6)
il is a value of type initializer_list<T>.

Table 121: Seed sequence requirements [tab:rand.req.seedseq]

🔗	Expression	Return type	Pre/post-condition	Complexity
🔗	S::result_type	T	T is an unsigned integer type of at least 32 bits.	compile-time
🔗	S()		Creates a seed sequence with the same initial state as all other default-constructed seed sequences of type S.	constant
🔗	S(ib,ie)		Creates a seed sequence having internal state that depends on some or all of the bits of the supplied sequence [ib,ie).	$O (ie - ib)$
🔗	S(il)		Same as S(il.begin(), il.end()).	same as S(il.begin(), il.end())
🔗	q.generate(rb,re)	void	Does nothing if rb == re. Otherwise, fills the supplied sequence [rb,re) with 32-bit quantities that depend on the sequence supplied to the constructor and possibly also depend on the history of generate's previous invocations.	$O (re - rb)$
🔗	r.size()	size_t	The number of 32-bit units that would be copied by a call to r.param.	constant
🔗	r.param(ob)	void	Copies to the given destination a sequence of 32-bit units that can be provided to the constructor of a second object of type S, and that would reproduce in that second object a state indistinguishable from the state of the first object.	$O (r.size())$

29.5.3.3 Uniform random bit generator requirements [rand.req.urng]

A uniform random bit generator g of type G is a function object returning unsigned integer values such that each value in the range of possible results has (ideally) equal probability of being returned.

[Note 1:

The degree to which g's results approximate the ideal is often determined statistically.

— end note]

template<class G> concept uniform_random_bit_generator = invocable<G&> && unsigned_integral<invoke_result_t<G&>> && requires { { G::min() } -> same_as<invoke_result_t<G&>>; { G::max() } -> same_as<invoke_result_t<G&>>; requires bool_constant<(G::min() < G::max())>::value; };

Let g be an object of type G.

G models uniform_random_bit_generator only if

(2.1)
G::min() <= g(),
(2.2)
g() <= G::max(), and
(2.3)
g() has amortized constant complexity.

A class G meets the uniform random bit generator requirements if G models uniform_random_bit_generator, invoke_result_t<G&> is an unsigned integer type ([basic.fundamental]), and G provides a nested typedef-name result_type that denotes the same type as invoke_result_t<G&>.

29.5.3.4 Random number engine requirements [rand.req.eng]

A random number engine (commonly shortened to engine) e of type E is a uniform random bit generator that additionally meets the requirements (e.g., for seeding and for input/output) specified in this subclause.

At any given time, e has a state e

_{i}

for some integer i ≥ 0.

Upon construction, e has an initial state e

_{0}

An engine's state may be established via a constructor, a seed function, assignment, or a suitable operator>>.

E's specification shall define:

(3.1)
the size of E's state in multiples of the size of result_type, given as an integral constant expression;
(3.2)
the transition algorithm TA by which e's state e $_{i}$ is advanced to its successor state e $_{i + 1}$ ; and
(3.3)
the generation algorithm GA by which an engine's state is mapped to a value of type result_type.

A class E that meets the requirements of a uniform random bit generator also meets the requirements of a random number engine if the expressions shown in Table 122 are valid and have the indicated semantics, and if E also meets all other requirements of [rand.req.eng].

In Table 122 and throughout this subclause:

(4.1)
T is the type named by E's associated result_type;
(4.2)
e is a value of E, v is an lvalue of E, x and y are (possibly const) values of E;
(4.3)
s is a value of T;
(4.4)
q is an lvalue meeting the requirements of a seed sequence;
(4.5)
z is a value of type unsigned long long;
(4.6)
os is an lvalue of the type of some class template specialization basic_ostream<charT, traits>; and
(4.7)
is is an lvalue of the type of some class template specialization basic_istream<charT, traits>;

where charT and traits are constrained according to [strings] and [input.output].

Table 122: Random number engine requirements [tab:rand.req.eng]

🔗	Expression	Return type	Pre/post-condition	Complexity
🔗	E()		Creates an engine with the same initial state as all other default-constructed engines of type E.	$O (size of state)$
🔗	E(x)		Creates an engine that compares equal to x.	$O (size of state)$
🔗	E(s)		Creates an engine with initial state determined by s.	$O (size of state)$
🔗	E(q)246		Creates an engine with an initial state that depends on a sequence produced by one call to q.generate.	same as complexity of q.generate called on a sequence whose length is size of state
🔗	e.seed()	void	Postconditions: e == E().	same as E()
🔗	e.seed(s)	void	Postconditions: e == E(s).	same as E(s)
🔗	e.seed(q)	void	Postconditions: e == E(q).	same as E(q)
🔗	e()	T	Advances e's state e $_{i}$ to e $_{i + 1}$ $= T A ($ e $_{i}$ ) and returns GA(e $_{i}$ ).	per [rand.req.urng]
🔗	e.discard(z)247	void	Advances e's state e $_{i}$ to $e_{i + z}$ by any means equivalent to z consecutive calls e().	no worse than the complexity of z consecutive calls e()
🔗	x == y	bool	This operator is an equivalence relation. With $S_{x}$ and $S_{y}$ as the infinite sequences of values that would be generated by repeated future calls to x() and y(), respectively, returns true if $S_{x} = S_{y}$ ; else returns false.	$O (size of state)$
🔗	x != y	bool	!(x == y).	$O (size of state)$
🔗	os << x	reference to the type of os	With os.fmtflags set to ios_base::dec\|ios_base::left and the fill character set to the space character, writes to os the textual representation of x's current state. In the output, adjacent numbers are separated by one or more space characters. Postconditions: The os.fmtflags and fill character are unchanged.	$O (size of state)$
🔗	is >> v	reference to the type of is	With is.fmtflags set to ios_base::dec, sets v's state as determined by reading its textual representation from is. If bad input is encountered, ensures that v's state is unchanged by the operation and calls is.setstate(ios_base::failbit) (which may throw ios_base::failure ([iostate.flags])). If a textual representation written via os << x was subsequently read via is >> v, then x == v provided that there have been no intervening invocations of x or of v. Preconditions: is provides a textual representation that was previously written using an output stream whose imbued locale was the same as that of is, and whose type's template specialization arguments charT and traits were respectively the same as those of is. Postconditions: The is.fmtflags are unchanged.	$O (size of state)$

E shall meet the Cpp17CopyConstructible (Table 32) and Cpp17CopyAssignable (Table 34) requirements.

These operations shall each be of complexity no worse than

O (size of state)

246)246)

This constructor (as well as the subsequent corresponding seed() function) can be particularly useful to applications requiring a large number of independent random sequences.

247)247)

This operation is common in user code, and can often be implemented in an engine-specific manner so as to provide significant performance improvements over an equivalent naive loop that makes z consecutive calls e().

29.5.3.5 Random number engine adaptor requirements [rand.req.adapt]

A random number engine adaptor (commonly shortened to adaptor) a of type A is a random number engine that takes values produced by some other random number engine, and applies an algorithm to those values in order to deliver a sequence of values with different randomness properties.

An engine b of type B adapted in this way is termed a base engine in this context.

The expression a.base() shall be valid and shall return a const reference to a's base engine.

The requirements of a random number engine type shall be interpreted as follows with respect to a random number engine adaptor type.

🔗

A::A();

Effects: The base engine is initialized as if by its default constructor.

🔗

bool operator==(const A& a1, const A& a2);

Returns: true if a1's base engine is equal to a2's base engine.

Otherwise returns false.

🔗

A::A(result_type s);

Effects: The base engine is initialized with s.

🔗

template<class Sseq> A::A(Sseq& q);

Effects: The base engine is initialized with q.

🔗

void seed();

Effects: With b as the base engine, invokes b.seed().

🔗

void seed(result_type s);

Effects: With b as the base engine, invokes b.seed(s).

🔗

template<class Sseq> void seed(Sseq& q);

Effects: With b as the base engine, invokes b.seed(q).

A shall also meet the following additional requirements:

(10.1)
The complexity of each function shall not exceed the complexity of the corresponding function applied to the base engine.
(10.2)
The state of A shall include the state of its base engine.

The size of A's state shall be no less than the size of the base engine.
(10.3)
Copying A's state (e.g., during copy construction or copy assignment) shall include copying the state of the base engine of A.
(10.4)
The textual representation of A shall include the textual representation of its base engine.

29.5.3.6 Random number distribution requirements [rand.req.dist]

A random number distribution (commonly shortened to distribution) d of type D is a function object returning values that are distributed according to an associated mathematical probability density function p(z) or according to an associated discrete probability function

P (z_{i})

A distribution's specification identifies its associated probability function p(z) or

P (z_{i})

An associated probability function is typically expressed using certain externally-supplied quantities known as the parameters of the distribution.

Such distribution parameters are identified in this context by writing, for example, p(z | a,b) or

P (z_{i} | a, b)

, to name specific parameters, or by writing, for example, p(z |{p}) or

P (z_{i} | {p})

, to denote a distribution's parameters p taken as a whole.

A class D meets the requirements of a random number distribution if the expressions shown in Table 123 are valid and have the indicated semantics, and if D and its associated types also meet all other requirements of [rand.req.dist].

In Table 123 and throughout this subclause,

(3.1)
T is the type named by D's associated result_type;
(3.2)
P is the type named by D's associated param_type;
(3.3)
d is a value of D, and x and y are (possibly const) values of D;
(3.4)
glb and lub are values of T respectively corresponding to the greatest lower bound and the least upper bound on the values potentially returned by d's operator(), as determined by the current values of d's parameters;
(3.5)
p is a (possibly const) value of P;
(3.6)
g, g1, and g2 are lvalues of a type meeting the requirements of a uniform random bit generator;
(3.7)
os is an lvalue of the type of some class template specialization basic_ostream<charT, traits>; and
(3.8)
is is an lvalue of the type of some class template specialization basic_istream<charT, traits>;

where charT and traits are constrained according to [strings] and [input.output].

Table 123: Random number distribution requirements [tab:rand.req.dist]

🔗	Expression	Return type	Pre/post-condition	Complexity
🔗	D::result_type	T	T is an arithmetic type .	compile-time
🔗	D::param_type	P		compile-time
🔗	D()		Creates a distribution whose behavior is indistinguishable from that of any other newly default-constructed distribution of type D.	constant
🔗	D(p)		Creates a distribution whose behavior is indistinguishable from that of a distribution newly constructed directly from the values used to construct p.	same as p's construction
🔗	d.reset()	void	Subsequent uses of d do not depend on values produced by any engine prior to invoking reset.	constant
🔗	x.param()	P	Returns a value p such that D(p).param() == p.	no worse than the complexity of D(p)
🔗	d.param(p)	void	Postconditions: d.param() == p.	no worse than the complexity of D(p)
🔗	d(g)	T	With $p = d.param()$ , the sequence of numbers returned by successive invocations with the same object g is randomly distributed according to the associated p(z \|{p}) or $P (z_{i} \| {p})$ function.	amortized constant number of invocations of g
🔗	d(g,p)	T	The sequence of numbers returned by successive invocations with the same objects g and p is randomly distributed according to the associated p(z \|{p}) or $P (z_{i} \| {p})$ function.	amortized constant number of invocations of g
🔗	x.min()	T	Returns glb.	constant
🔗	x.max()	T	Returns lub.	constant
🔗	x == y	bool	This operator is an equivalence relation. Returns true if x.param() == y.param() and $S_{1} = S_{2}$ , where $S_{1}$ and $S_{2}$ are the infinite sequences of values that would be generated, respectively, by repeated future calls to x(g1) and y(g2) whenever g1 == g2. Otherwise returns false.	constant
🔗	x != y	bool	!(x == y).	same as x == y.
🔗	os << x	reference to the type of os	Writes to os a textual representation for the parameters and the additional internal data of x. Postconditions: The os.fmtflags and fill character are unchanged.
🔗	is >> d	reference to the type of is	Restores from is the parameters and additional internal data of the lvalue d. If bad input is encountered, ensures that d is unchanged by the operation and calls is.setstate(ios_base::failbit) (which may throw ios_base::failure ([iostate.flags])). Preconditions: is provides a textual representation that was previously written using an os whose imbued locale and whose type's template specialization arguments charT and traits were the same as those of is. Postconditions: The is.fmtflags are unchanged.

D shall meet the Cpp17CopyConstructible (Table 32) and Cpp17CopyAssignable (Table 34) requirements.

The sequence of numbers produced by repeated invocations of d(g) shall be independent of any invocation of os << d or of any const member function of D between any of the invocations of d(g).

If a textual representation is written using os << x and that representation is restored into the same or a different object y of the same type using is >> y, repeated invocations of y(g) shall produce the same sequence of numbers as would repeated invocations of x(g).

It is unspecified whether D::param_type is declared as a (nested) class or via a typedef.

In [rand], declarations of D::param_type are in the form of typedefs for convenience of exposition only.

P shall meet the Cpp17CopyConstructible (Table 32), Cpp17CopyAssignable (Table 34), and Cpp17EqualityComparable (Table 28) requirements.

For each of the constructors of D taking arguments corresponding to parameters of the distribution, P shall have a corresponding constructor subject to the same requirements and taking arguments identical in number, type, and default values.

Moreover, for each of the member functions of D that return values corresponding to parameters of the distribution, P shall have a corresponding member function with the identical name, type, and semantics.

P shall have a declaration of the form using distribution_type = D;

29.5.4 Random number engine class templates [rand.eng]

29.5.4.1 General [rand.eng.general]

Each type instantiated from a class template specified in [rand.eng] meets the requirements of a random number engine type.

Except where specified otherwise, the complexity of each function specified in [rand.eng] is constant.

Except where specified otherwise, no function described in [rand.eng] throws an exception.

Every function described in [rand.eng] that has a function parameter q of type Sseq& for a template type parameter named Sseq that is different from type seed_seq throws what and when the invocation of q.generate throws.

Descriptions are provided in [rand.eng] only for engine operations that are not described in [rand.req.eng] or for operations where there is additional semantic information.

In particular, declarations for copy constructors, for copy assignment operators, for streaming operators, and for equality and inequality operators are not shown in the synopses.

Each template specified in [rand.eng] requires one or more relationships, involving the value(s) of its non-type template parameter(s), to hold.

A program instantiating any of these templates is ill-formed if any such required relationship fails to hold.

For every random number engine and for every random number engine adaptor X defined in [rand.eng] and in [rand.adapt]:

(7.1)
if the constructor template<class Sseq> explicit X(Sseq& q); is called with a type Sseq that does not qualify as a seed sequence, then this constructor shall not participate in overload resolution;
(7.2)
if the member function template<class Sseq> void seed(Sseq& q); is called with a type Sseq that does not qualify as a seed sequence, then this function shall not participate in overload resolution.

The extent to which an implementation determines that a type cannot be a seed sequence is unspecified, except that as a minimum a type shall not qualify as a seed sequence if it is implicitly convertible to X::result_type.

29.5.4.2 Class template linear_congruential_engine [rand.eng.lcong]

A linear_congruential_engine random number engine produces unsigned integer random numbers.

The state x

_{i}

of a linear_congruential_engine object x is of size 1 and consists of a single integer.

The transition algorithm is a modular linear function of the form

T A (x_{i}) = (a \cdot x_{i} + c) mod m

; the generation algorithm is

G A (x_{i}) = x_{i + 1}

🔗

namespace std { template<class UIntType, UIntType a, UIntType c, UIntType m> class linear_congruential_engine { public: // types using result_type = UIntType; // engine characteristics static constexpr result_type multiplier = a; static constexpr result_type increment = c; static constexpr result_type modulus = m; static constexpr result_type min() { return c == 0u ? 1u: 0u; } static constexpr result_type max() { return m - 1u; } static constexpr result_type default_seed = 1u; // constructors and seeding functions linear_congruential_engine() : linear_congruential_engine(default_seed) {} explicit linear_congruential_engine(result_type s); template<class Sseq> explicit linear_congruential_engine(Sseq& q); void seed(result_type s = default_seed); template<class Sseq> void seed(Sseq& q); // equality operators friend bool operator==(const linear_congruential_engine& x, const linear_congruential_engine& y); // generating functions result_type operator()(); void discard(unsigned long long z); // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const linear_congruential_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, linear_congruential_engine& x); }; }

If the template parameter m is 0, the modulus m used throughout [rand.eng.lcong] is numeric_limits<result_type>::max() plus 1.

[Note 1:

m need not be representable as a value of type result_type.

— end note]

If the template parameter m is not 0, the following relations shall hold: a < m and c < m.

The textual representation consists of the value of x

_{i}

🔗

explicit linear_congruential_engine(result_type s);

Effects: If

c mod m

is 0 and

s mod m

is 0, sets the engine's state to 1, otherwise sets the engine's state to

s mod m

🔗

template<class Sseq> explicit linear_congruential_engine(Sseq& q);

Effects: With

k = ⌈ \frac{log_{2} m}{32} ⌉

and a an array (or equivalent) of length

k + 3

, invokes q.generate(

a + 0

a + k + 3

) and then computes

S = (\sum_{j = 0}^{k - 1} a_{j + 3} \cdot 2^{32 j}) mod m

c mod m

is 0 and S is 0, sets the engine's state to 1, else sets the engine's state to S.

29.5.4.3 Class template mersenne_twister_engine [rand.eng.mers]

A mersenne_twister_engine random number engine248 produces unsigned integer random numbers in the closed interval

[0, 2^{w} - 1]

The state x

_{i}

of a mersenne_twister_engine object x is of size n and consists of a sequence X of n values of the type delivered by x; all subscripts applied to X are to be taken modulo n.

The transition algorithm employs a twisted generalized feedback shift register defined by shift values n and m, a twist value r, and a conditional xor-mask a.

To improve the uniformity of the result, the bits of the raw shift register are additionally tempered (i.e., scrambled) according to a bit-scrambling matrix defined by values u, d, s, b, t, c, and ℓ.

The state transition is performed as follows:

(2.1)
Concatenate the upper $w - r$ bits of $X_{i - n}$ with the lower r bits of $X_{i + 1 - n}$ to obtain an unsigned integer value Y.
(2.2)
With $α = a \cdot (Y b i t a n d 1)$ , set $X_{i}$ to $X_{i + m - n} x o r (Y r s h i f t 1) x o r α$ .

The sequence X is initialized with the help of an initialization multiplier f.

The generation algorithm determines the unsigned integer values

z_{1}, z_{2}, z_{3}, z_{4}

as follows, then delivers

z_{4}

as its result:

(3.1)
Let $z_{1} = X_{i} x o r ((X_{i} r s h i f t u) b i t a n d d)$ .
(3.2)
Let $z_{2} = z_{1} x o r ((z_{1} {l s h i f t}_{w} s) b i t a n d b)$ .
(3.3)
Let $z_{3} = z_{2} x o r ((z_{2} {l s h i f t}_{w} t) b i t a n d c)$ .
(3.4)
Let $z_{4} = z_{3} x o r (z_{3} r s h i f t ℓ)$ .

🔗

namespace std { template<class UIntType, size_t w, size_t n, size_t m, size_t r, UIntType a, size_t u, UIntType d, size_t s, UIntType b, size_t t, UIntType c, size_t l, UIntType f> class mersenne_twister_engine { public: // types using result_type = UIntType; // engine characteristics static constexpr size_t word_size = w; static constexpr size_t state_size = n; static constexpr size_t shift_size = m; static constexpr size_t mask_bits = r; static constexpr UIntType xor_mask = a; static constexpr size_t tempering_u = u; static constexpr UIntType tempering_d = d; static constexpr size_t tempering_s = s; static constexpr UIntType tempering_b = b; static constexpr size_t tempering_t = t; static constexpr UIntType tempering_c = c; static constexpr size_t tempering_l = l; static constexpr UIntType initialization_multiplier = f; static constexpr result_type min() { return 0; } static constexpr result_type max() { return

2^{w} - 1

; } static constexpr result_type default_seed = 5489u; // constructors and seeding functions mersenne_twister_engine() : mersenne_twister_engine(default_seed) {} explicit mersenne_twister_engine(result_type value); template<class Sseq> explicit mersenne_twister_engine(Sseq& q); void seed(result_type value = default_seed); template<class Sseq> void seed(Sseq& q); // equality operators friend bool operator==(const mersenne_twister_engine& x, const mersenne_twister_engine& y); // generating functions result_type operator()(); void discard(unsigned long long z); // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const mersenne_twister_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, mersenne_twister_engine& x); }; }

The following relations shall hold: 0 < m, m <= n, 2u < w, r <= w, u <= w, s <= w, t <= w, l <= w, w <= numeric_limits<UIntType>::digits, a <= (1u<<w) - 1u, b <= (1u<<w) - 1u, c <= (1u<<w) - 1u, d <= (1u<<w) - 1u, and f <= (1u<<w) - 1u.

The textual representation of x

_{i}

consists of the values of

X_{i - n}, \dots, X_{i - 1}

, in that order.

🔗

explicit mersenne_twister_engine(result_type value);

Effects: Sets

X_{- n}

value mod 2^{w}

Then, iteratively for

i = 1 - n, \dots, - 1

, sets

X_{i}

[f \cdot (X_{i - 1} x o r (X_{i - 1} r s h i f t (w - 2))) + i mod n] mod 2^{w} .

Complexity:

O (n)

🔗

template<class Sseq> explicit mersenne_twister_engine(Sseq& q);

Effects: With

k = ⌈ w / 32 ⌉

and a an array (or equivalent) of length

n \cdot k

, invokes q.generate(

a + 0

a + n \cdot k

) and then, iteratively for

i = - n, \dots, - 1

, sets

X_{i}

(\sum_{j = 0}^{k - 1} a_{k (i + n) + j} \cdot 2^{32 j}) mod 2^{w}

Finally, if the most significant

w - r

bits of

X_{- n}

are zero, and if each of the other resulting

X_{i}

is 0, changes

X_{- n}

2^{w - 1}

248)248)

The name of this engine refers, in part, to a property of its period: For properly-selected values of the parameters, the period is closely related to a large Mersenne prime number.

29.5.4.4 Class template subtract_with_carry_engine [rand.eng.sub]

A subtract_with_carry_engine random number engine produces unsigned integer random numbers.

The state x

_{i}

of a subtract_with_carry_engine object x is of size

O (r)

, and consists of a sequence X of r integer values

0 \leq X_{i} < m = 2^{w}

; all subscripts applied to X are to be taken modulo r.

The state x

_{i}

additionally consists of an integer c (known as the carry) whose value is either 0 or 1.

The state transition is performed as follows:

(3.1)
Let $Y = X_{i - s} - X_{i - r} - c$ .
(3.2)
Set $X_{i}$ to $y = Y mod m$ .

Set c to 1 if $Y < 0$ , otherwise set c to 0.

[Note 1:

This algorithm corresponds to a modular linear function of the form

T A (x_{i}) = (a \cdot x_{i}) mod b

, where b is of the form

m^{r} - m^{s} + 1

and

a = b - (b - 1) / m

— end note]

The generation algorithm is given by

G A (x_{i}) = y

, where y is the value produced as a result of advancing the engine's state as described above.

🔗

namespace std { template<class UIntType, size_t w, size_t s, size_t r> class subtract_with_carry_engine { public: // types using result_type = UIntType; // engine characteristics static constexpr size_t word_size = w; static constexpr size_t short_lag = s; static constexpr size_t long_lag = r; static constexpr result_type min() { return 0; } static constexpr result_type max() { return

m - 1

; } static constexpr uint_least32_t default_seed = 19780503u; // constructors and seeding functions subtract_with_carry_engine() : subtract_with_carry_engine(0u) {} explicit subtract_with_carry_engine(result_type value); template<class Sseq> explicit subtract_with_carry_engine(Sseq& q); void seed(result_type value = 0u); template<class Sseq> void seed(Sseq& q); // equality operators friend bool operator==(const subtract_with_carry_engine& x, const subtract_with_carry_engine& y); // generating functions result_type operator()(); void discard(unsigned long long z); // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const subtract_with_carry_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, subtract_with_carry_engine& x); }; }

The following relations shall hold: 0u < s, s < r, 0 < w, and w <= numeric_limits<UIntType>::digits.

The textual representation consists of the values of

X_{i - r}, \dots, X_{i - 1}

, in that order, followed by c.

🔗

explicit subtract_with_carry_engine(result_type value);

Effects: Sets the values of

X_{- r}, \dots, X_{- 1}

, in that order, as specified below.

X_{- 1}

is then 0, sets c to 1; otherwise sets c to 0.

To set the values

X_{k}

, first construct e, a linear_congruential_engine object, as if by the following definition: linear_congruential_engine<uint_least32_t, 40014u,0u,2147483563u> e(value == 0u ? default_seed : value);

Then, to set each

X_{k}

, obtain new values

z_{0}, \dots, z_{n - 1}

from

n = ⌈ w / 32 ⌉

successive invocations of e.

Set

X_{k}

(\sum_{j = 0}^{n - 1} z_{j} \cdot 2^{32 j}) mod m

Complexity: Exactly

n \cdot r

invocations of e.

🔗

template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);

Effects: With

k = ⌈ w / 32 ⌉

and a an array (or equivalent) of length

r \cdot k

, invokes q.generate(

a + 0

a + r \cdot k

) and then, iteratively for

i = - r, \dots, - 1

, sets

X_{i}

(\sum_{j = 0}^{k - 1} a_{k (i + r) + j} \cdot 2^{32 j}) mod m

X_{- 1}

is then 0, sets c to 1; otherwise sets c to 0.

29.5.4.5 Class template philox_engine [rand.eng.philox]

A philox_engine random number engine produces unsigned integer random numbers in the closed interval [0, m], where

m = 2^{w} - 1

and the template parameter w defines the range of the produced numbers.

The state of a philox_engine object consists of a sequence X of n unsigned integer values of width w, a sequence K of

n / 2

values of result_type, a sequence Y of n values of result_type, and a scalar i, where

(1.1)
X is the interpretation of the unsigned integer counter value $Z : = \sum_{j = 0}^{n - 1} X_{j} \cdot 2^{w j}$ of $n \cdot w$ bits,
(1.2)
K are keys, which are generated once from the seed (see constructors below) and remain constant unless the seed function ([rand.req.eng]) is invoked,
(1.3)
Y stores a batch of output values, and
(1.4)
i is an index for an element of the sequence Y.

The generation algorithm returns

Y_{i}

, the value stored in the

i^{t h}

element of Y after applying the transition algorithm.

The state transition is performed as if by the following algorithm: i = i + 1 if (i == n) { Y = Philox(K, X) // see below Z = Z + 1 i = 0 }

The Philox function maps the length-

n / 2

sequence K and the length-n sequence X into a length-n output sequence Y.

Philox applies an r-round substitution-permutation network to the values in X.

A single round of the generation algorithm performs the following steps:

(4.1)
The output sequence $X^{'}$ of the previous round (X in case of the first round) is permuted to obtain the intermediate state V: $V_{j} = X_{f_{n} (j)}^{'}$ where $j = 0, \dots, n - 1$ and $f_{n} (j)$ is defined in Table 124.
Table 124: Values for the word permutation $f_{n} (j)$ [tab:rand.eng.philox.f]
🔗
$f_{n} (j)$
j
🔗
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
🔗
n
2
0
1
🔗
4
0
3
2
1
🔗
8
2
1
4
7
6
5
0
3
🔗
16
0
9
2
13
6
11
4
15
10
7
12
3
14
5
8
1
🔗

[Note 1:
For $n = 2$ the sequence is not permuted.
— end note]
(4.2)
The following computations are applied to the elements of the V sequence: $X_{2 k + 0} = mullo (V_{2 k + 1}, M_{k}, w)$ $X_{2 k + 1} = mulhi (V_{2 k + 1}, M_{k}, w) x o r {k e y}_{k}^{q} x o r V_{2 k}$ where:
- (4.2.1)
  mullo(a, b, w) is the low half of the modular multiplication of a and b: $(a \cdot b) mod 2^{w}$ ,
- (4.2.2)
  mulhi(a, b, w) is the high half of the modular multiplication of a and b: $(⌊ (a \cdot b) / 2^{w} ⌋)$ ,
- (4.2.3)
  $k = 0, \dots, n / 2 - 1$ is the index in the sequences,
- (4.2.4)
  $q = 0, \dots, r - 1$ is the index of the round,
- (4.2.5)
  ${k e y}_{k}^{q}$ is the $k^{th}$ round key for round q, ${k e y}_{k}^{q} : = (K_{k} + q \cdot C_{k}) mod 2^{w}$ ,
- (4.2.6)
  $K_{k}$ are the elements of the key sequence K,
- (4.2.7)
  $M_{k}$ is multipliers[k], and
- (4.2.8)
  $C_{k}$ is round_consts[k].

After r applications of the single-round function, Philox returns the sequence

Y = X^{'}

🔗

namespace std { template<class UIntType, size_t w, size_t n, size_t r, UIntType... consts> class philox_engine { static constexpr size_t array-size = n / 2; // exposition only public: // types using result_type = UIntType; // engine characteristics static constexpr size_t word_size = w; static constexpr size_t word_count = n; static constexpr size_t round_count = r; static constexpr array<result_type, array-size> multipliers; static constexpr array<result_type, array-size> round_consts; static constexpr result_type min() { return 0; } static constexpr result_type max() { return m - 1; } static constexpr result_type default_seed = 20111115u; // constructors and seeding functions philox_engine() : philox_engine(default_seed) {} explicit philox_engine(result_type value); template<class Sseq> explicit philox_engine(Sseq& q); void seed(result_type value = default_seed); template<class Sseq> void seed(Sseq& q); void set_counter(const array<result_type, n>& counter); // equality operators friend bool operator==(const philox_engine& x, const philox_engine& y); // generating functions result_type operator()(); void discard(unsigned long long z); // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const philox_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, philox_engine& x); }; }

Mandates:

(6.1)
sizeof...(consts) == n is true, and
(6.2)
n == 2 || n == 4 || n == 8 || n == 16 is true, and
(6.3)
0 < r is true, and
(6.4)
0 < w && w <= numeric_limits<UIntType>::digits is true.

The template parameter pack consts represents the

M_{k}

and

C_{k}

constants which are grouped as follows:

[M_{0}, C_{0}, M_{1}, C_{1}, M_{2}, C_{2}, \dots, M_{n / 2 - 1}, C_{n / 2 - 1}]

The textual representation consists of the values of

K_{0}, \dots, K_{n / 2 - 1}, X_{0}, \dots, X_{n - 1}, i

, in that order.

[Note 2:

The stream extraction operator can reconstruct Y from K and X, as needed.

— end note]

🔗

explicit philox_engine(result_type value);

Effects: Sets the

K_{0}

element of sequence K to

value mod 2^{w}

All elements of sequences X and K (except

K_{0}

) are set to 0.

The value of i is set to

n - 1

🔗

template<class Sseq> explicit philox_engine(Sseq& q);

Effects: With

p = ⌈ w / 32 ⌉

and an array (or equivalent) a of length

(n / 2) \cdot p

, invokes q.generate(a + 0, a + n / 2 * p) and then iteratively for

k = 0, \dots, n / 2 - 1

, sets

K_{k}

(\sum_{j = 0}^{p - 1} a_{k p + j} \cdot 2^{32 j}) mod 2^{w}

All elements of sequence X are set to 0.

The value of i is set to

n - 1

🔗

void set_counter(const array<result_type, n>& c);

Effects: For

j = 0, \dots, n - 1

sets

X_{j}

C_{n - 1 - j} mod 2^{w}

The value of i is set to

n - 1

[Note 3:

The counter is the value Z introduced at the beginning of this subclause.

— end note]

29.5.5 Random number engine adaptor class templates [rand.adapt]

29.5.5.1 General [rand.adapt.general]

Each type instantiated from a class template specified in [rand.adapt] meets the requirements of a random number engine adaptor type.

Except where specified otherwise, the complexity of each function specified in [rand.adapt] is constant.

Except where specified otherwise, no function described in [rand.adapt] throws an exception.

Every function described in [rand.adapt] that has a function parameter q of type Sseq& for a template type parameter named Sseq that is different from type seed_seq throws what and when the invocation of q.generate throws.

Descriptions are provided in [rand.adapt] only for adaptor operations that are not described in subclause [rand.req.adapt] or for operations where there is additional semantic information.

In particular, declarations for copy constructors, for copy assignment operators, for streaming operators, and for equality and inequality operators are not shown in the synopses.

Each template specified in [rand.adapt] requires one or more relationships, involving the value(s) of its non-type template parameter(s), to hold.

A program instantiating any of these templates is ill-formed if any such required relationship fails to hold.

29.5.5.2 Class template discard_block_engine [rand.adapt.disc]

A discard_block_engine random number engine adaptor produces random numbers selected from those produced by some base engine e.

The state x

_{i}

of a discard_block_engine engine adaptor object x consists of the state e

_{i}

of its base engine e and an additional integer n.

The size of the state is the size of e's state plus 1.

The transition algorithm discards all but

r > 0

values from each block of p ≥ r values delivered by e.

The state transition is performed as follows: If n ≥ r, advance the state of e from e

_{i}

to e

_{i + p - r}

and set n to 0.

In any case, then increment n and advance e's then-current state e

_{j}

to e

_{j + 1}

The generation algorithm yields the value returned by the last invocation of e() while advancing e's state as described above.

🔗

namespace std { template<class Engine, size_t p, size_t r> class discard_block_engine { public: // types using result_type = typename Engine::result_type; // engine characteristics static constexpr size_t block_size = p; static constexpr size_t used_block = r; static constexpr result_type min() { return Engine::min(); } static constexpr result_type max() { return Engine::max(); } // constructors and seeding functions discard_block_engine(); explicit discard_block_engine(const Engine& e); explicit discard_block_engine(Engine&& e); explicit discard_block_engine(result_type s); template<class Sseq> explicit discard_block_engine(Sseq& q); void seed(); void seed(result_type s); template<class Sseq> void seed(Sseq& q); // equality operators friend bool operator==(const discard_block_engine& x, const discard_block_engine& y); // generating functions result_type operator()(); void discard(unsigned long long z); // property functions const Engine& base() const noexcept { return e; } // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const discard_block_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, discard_block_engine& x); private: Engine e; // exposition only size_t n; // exposition only }; }

The following relations shall hold: 0 < r and r <= p.

The textual representation consists of the textual representation of e followed by the value of n.

In addition to its behavior pursuant to subclause [rand.req.adapt], each constructor that is not a copy constructor sets n to 0.

29.5.5.3 Class template independent_bits_engine [rand.adapt.ibits]

An independent_bits_engine random number engine adaptor combines random numbers that are produced by some base engine e, so as to produce random numbers with a specified number of bits w.

The state x

_{i}

of an independent_bits_engine engine adaptor object x consists of the state e

_{i}

of its base engine e; the size of the state is the size of e's state.

The transition and generation algorithms are described in terms of the following integral constants:

(2.1)
Let $R = e.max() - e.min() + 1$ and $m = ⌊ log_{2} R ⌋$ .
(2.2)
With n as determined below, let $w_{0} = ⌊ w / n ⌋$ , $n_{0} = n - w mod n$ , $y_{0} = 2^{w_{0}} ⌊ R / 2^{w_{0}} ⌋$ , and $y_{1} = 2^{w_{0} + 1} ⌊ R / 2^{w_{0} + 1} ⌋$ .
(2.3)
Let $n = ⌈ w / m ⌉$ if and only if the relation $R - y_{0} \leq ⌊ y_{0} / n ⌋$ holds as a result.

Otherwise let $n = 1 + ⌈ w / m ⌉$ .

[Note 1:

The relation

w = n_{0} w_{0} + (n - n_{0}) (w_{0} + 1)

always holds.

— end note]

The transition algorithm is carried out by invoking e() as often as needed to obtain

n_{0}

values less than

y_{0} + e.min()

and

n - n_{0}

values less than

y_{1} + e.min()

The generation algorithm uses the values produced while advancing the state as described above to yield a quantity S obtained as if by the following algorithm: S = 0; for (k = 0;

k \neq n_{0}

; k += 1) { do u = e() - e.min(); while (

u \geq y_{0}

); S =

2^{w_{0}} \cdot S + u mod 2^{w_{0}}

; } for (k =

n_{0}

; k ≠ n; k += 1) { do u = e() - e.min(); while (

u \geq y_{1}

); S =

2^{w_{0} + 1} \cdot S + u mod 2^{w_{0} + 1}

; }

🔗

namespace std { template<class Engine, size_t w, class UIntType> class independent_bits_engine { public: // types using result_type = UIntType; // engine characteristics static constexpr result_type min() { return 0; } static constexpr result_type max() { return

2^{w} - 1

; } // constructors and seeding functions independent_bits_engine(); explicit independent_bits_engine(const Engine& e); explicit independent_bits_engine(Engine&& e); explicit independent_bits_engine(result_type s); template<class Sseq> explicit independent_bits_engine(Sseq& q); void seed(); void seed(result_type s); template<class Sseq> void seed(Sseq& q); // equality operators friend bool operator==(const independent_bits_engine& x, const independent_bits_engine& y); // generating functions result_type operator()(); void discard(unsigned long long z); // property functions const Engine& base() const noexcept { return e; } // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const independent_bits_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, independent_bits_engine& x); private: Engine e; // exposition only }; }

The following relations shall hold: 0 < w and w <= numeric_limits<result_type>::digits.

The textual representation consists of the textual representation of e.

29.5.5.4 Class template shuffle_order_engine [rand.adapt.shuf]

A shuffle_order_engine random number engine adaptor produces the same random numbers that are produced by some base engine e, but delivers them in a different sequence.

The state x

_{i}

of a shuffle_order_engine engine adaptor object x consists of the state e

_{i}

of its base engine e, an additional value Y of the type delivered by e, and an additional sequence V of k values also of the type delivered by e.

The size of the state is the size of e's state plus

k + 1

The transition algorithm permutes the values produced by e.

The state transition is performed as follows:

(2.1)
Calculate an integer $j = ⌊ \frac{k \cdot (Y - e_{min})}{e_{max} - e_{min} + 1} ⌋$ .
(2.2)
Set Y to $V_{j}$ and then set $V_{j}$ to e().

The generation algorithm yields the last value of Y produced while advancing e's state as described above.

🔗

namespace std { template<class Engine, size_t k> class shuffle_order_engine { public: // types using result_type = typename Engine::result_type; // engine characteristics static constexpr size_t table_size = k; static constexpr result_type min() { return Engine::min(); } static constexpr result_type max() { return Engine::max(); } // constructors and seeding functions shuffle_order_engine(); explicit shuffle_order_engine(const Engine& e); explicit shuffle_order_engine(Engine&& e); explicit shuffle_order_engine(result_type s); template<class Sseq> explicit shuffle_order_engine(Sseq& q); void seed(); void seed(result_type s); template<class Sseq> void seed(Sseq& q); // equality operators friend bool operator==(const shuffle_order_engine& x, const shuffle_order_engine& y); // generating functions result_type operator()(); void discard(unsigned long long z); // property functions const Engine& base() const noexcept { return e; } // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const shuffle_order_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, shuffle_order_engine& x); private: Engine e; // exposition only result_type V[k]; // exposition only result_type Y; // exposition only }; }

The following relation shall hold: 0 < k.

The textual representation consists of the textual representation of e, followed by the k values of V, followed by the value of Y.

In addition to its behavior pursuant to subclause [rand.req.adapt], each constructor that is not a copy constructor initializes V[0], …, V[k-1] and Y, in that order, with values returned by successive invocations of e().

29.5.6 Engines and engine adaptors with predefined parameters [rand.predef]

🔗

using minstd_rand0 =
      linear_congruential_engine<uint_fast32_t, 16'807, 0, 2'147'483'647>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type minstd_rand0 produces the value 1043618065.

🔗

using minstd_rand =
      linear_congruential_engine<uint_fast32_t, 48'271, 0, 2'147'483'647>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type minstd_rand produces the value 399268537.

🔗

using mt19937 =
      mersenne_twister_engine<uint_fast32_t, 32, 624, 397, 31,
       0x9908'b0df, 11, 0xffff'ffff, 7, 0x9d2c'5680, 15, 0xefc6'0000, 18, 1'812'433'253>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type mt19937 produces the value 4123659995.

🔗

using mt19937_64 =
      mersenne_twister_engine<uint_fast64_t, 64, 312, 156, 31,
       0xb502'6f5a'a966'19e9, 29, 0x5555'5555'5555'5555, 17,
       0x71d6'7fff'eda6'0000, 37, 0xfff7'eee0'0000'0000, 43, 6'364'136'223'846'793'005>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type mt19937_64 produces the value 9981545732273789042.

🔗

using ranlux24_base =
      subtract_with_carry_engine<uint_fast32_t, 24, 10, 24>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type ranlux24_base produces the value 7937952.

🔗

using ranlux48_base =
      subtract_with_carry_engine<uint_fast64_t, 48, 5, 12>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type ranlux48_base produces the value 61839128582725.

🔗

using ranlux24 = discard_block_engine<ranlux24_base, 223, 23>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type ranlux24 produces the value 9901578.

🔗

using ranlux48 = discard_block_engine<ranlux48_base, 389, 11>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type ranlux48 produces the value 249142670248501.

🔗

using knuth_b = shuffle_order_engine<minstd_rand0,256>;

Required behavior: The

10000^{th}

consecutive invocation of a default-constructed object of type knuth_b produces the value 1112339016.

🔗

using default_random_engine = implementation-defined;

Remarks: The choice of engine type named by this typedef is implementation-defined.

[Note 1:

The implementation can select this type on the basis of performance, size, quality, or any combination of such factors, so as to provide at least acceptable engine behavior for relatively casual, inexpert, and/or lightweight use.

Because different implementations can select different underlying engine types, code that uses this typedef need not generate identical sequences across implementations.

— end note]

🔗

using philox4x32 =
      philox_engine<uint_fast32_t, 32, 4, 10,
       0xD2511F53, 0x9E3779B9, 0xCD9E8D57, 0xBB67AE85>;

Required behavior: The

10000^{th}

consecutive invocation a default-constructed object of type philox4x32 produces the value 1955073260.

🔗

using philox4x64 =
      philox_engine<uint_fast64_t, 64, 4, 10,
       0xD2E7470EE14C6C93, 0x9E3779B97F4A7C15, 0xCA5A826395121157, 0xBB67AE8584CAA73B>;

Required behavior: The

10000^{th}

consecutive invocation a default-constructed object of type philox4x64 produces the value 3409172418970261260.

29.5.7 Class random_device [rand.device]

A random_device uniform random bit generator produces nondeterministic random numbers.

If implementation limitations prevent generating nondeterministic random numbers, the implementation may employ a random number engine.

🔗

namespace std { class random_device { public: // types using result_type = unsigned int; // generator characteristics static constexpr result_type min() { return numeric_limits<result_type>::min(); } static constexpr result_type max() { return numeric_limits<result_type>::max(); } // constructors random_device() : random_device(implementation-defined) {} explicit random_device(const string& token); // generating functions result_type operator()(); // property functions double entropy() const noexcept; // no copy functions random_device(const random_device&) = delete; void operator=(const random_device&) = delete; }; }

🔗

explicit random_device(const string& token);

Throws: A value of an implementation-defined type derived from exception if the random_device cannot be initialized.

Remarks: The semantics of the token parameter and the token value used by the default constructor are implementation-defined.249

🔗

double entropy() const noexcept;

Returns: If the implementation employs a random number engine, returns 0.0.

Otherwise, returns an entropy estimate250 for the random numbers returned by operator(), in the range min() to

log_{2} (max() + 1)

🔗

result_type operator()();

Returns: A nondeterministic random value, uniformly distributed between min() and max() (inclusive).

It is implementation-defined how these values are generated.

Throws: A value of an implementation-defined type derived from exception if a random number cannot be obtained.

249)249)

The parameter is intended to allow an implementation to differentiate between different sources of randomness.

250)250)

If a device has n states whose respective probabilities are

P_{0}, \dots, P_{n - 1}

, the device entropy S is defined as

S = - \sum_{i = 0}^{n - 1} P_{i} \cdot log P_{i}

29.5.8 Utilities [rand.util]

29.5.8.1 Class seed_seq [rand.util.seedseq]

🔗

namespace std { class seed_seq { public: // types using result_type = uint_least32_t; // constructors seed_seq() noexcept; template<class T> seed_seq(initializer_list<T> il); template<class InputIterator> seed_seq(InputIterator begin, InputIterator end); // generating functions template<class RandomAccessIterator> void generate(RandomAccessIterator begin, RandomAccessIterator end); // property functions size_t size() const noexcept; template<class OutputIterator> void param(OutputIterator dest) const; // no copy functions seed_seq(const seed_seq&) = delete; void operator=(const seed_seq&) = delete; private: vector<result_type> v; // exposition only }; }

🔗

seed_seq() noexcept;

Postconditions: v.empty() is true.

🔗

template<class T>
  seed_seq(initializer_list<T> il);

Constraints: T is an integer type.

Effects: Same as seed_seq(il.begin(), il.end()).

🔗

template<class InputIterator>
  seed_seq(InputIterator begin, InputIterator end);

Mandates: iterator_traits<InputIterator>::value_type is an integer type.

Preconditions: InputIterator meets the Cpp17InputIterator requirements ([input.iterators]).

Effects: Initializes v by the following algorithm: for (InputIterator s = begin; s != end; ++s) v.push_back((*s)

mod 2^{32}

);

🔗

template<class RandomAccessIterator>
  void generate(RandomAccessIterator begin, RandomAccessIterator end);

Mandates: iterator_traits<RandomAccessIterator>::value_type is an unsigned integer type capable of accommodating 32-bit quantities.

Preconditions: RandomAccessIterator meets the Cpp17RandomAccessIterator requirements ([random.access.iterators]) and the requirements of a mutable iterator.

Effects: Does nothing if begin == end.

Otherwise, with

s = v.size()

and

n = end - begin

, fills the supplied range [begin,end) according to the following algorithm in which each operation is to be carried out modulo

2^{32}

, each indexing operator applied to begin is to be taken modulo n, and T(x) is defined as x xor(x rshift27):

(9.1)
By way of initialization, set each element of the range to the value 0x8b8b8b8b.

Additionally, for use in subsequent steps, let $p = (n - t) / 2$ and let $q = p + t$ , where
$t = (n \geq 623) ? 11 : (n \geq 68) ? 7 : (n \geq 39) ? 5 : (n \geq 7) ? 3 : (n - 1) / 2;$
(9.2)
With m as the larger of $s + 1$ and n, transform the elements of the range: iteratively for $k = 0, \dots, m - 1$ , calculate values
$\begin{matrix} r_{1} & = & 1664525 \cdot T (begin[k] x o r begin[k + p] x o r begin[k - 1]) r_{2} & = & r_{1} + ⎧ ⎪ ⎨ ⎪ ⎩ \begin{matrix} s & , k = 0 k mod n + v[k - 1] & , 0 < k \leq s k mod n & , s < k \end{matrix} \end{matrix}$ and, in order, increment begin[ $k + p$ ] by $r_{1}$ , increment begin[ $k + q$ ] by $r_{2}$ , and set begin[k] to $r_{2}$ .
(9.3)
Transform the elements of the range again, beginning where the previous step ended: iteratively for $k = m, \dots, m + n - 1$ , calculate values
$\begin{matrix} r_{3} & = & 1566083941 \cdot T (begin[k] + begin[k + p] + begin[k - 1]) r_{4} & = & r_{3} - (k mod n) \end{matrix}$ and, in order, update begin[ $k + p$ ] by xoring it with $r_{3}$ , update begin[ $k + q$ ] by xoring it with $r_{4}$ , and set begin[k] to $r_{4}$ .

Throws: What and when RandomAccessIterator operations of begin and end throw.

🔗

size_t size() const noexcept;

Returns: The number of 32-bit units that would be returned by a call to param().

Complexity: Constant time.

🔗

template<class OutputIterator>
  void param(OutputIterator dest) const;

Mandates: Values of type result_type are writable ([iterator.requirements.general]) to dest.

Preconditions: OutputIterator meets the Cpp17OutputIterator requirements ([output.iterators]).

Effects: Copies the sequence of prepared 32-bit units to the given destination, as if by executing the following statement: copy(v.begin(), v.end(), dest);

Throws: What and when OutputIterator operations of dest throw.

29.5.8.2 Function template generate_canonical [rand.util.canonical]

🔗

template<class RealType, size_t digits, class URBG>
  RealType generate_canonical(URBG& g);

Let

(1.1)
r be numeric_limits<RealType>::radix,
(1.2)
R be $g.max() - g.min() + 1$ ,
(1.3)
d be the smaller of digits and numeric_limits<RealType>::digits,251
(1.4)
k be the smallest integer such that $R^{k} \geq r^{d}$ , and
(1.5)
x be $⌊ R^{k} / r^{d} ⌋$ .

An attempt is k invocations of g() to obtain values

g_{0}, \dots, g_{k - 1}

, respectively, and the calculation of a quantity S given by Formula 29.1:

\begin{matrix} S = k - 1 \sum i = 0 (g_{i} - g.min()) \cdot R^{i} \\ (29.1) \end{matrix}

Effects: Attempts are made until

S < x r^{d}

[Note 1:

When R is a power of r, precisely one attempt is made.

— end note]

Returns:

⌊ S / x ⌋ / r^{d}

[Note 2:

The return value c satisfies

0 \leq c < 1

— end note]

Throws: What and when g throws.

Complexity: Exactly k invocations of g per attempt.

[Note 3:

If the values

g_{i}

produced by g are uniformly distributed, the instantiation's results are distributed as uniformly as possible.

Obtaining a value in this way can be a useful step in the process of transforming a value generated by a uniform random bit generator into a value that can be delivered by a random number distribution.

— end note]

[Note 4:

When R is a power of r, an implementation can avoid using an arithmetic type that is wider than the output when computing S.

— end note]

251)251)

d is introduced to avoid any attempt to produce more bits of randomness than can be held in RealType.

29.5.9 Random number distribution class templates [rand.dist]

29.5.9.1 General [rand.dist.general]

Each type instantiated from a class template specified in [rand.dist] meets the requirements of a random number distribution type.

Descriptions are provided in [rand.dist] only for distribution operations that are not described in [rand.req.dist] or for operations where there is additional semantic information.

In particular, declarations for copy constructors, for copy assignment operators, for streaming operators, and for equality and inequality operators are not shown in the synopses.

The algorithms for producing each of the specified distributions are implementation-defined.

The value of each probability density function p(z) and of each discrete probability function

P (z_{i})

specified in this subclause is 0 everywhere outside its stated domain.

29.5.9.2 Uniform distributions [rand.dist.uni]

29.5.9.2.1 Class template uniform_int_distribution [rand.dist.uni.int]

A uniform_int_distribution random number distribution produces random integers i, a ≤ i ≤ b, distributed according to the constant discrete probability function in Formula 29.2 .

\begin{matrix} P (i | a, b) = 1 / (b - a + 1) \\ (29.2) \end{matrix}

🔗

namespace std { template<class IntType = int> class uniform_int_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructors and reset functions uniform_int_distribution() : uniform_int_distribution(0) {} explicit uniform_int_distribution(IntType a, IntType b = numeric_limits<IntType>::max()); explicit uniform_int_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const uniform_int_distribution& x, const uniform_int_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions result_type a() const; result_type b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const uniform_int_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, uniform_int_distribution& x); }; }

🔗

explicit uniform_int_distribution(IntType a, IntType b = numeric_limits<IntType>::max());

Preconditions: a ≤ b.

Remarks: a and b correspond to the respective parameters of the distribution.

🔗

result_type a() const;

Returns: The value of the a parameter with which the object was constructed.

🔗

result_type b() const;

Returns: The value of the b parameter with which the object was constructed.

29.5.9.2.2 Class template uniform_real_distribution [rand.dist.uni.real]

A uniform_real_distribution random number distribution produces random numbers x,

a \leq x < b

, distributed according to the constant probability density function in Formula 29.3 .

\begin{matrix} p (x | a, b) = 1 / (b - a) \\ (29.3) \end{matrix}

[Note 1:

This implies that p(x | a,b) is undefined when a == b.

— end note]

🔗

namespace std { template<class RealType = double> class uniform_real_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructors and reset functions uniform_real_distribution() : uniform_real_distribution(0.0) {} explicit uniform_real_distribution(RealType a, RealType b = 1.0); explicit uniform_real_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const uniform_real_distribution& x, const uniform_real_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions result_type a() const; result_type b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const uniform_real_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, uniform_real_distribution& x); }; }

🔗

explicit uniform_real_distribution(RealType a, RealType b = 1.0);

Preconditions: a ≤ b and

b - a \leq numeric_limits<RealType>::max()

Remarks: a and b correspond to the respective parameters of the distribution.

🔗

result_type a() const;

Returns: The value of the a parameter with which the object was constructed.

🔗

result_type b() const;

Returns: The value of the b parameter with which the object was constructed.

29.5.9.3 Bernoulli distributions [rand.dist.bern]

29.5.9.3.1 Class bernoulli_distribution [rand.dist.bern.bernoulli]

A bernoulli_distribution random number distribution produces bool values b distributed according to the discrete probability function in Formula 29.4 .

\begin{matrix} P (b | p) = {\begin{matrix} p & if b = true 1 - p & if b = false \end{matrix} \\ (29.4) \end{matrix}

🔗

namespace std { class bernoulli_distribution { public: // types using result_type = bool; using param_type = unspecified; // constructors and reset functions bernoulli_distribution() : bernoulli_distribution(0.5) {} explicit bernoulli_distribution(double p); explicit bernoulli_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const bernoulli_distribution& x, const bernoulli_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions double p() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const bernoulli_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, bernoulli_distribution& x); }; }

🔗

explicit bernoulli_distribution(double p);

Preconditions: 0 ≤ p ≤ 1.

Remarks: p corresponds to the parameter of the distribution.

🔗

double p() const;

Returns: The value of the p parameter with which the object was constructed.

29.5.9.3.2 Class template binomial_distribution [rand.dist.bern.bin]

A binomial_distribution random number distribution produces integer values i ≥ 0 distributed according to the discrete probability function in Formula 29.5 .

\begin{matrix} P (i | t, p) = (\frac{t}{i}) \cdot p^{i} \cdot (1 - p)^{t - i} \\ (29.5) \end{matrix}

🔗

namespace std { template<class IntType = int> class binomial_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructors and reset functions binomial_distribution() : binomial_distribution(1) {} explicit binomial_distribution(IntType t, double p = 0.5); explicit binomial_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const binomial_distribution& x, const binomial_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions IntType t() const; double p() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const binomial_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, binomial_distribution& x); }; }

🔗

explicit binomial_distribution(IntType t, double p = 0.5);

Preconditions: 0 ≤ p ≤ 1 and 0 ≤ t.

Remarks: t and p correspond to the respective parameters of the distribution.

🔗

IntType t() const;

Returns: The value of the t parameter with which the object was constructed.

🔗

double p() const;

Returns: The value of the p parameter with which the object was constructed.

29.5.9.3.3 Class template geometric_distribution [rand.dist.bern.geo]

A geometric_distribution random number distribution produces integer values i ≥ 0 distributed according to the discrete probability function in Formula 29.6 .

\begin{matrix} P (i | p) = p \cdot (1 - p)^{i} \\ (29.6) \end{matrix}

🔗

namespace std { template<class IntType = int> class geometric_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructors and reset functions geometric_distribution() : geometric_distribution(0.5) {} explicit geometric_distribution(double p); explicit geometric_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const geometric_distribution& x, const geometric_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions double p() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const geometric_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, geometric_distribution& x); }; }

🔗

explicit geometric_distribution(double p);

Preconditions:

0 < p < 1

Remarks: p corresponds to the parameter of the distribution.

🔗

double p() const;

Returns: The value of the p parameter with which the object was constructed.

29.5.9.3.4 Class template negative_binomial_distribution [rand.dist.bern.negbin]

A negative_binomial_distribution random number distribution produces random integers i ≥ 0 distributed according to the discrete probability function in Formula 29.7 .

\begin{matrix} P (i | k, p) = (\frac{k + i - 1}{i}) \cdot p^{k} \cdot (1 - p)^{i} \\ (29.7) \end{matrix}

[Note 1:

This implies that P(i | k,p) is undefined when p == 1.

— end note]

🔗

namespace std { template<class IntType = int> class negative_binomial_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructor and reset functions negative_binomial_distribution() : negative_binomial_distribution(1) {} explicit negative_binomial_distribution(IntType k, double p = 0.5); explicit negative_binomial_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const negative_binomial_distribution& x, const negative_binomial_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions IntType k() const; double p() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const negative_binomial_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, negative_binomial_distribution& x); }; }

🔗

explicit negative_binomial_distribution(IntType k, double p = 0.5);

Preconditions:

0 < p \leq 1

and

0 < k

Remarks: k and p correspond to the respective parameters of the distribution.

🔗

IntType k() const;

Returns: The value of the k parameter with which the object was constructed.

🔗

double p() const;

Returns: The value of the p parameter with which the object was constructed.

29.5.9.4 Poisson distributions [rand.dist.pois]

29.5.9.4.1 Class template poisson_distribution [rand.dist.pois.poisson]

A poisson_distribution random number distribution produces integer values i ≥ 0 distributed according to the discrete probability function in Formula 29.8 .

\begin{matrix} P (i | μ) = \frac{e^{- μ} μ^{i}}{i!} \\ (29.8) \end{matrix}

The distribution parameter μ is also known as this distribution's mean.

🔗

namespace std { template<class IntType = int> class poisson_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructors and reset functions poisson_distribution() : poisson_distribution(1.0) {} explicit poisson_distribution(double mean); explicit poisson_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const poisson_distribution& x, const poisson_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions double mean() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const poisson_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, poisson_distribution& x); }; }

🔗

explicit poisson_distribution(double mean);

Preconditions:

0 < mean

Remarks: mean corresponds to the parameter of the distribution.

🔗

double mean() const;

Returns: The value of the mean parameter with which the object was constructed.

29.5.9.4.2 Class template exponential_distribution [rand.dist.pois.exp]

An exponential_distribution random number distribution produces random numbers

x > 0

distributed according to the probability density function in Formula 29.9 .

\begin{matrix} p (x | λ) = λ e^{- λ x} \\ (29.9) \end{matrix}

🔗

namespace std { template<class RealType = double> class exponential_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructors and reset functions exponential_distribution() : exponential_distribution(1.0) {} explicit exponential_distribution(RealType lambda); explicit exponential_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const exponential_distribution& x, const exponential_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType lambda() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const exponential_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, exponential_distribution& x); }; }

🔗

explicit exponential_distribution(RealType lambda);

Preconditions:

0 < lambda

Remarks: lambda corresponds to the parameter of the distribution.

🔗

RealType lambda() const;

Returns: The value of the lambda parameter with which the object was constructed.

29.5.9.4.3 Class template gamma_distribution [rand.dist.pois.gamma]

A gamma_distribution random number distribution produces random numbers

x > 0

distributed according to the probability density function in Formula 29.10 .

\begin{matrix} p (x | α, β) = \frac{e^{- x / β}}{β^{α} \cdot Γ (α)} \cdot x^{α - 1} \\ (29.10) \end{matrix}

🔗

namespace std { template<class RealType = double> class gamma_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructors and reset functions gamma_distribution() : gamma_distribution(1.0) {} explicit gamma_distribution(RealType alpha, RealType beta = 1.0); explicit gamma_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const gamma_distribution& x, const gamma_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType alpha() const; RealType beta() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const gamma_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, gamma_distribution& x); }; }

🔗

explicit gamma_distribution(RealType alpha, RealType beta = 1.0);

Preconditions:

0 < alpha

and

0 < beta

Remarks: alpha and beta correspond to the parameters of the distribution.

🔗

RealType alpha() const;

Returns: The value of the alpha parameter with which the object was constructed.

🔗

RealType beta() const;

Returns: The value of the beta parameter with which the object was constructed.

29.5.9.4.4 Class template weibull_distribution [rand.dist.pois.weibull]

A weibull_distribution random number distribution produces random numbers x ≥ 0 distributed according to the probability density function in Formula 29.11 .

\begin{matrix} p (x | a, b) = \frac{a}{b} \cdot {(\frac{x}{b})}^{a - 1} \cdot exp (- {(\frac{x}{b})}^{a}) \\ (29.11) \end{matrix}

🔗

namespace std { template<class RealType = double> class weibull_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions weibull_distribution() : weibull_distribution(1.0) {} explicit weibull_distribution(RealType a, RealType b = 1.0); explicit weibull_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const weibull_distribution& x, const weibull_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType a() const; RealType b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const weibull_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, weibull_distribution& x); }; }

🔗

explicit weibull_distribution(RealType a, RealType b = 1.0);

Preconditions:

0 < a

and

0 < b

Remarks: a and b correspond to the respective parameters of the distribution.

🔗

RealType a() const;

Returns: The value of the a parameter with which the object was constructed.

🔗

RealType b() const;

Returns: The value of the b parameter with which the object was constructed.

29.5.9.4.5 Class template extreme_value_distribution [rand.dist.pois.extreme]

An extreme_value_distribution random number distribution produces random numbers x distributed according to the probability density function in Formula 29.12 .252

\begin{matrix} p (x | a, b) = \frac{1}{b} \cdot exp (\frac{a - x}{b} - exp (\frac{a - x}{b})) \\ (29.12) \end{matrix}

🔗

namespace std { template<class RealType = double> class extreme_value_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions extreme_value_distribution() : extreme_value_distribution(0.0) {} explicit extreme_value_distribution(RealType a, RealType b = 1.0); explicit extreme_value_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const extreme_value_distribution& x, const extreme_value_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType a() const; RealType b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const extreme_value_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, extreme_value_distribution& x); }; }

🔗

explicit extreme_value_distribution(RealType a, RealType b = 1.0);

Preconditions:

0 < b

Remarks: a and b correspond to the respective parameters of the distribution.

🔗

RealType a() const;

Returns: The value of the a parameter with which the object was constructed.

🔗

RealType b() const;

Returns: The value of the b parameter with which the object was constructed.

252)252)

The distribution corresponding to this probability density function is also known (with a possible change of variable) as the Gumbel Type I, the log-Weibull, or the Fisher-Tippett Type I distribution.

29.5.9.5 Normal distributions [rand.dist.norm]

29.5.9.5.1 Class template normal_distribution [rand.dist.norm.normal]

A normal_distribution random number distribution produces random numbers x distributed according to the probability density function in Formula 29.13 .

\begin{matrix} p (x | μ, σ) = \frac{1}{σ \sqrt{2 π}} \cdot exp (- \frac{(x - μ)^{2}}{2 σ^{2}}) \\ (29.13) \end{matrix}

The distribution parameters μ and σ are also known as this distribution's mean and standard deviation.

🔗

namespace std { template<class RealType = double> class normal_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructors and reset functions normal_distribution() : normal_distribution(0.0) {} explicit normal_distribution(RealType mean, RealType stddev = 1.0); explicit normal_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const normal_distribution& x, const normal_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType mean() const; RealType stddev() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const normal_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, normal_distribution& x); }; }

🔗

explicit normal_distribution(RealType mean, RealType stddev = 1.0);

Preconditions:

0 < stddev

Remarks: mean and stddev correspond to the respective parameters of the distribution.

🔗

RealType mean() const;

Returns: The value of the mean parameter with which the object was constructed.

🔗

RealType stddev() const;

Returns: The value of the stddev parameter with which the object was constructed.

29.5.9.5.2 Class template lognormal_distribution [rand.dist.norm.lognormal]

A lognormal_distribution random number distribution produces random numbers

x > 0

distributed according to the probability density function in Formula 29.14 .

\begin{matrix} p (x | m, s) = \frac{1}{s x \sqrt{2 π}} \cdot exp (- \frac{(ln x - m)^{2}}{2 s^{2}}) \\ (29.14) \end{matrix}

🔗

namespace std { template<class RealType = double> class lognormal_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions lognormal_distribution() : lognormal_distribution(0.0) {} explicit lognormal_distribution(RealType m, RealType s = 1.0); explicit lognormal_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const lognormal_distribution& x, const lognormal_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType m() const; RealType s() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const lognormal_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, lognormal_distribution& x); }; }

🔗

explicit lognormal_distribution(RealType m, RealType s = 1.0);

Preconditions:

0 < s

Remarks: m and s correspond to the respective parameters of the distribution.

🔗

RealType m() const;

Returns: The value of the m parameter with which the object was constructed.

🔗

RealType s() const;

Returns: The value of the s parameter with which the object was constructed.

29.5.9.5.3 Class template chi_squared_distribution [rand.dist.norm.chisq]

A chi_squared_distribution random number distribution produces random numbers

x > 0

distributed according to the probability density function in Formula 29.15 .

\begin{matrix} p (x | n) = \frac{x^{(n / 2) - 1} \cdot e^{- x / 2}}{Γ (n / 2) \cdot 2^{n / 2}} \\ (29.15) \end{matrix}

🔗

namespace std { template<class RealType = double> class chi_squared_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions chi_squared_distribution() : chi_squared_distribution(1.0) {} explicit chi_squared_distribution(RealType n); explicit chi_squared_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const chi_squared_distribution& x, const chi_squared_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType n() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const chi_squared_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, chi_squared_distribution& x); }; }

🔗

explicit chi_squared_distribution(RealType n);

Preconditions:

0 < n

Remarks: n corresponds to the parameter of the distribution.

🔗

RealType n() const;

Returns: The value of the n parameter with which the object was constructed.

29.5.9.5.4 Class template cauchy_distribution [rand.dist.norm.cauchy]

A cauchy_distribution random number distribution produces random numbers x distributed according to the probability density function in Formula 29.16 .

\begin{matrix} p (x | a, b) = {(π b (1 + {(\frac{x - a}{b})}^{2}))}^{- 1} \\ (29.16) \end{matrix}

🔗

namespace std { template<class RealType = double> class cauchy_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions cauchy_distribution() : cauchy_distribution(0.0) {} explicit cauchy_distribution(RealType a, RealType b = 1.0); explicit cauchy_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const cauchy_distribution& x, const cauchy_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType a() const; RealType b() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const cauchy_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, cauchy_distribution& x); }; }

🔗

explicit cauchy_distribution(RealType a, RealType b = 1.0);

Preconditions:

0 < b

Remarks: a and b correspond to the respective parameters of the distribution.

🔗

RealType a() const;

Returns: The value of the a parameter with which the object was constructed.

🔗

RealType b() const;

Returns: The value of the b parameter with which the object was constructed.

29.5.9.5.5 Class template fisher_f_distribution [rand.dist.norm.f]

A fisher_f_distribution random number distribution produces random numbers x ≥ 0 distributed according to the probability density function in Formula 29.17 .

\begin{matrix} p (x | m, n) = \frac{Γ ((m + n) / 2)}{Γ (m / 2) Γ (n / 2)} \cdot {(\frac{m}{n})}^{m / 2} \cdot x^{(m / 2) - 1} \cdot {(1 + \frac{m x}{n})}^{- (m + n) / 2} \\ (29.17) \end{matrix}

🔗

namespace std { template<class RealType = double> class fisher_f_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions fisher_f_distribution() : fisher_f_distribution(1.0) {} explicit fisher_f_distribution(RealType m, RealType n = 1.0); explicit fisher_f_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const fisher_f_distribution& x, const fisher_f_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType m() const; RealType n() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const fisher_f_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, fisher_f_distribution& x); }; }

🔗

explicit fisher_f_distribution(RealType m, RealType n = 1);

Preconditions:

0 < m

and

0 < n

Remarks: m and n correspond to the respective parameters of the distribution.

🔗

RealType m() const;

Returns: The value of the m parameter with which the object was constructed.

🔗

RealType n() const;

Returns: The value of the n parameter with which the object was constructed.

29.5.9.5.6 Class template student_t_distribution [rand.dist.norm.t]

A student_t_distribution random number distribution produces random numbers x distributed according to the probability density function in Formula 29.18 .

\begin{matrix} p (x | n) = \frac{1}{\sqrt{n π}} \cdot \frac{Γ ((n + 1) / 2)}{Γ (n / 2)} \cdot {(1 + \frac{x^{2}}{n})}^{- (n + 1) / 2} \\ (29.18) \end{matrix}

🔗

namespace std { template<class RealType = double> class student_t_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions student_t_distribution() : student_t_distribution(1.0) {} explicit student_t_distribution(RealType n); explicit student_t_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const student_t_distribution& x, const student_t_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions RealType n() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const student_t_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, student_t_distribution& x); }; }

🔗

explicit student_t_distribution(RealType n);

Preconditions:

0 < n

Remarks: n corresponds to the parameter of the distribution.

🔗

RealType n() const;

Returns: The value of the n parameter with which the object was constructed.

29.5.9.6 Sampling distributions [rand.dist.samp]

29.5.9.6.1 Class template discrete_distribution [rand.dist.samp.discrete]

A discrete_distribution random number distribution produces random integers i,

0 \leq i < n

, distributed according to the discrete probability function in Formula 29.19 .

\begin{matrix} P (i | p_{0}, \dots, p_{n - 1}) = p_{i} \\ (29.19) \end{matrix}

Unless specified otherwise, the distribution parameters are calculated as:

p_{k} = w_{k} / S

for

k = 0, \dots, n - 1

, in which the values

w_{k}

, commonly known as the weights, shall be non-negative, non-NaN, and non-infinity.

Moreover, the following relation shall hold:

0 < S = w_{0} + \dots + w_{n - 1}

🔗

namespace std { template<class IntType = int> class discrete_distribution { public: // types using result_type = IntType; using param_type = unspecified; // constructor and reset functions discrete_distribution(); template<class InputIterator> discrete_distribution(InputIterator firstW, InputIterator lastW); discrete_distribution(initializer_list<double> wl); template<class UnaryOperation> discrete_distribution(size_t nw, double xmin, double xmax, UnaryOperation fw); explicit discrete_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const discrete_distribution& x, const discrete_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions vector<double> probabilities() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const discrete_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, discrete_distribution& x); }; }

🔗

discrete_distribution();

Effects: Constructs a discrete_distribution object with

n = 1

and

p_{0} = 1

[Note 1:

Such an object will always deliver the value 0.

— end note]

🔗

template<class InputIterator>
  discrete_distribution(InputIterator firstW, InputIterator lastW);

Mandates: is_convertible_v<iterator_traits<InputIterator>::value_type, double> is true.

Preconditions: InputIterator meets the Cpp17InputIterator requirements ([input.iterators]).

If firstW == lastW, let

n = 1

and

w_{0} = 1

Otherwise, [firstW, lastW) forms a sequence w of length

n > 0

Effects: Constructs a discrete_distribution object with probabilities given by the Formula 29.19 .

🔗

discrete_distribution(initializer_list<double> wl);

Effects: Same as discrete_distribution(wl.begin(), wl.end()).

🔗

template<class UnaryOperation>
  discrete_distribution(size_t nw, double xmin, double xmax, UnaryOperation fw);

Mandates: is_invocable_r_v<double, UnaryOperation&, double> is true.

Preconditions: If

nw = 0

, let

n = 1

, otherwise let

n = nw

The relation

0 < δ = (xmax - xmin) / n

holds.

Effects: Constructs a discrete_distribution object with probabilities given by the formula above, using the following values: If

nw = 0

, let

w_{0} = 1

Otherwise, let

w_{k} = fw (xmin + k \cdot δ + δ / 2)

for

k = 0, \dots, n - 1

Complexity: The number of invocations of fw does not exceed n.

🔗

vector<double> probabilities() const;

Returns: A vector<double> whose size member returns n and whose operator[] member returns

p_{k}

when invoked with argument k for

k = 0, \dots, n - 1

29.5.9.6.2 Class template piecewise_constant_distribution [rand.dist.samp.pconst]

A piecewise_constant_distribution random number distribution produces random numbers x,

b_{0} \leq x < b_{n}

, uniformly distributed over each subinterval

[b_{i}, b_{i + 1})

according to the probability density function in Formula 29.20 .

\begin{matrix} p (x | b_{0}, \dots, b_{n}, ρ_{0}, \dots, ρ_{n - 1}) = ρ_{i}, for b_{i} \leq x < b_{i + 1} \\ (29.20) \end{matrix}

The

n + 1

distribution parameters

b_{i}

, also known as this distribution's interval boundaries, shall satisfy the relation

b_{i} < b_{i + 1}

for

i = 0, \dots, n - 1

Unless specified otherwise, the remaining n distribution parameters are calculated as:

ρ_{k} = \frac{w_{k}}{S \cdot (b_{k + 1} - b_{k})} for k = 0, \dots, n - 1,

in which the values

w_{k}

, commonly known as the weights, shall be non-negative, non-NaN, and non-infinity.

Moreover, the following relation shall hold:

0 < S = w_{0} + \dots + w_{n - 1}

🔗

namespace std { template<class RealType = double> class piecewise_constant_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions piecewise_constant_distribution(); template<class InputIteratorB, class InputIteratorW> piecewise_constant_distribution(InputIteratorB firstB, InputIteratorB lastB, InputIteratorW firstW); template<class UnaryOperation> piecewise_constant_distribution(initializer_list<RealType> bl, UnaryOperation fw); template<class UnaryOperation> piecewise_constant_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw); explicit piecewise_constant_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const piecewise_constant_distribution& x, const piecewise_constant_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions vector<result_type> intervals() const; vector<result_type> densities() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const piecewise_constant_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, piecewise_constant_distribution& x); }; }

🔗

piecewise_constant_distribution();

Effects: Constructs a piecewise_constant_distribution object with

n = 1

ρ_{0} = 1

b_{0} = 0

, and

b_{1} = 1

🔗

template<class InputIteratorB, class InputIteratorW>
 piecewise_constant_distribution(InputIteratorB firstB, InputIteratorB lastB,
                                 InputIteratorW firstW);

Mandates: Both of

(4.1)
is_convertible_v<iterator_traits<InputIteratorB>::value_type, double>
(4.2)
is_convertible_v<iterator_traits<InputIteratorW>::value_type, double>

are true.

Preconditions: InputIteratorB and InputIteratorW each meet the Cpp17InputIterator requirements ([input.iterators]).

If firstB == lastB or ++firstB == lastB, let

n = 1

w_{0} = 1

b_{0} = 0

, and

b_{1} = 1

Otherwise, [firstB, lastB) forms a sequence b of length

n + 1

, the length of the sequence w starting from firstW is at least n, and any

w_{k}

for k ≥ n are ignored by the distribution.

Effects: Constructs a piecewise_constant_distribution object with parameters as specified above.

🔗

template<class UnaryOperation>
 piecewise_constant_distribution(initializer_list<RealType> bl, UnaryOperation fw);

Mandates: is_invocable_r_v<double, UnaryOperation&, double> is true.

Effects: Constructs a piecewise_constant_distribution object with parameters taken or calculated from the following values: If

bl.size() < 2

, let

n = 1

w_{0} = 1

b_{0} = 0

, and

b_{1} = 1

Otherwise, let [bl.begin(), bl.end()) form a sequence

b_{0}, \dots, b_{n}

, and let

w_{k} = fw ((b_{k + 1} + b_{k}) / 2)

for

k = 0, \dots, n - 1

Complexity: The number of invocations of fw does not exceed n.

🔗

template<class UnaryOperation>
 piecewise_constant_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);

Mandates: is_invocable_r_v<double, UnaryOperation&, double> is true.

Preconditions: If

nw = 0

, let

n = 1

, otherwise let

n = nw

The relation

0 < δ = (xmax - xmin) / n

holds.

Effects: Constructs a piecewise_constant_distribution object with parameters taken or calculated from the following values: Let

b_{k} = xmin + k \cdot δ

for

k = 0, \dots, n

, and

w_{k} = fw (b_{k} + δ / 2)

for

k = 0, \dots, n - 1

Complexity: The number of invocations of fw does not exceed n.

🔗

vector<result_type> intervals() const;

Returns: A vector<result_type> whose size member returns

n + 1

and whose operator[] member returns

b_{k}

when invoked with argument k for

k = 0, \dots, n

🔗

vector<result_type> densities() const;

Returns: A vector<result_type> whose size member returns n and whose operator[] member returns

ρ_{k}

when invoked with argument k for

k = 0, \dots, n - 1

29.5.9.6.3 Class template piecewise_linear_distribution [rand.dist.samp.plinear]

A piecewise_linear_distribution random number distribution produces random numbers x,

b_{0} \leq x < b_{n}

, distributed over each subinterval

[b_{i}, b_{i + 1})

according to the probability density function in Formula 29.21 .

\begin{matrix} p (x | b_{0}, \dots, b_{n}, ρ_{0}, \dots, ρ_{n}) = ρ_{i} \cdot \frac{b_{i + 1} - x}{b_{i + 1} - b_{i}} + ρ_{i + 1} \cdot \frac{x - b_{i}}{b_{i + 1} - b_{i}}, for b_{i} \leq x < b_{i + 1} . \\ (29.21) \end{matrix}

The

n + 1

distribution parameters

b_{i}

, also known as this distribution's interval boundaries, shall satisfy the relation

b_{i} < b_{i + 1}

for

i = 0, \dots, n - 1

Unless specified otherwise, the remaining

n + 1

distribution parameters are calculated as

ρ_{k} = w_{k} / S

for

k = 0, \dots, n

, in which the values

w_{k}

, commonly known as the weights at boundaries, shall be non-negative, non-NaN, and non-infinity.

Moreover, the following relation shall hold:

0 < S = \frac{1}{2} \cdot n - 1 \sum k = 0 (w_{k} + w_{k + 1}) \cdot (b_{k + 1} - b_{k}) .

🔗

namespace std { template<class RealType = double> class piecewise_linear_distribution { public: // types using result_type = RealType; using param_type = unspecified; // constructor and reset functions piecewise_linear_distribution(); template<class InputIteratorB, class InputIteratorW> piecewise_linear_distribution(InputIteratorB firstB, InputIteratorB lastB, InputIteratorW firstW); template<class UnaryOperation> piecewise_linear_distribution(initializer_list<RealType> bl, UnaryOperation fw); template<class UnaryOperation> piecewise_linear_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw); explicit piecewise_linear_distribution(const param_type& parm); void reset(); // equality operators friend bool operator==(const piecewise_linear_distribution& x, const piecewise_linear_distribution& y); // generating functions template<class URBG> result_type operator()(URBG& g); template<class URBG> result_type operator()(URBG& g, const param_type& parm); // property functions vector<result_type> intervals() const; vector<result_type> densities() const; param_type param() const; void param(const param_type& parm); result_type min() const; result_type max() const; // inserters and extractors template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const piecewise_linear_distribution& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, piecewise_linear_distribution& x); }; }

🔗

piecewise_linear_distribution();

Effects: Constructs a piecewise_linear_distribution object with

n = 1

ρ_{0} = ρ_{1} = 1

b_{0} = 0

, and

b_{1} = 1

🔗

template<class InputIteratorB, class InputIteratorW>
 piecewise_linear_distribution(InputIteratorB firstB, InputIteratorB lastB,
                               InputIteratorW firstW);

Mandates: Both of

(4.1)
is_convertible_v<iterator_traits<InputIteratorB>::value_type, double>
(4.2)
is_convertible_v<iterator_traits<InputIteratorW>::value_type, double>

are true.

Preconditions: InputIteratorB and InputIteratorW each meet the Cpp17InputIterator requirements ([input.iterators]).

If firstB == lastB or ++firstB == lastB, let

n = 1

ρ_{0} = ρ_{1} = 1

b_{0} = 0

, and

b_{1} = 1

Otherwise, [firstB, lastB) forms a sequence b of length

n + 1

, the length of the sequence w starting from firstW is at least

n + 1

, and any

w_{k}

for

k \geq n + 1

are ignored by the distribution.

Effects: Constructs a piecewise_linear_distribution object with parameters as specified above.

🔗

template<class UnaryOperation>
 piecewise_linear_distribution(initializer_list<RealType> bl, UnaryOperation fw);

Mandates: is_invocable_r_v<double, UnaryOperation&, double> is true.

Effects: Constructs a piecewise_linear_distribution object with parameters taken or calculated from the following values: If

bl.size() < 2

, let

n = 1

ρ_{0} = ρ_{1} = 1

b_{0} = 0

, and

b_{1} = 1

Otherwise, let [bl.begin(), bl.end()) form a sequence

b_{0}, \dots, b_{n}

, and let

w_{k} = fw (b_{k})

for

k = 0, \dots, n

Complexity: The number of invocations of fw does not exceed

n + 1

🔗

template<class UnaryOperation>
 piecewise_linear_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);

Mandates: is_invocable_r_v<double, UnaryOperation&, double> is true.

Preconditions: If

nw = 0

, let

n = 1

, otherwise let

n = nw

The relation

0 < δ = (xmax - xmin) / n

holds.

Effects: Constructs a piecewise_linear_distribution object with parameters taken or calculated from the following values: Let

b_{k} = xmin + k \cdot δ

for

k = 0, \dots, n

, and

w_{k} = fw (b_{k})

for

k = 0, \dots, n

Complexity: The number of invocations of fw does not exceed

n + 1

🔗

vector<result_type> intervals() const;

Returns: A vector<result_type> whose size member returns

n + 1

and whose operator[] member returns

b_{k}

when invoked with argument k for

k = 0, \dots, n

🔗

vector<result_type> densities() const;

Returns: A vector<result_type> whose size member returns n and whose operator[] member returns

ρ_{k}

when invoked with argument k for

k = 0, \dots, n

29.5.10 Low-quality random number generation [c.math.rand]

[Note 1:

The header <cstdlib> declares the functions described in this subclause.

— end note]

🔗

int rand();
void srand(unsigned int seed);

Effects: The rand and srand functions have the semantics specified in the C standard library.

Remarks: The implementation may specify that particular library functions may call rand.

It is implementation-defined whether the rand function may introduce data races ([res.on.data.races]).

[Note 2:

The other random number generation facilities in this document ([rand]) are often preferable to rand, because rand's underlying algorithm is unspecified.

Use of rand therefore continues to be non-portable, with unpredictable and oft-questionable quality and performance.

— end note]

29.6 Numeric arrays [numarray]

29.6.1 Header <valarray> synopsis [valarray.syn]

🔗

#include <initializer_list> // see [initializer.list.syn] namespace std { template<class T> class valarray; // An array of type T class slice; // a BLAS-like slice out of an array template<class T> class slice_array; class gslice; // a generalized slice out of an array template<class T> class gslice_array; template<class T> class mask_array; // a masked array template<class T> class indirect_array; // an indirected array template<class T> void swap(valarray<T>&, valarray<T>&) noexcept; template<class T> valarray<T> operator* (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator* (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator* (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator/ (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator/ (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator/ (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator% (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator% (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator% (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator+ (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator+ (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator+ (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator- (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator- (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator- (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator^ (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator^ (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator^ (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator& (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator& (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator& (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator| (const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator| (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator| (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator<<(const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator<<(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator<<(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> operator>>(const valarray<T>&, const valarray<T>&); template<class T> valarray<T> operator>>(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> operator>>(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<bool> operator&&(const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator&&(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<bool> operator&&(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<bool> operator||(const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator||(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<bool> operator||(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<bool> operator==(const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator==(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<bool> operator==(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<bool> operator!=(const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator!=(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<bool> operator!=(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<bool> operator< (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator< (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<bool> operator< (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<bool> operator> (const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator> (const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<bool> operator> (const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<bool> operator<=(const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator<=(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<bool> operator<=(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<bool> operator>=(const valarray<T>&, const valarray<T>&); template<class T> valarray<bool> operator>=(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<bool> operator>=(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> abs (const valarray<T>&); template<class T> valarray<T> acos (const valarray<T>&); template<class T> valarray<T> asin (const valarray<T>&); template<class T> valarray<T> atan (const valarray<T>&); template<class T> valarray<T> atan2(const valarray<T>&, const valarray<T>&); template<class T> valarray<T> atan2(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> atan2(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> cos (const valarray<T>&); template<class T> valarray<T> cosh (const valarray<T>&); template<class T> valarray<T> exp (const valarray<T>&); template<class T> valarray<T> log (const valarray<T>&); template<class T> valarray<T> log10(const valarray<T>&); template<class T> valarray<T> pow(const valarray<T>&, const valarray<T>&); template<class T> valarray<T> pow(const valarray<T>&, const typename valarray<T>::value_type&); template<class T> valarray<T> pow(const typename valarray<T>::value_type&, const valarray<T>&); template<class T> valarray<T> sin (const valarray<T>&); template<class T> valarray<T> sinh (const valarray<T>&); template<class T> valarray<T> sqrt (const valarray<T>&); template<class T> valarray<T> tan (const valarray<T>&); template<class T> valarray<T> tanh (const valarray<T>&); template<class T> unspecified1 begin(valarray<T>& v); template<class T> unspecified2 begin(const valarray<T>& v); template<class T> unspecified1 end(valarray<T>& v); template<class T> unspecified2 end(const valarray<T>& v); }

The header <valarray> defines five class templates (valarray, slice_array, gslice_array, mask_array, and indirect_array), two classes (slice and gslice), and a series of related function templates for representing and manipulating arrays of values.

The valarray array classes are defined to be free of certain forms of aliasing, thus allowing operations on these classes to be optimized.

Any function returning a valarray<T> is permitted to return an object of another type, provided all the const member functions of valarray<T> are also applicable to this type.

This return type shall not add more than two levels of template nesting over the most deeply nested argument type.253

Implementations introducing such replacement types shall provide additional functions and operators as follows:

(4.1)
for every function taking a const valarray<T>& other than begin and end, identical functions taking the replacement types shall be added;
(4.2)
for every function taking two const valarray<T>& arguments, identical functions taking every combination of const valarray<T>& and replacement types shall be added.

In particular, an implementation shall allow a valarray<T> to be constructed from such replacement types and shall allow assignments and compound assignments of such types to valarray<T>, slice_array<T>, gslice_array<T>, mask_array<T> and indirect_array<T> objects.

These library functions are permitted to throw a bad_alloc exception if there are not sufficient resources available to carry out the operation.

Note that the exception is not mandated.

253)253)

[implimits] recommends a minimum number of recursively nested template instantiations.

This requirement thus indirectly suggests a minimum allowable complexity for valarray expressions.

29.6.2 Class template valarray [template.valarray]

29.6.2.1 Overview [template.valarray.overview]

🔗

namespace std { template<class T> class valarray { public: using value_type = T; // [valarray.cons], construct/destroy valarray(); explicit valarray(size_t); valarray(const T&, size_t); valarray(const T*, size_t); valarray(const valarray&); valarray(valarray&&) noexcept; valarray(const slice_array<T>&); valarray(const gslice_array<T>&); valarray(const mask_array<T>&); valarray(const indirect_array<T>&); valarray(initializer_list<T>); ~valarray(); // [valarray.assign], assignment valarray& operator=(const valarray&); valarray& operator=(valarray&&) noexcept; valarray& operator=(initializer_list<T>); valarray& operator=(const T&); valarray& operator=(const slice_array<T>&); valarray& operator=(const gslice_array<T>&); valarray& operator=(const mask_array<T>&); valarray& operator=(const indirect_array<T>&); // [valarray.access], element access const T& operator[](size_t) const; T& operator[](size_t); // [valarray.sub], subset operations valarray operator[](slice) const; slice_array<T> operator[](slice); valarray operator[](const gslice&) const; gslice_array<T> operator[](const gslice&); valarray operator[](const valarray<bool>&) const; mask_array<T> operator[](const valarray<bool>&); valarray operator[](const valarray<size_t>&) const; indirect_array<T> operator[](const valarray<size_t>&); // [valarray.unary], unary operators valarray operator+() const; valarray operator-() const; valarray operator~() const; valarray<bool> operator!() const; // [valarray.cassign], compound assignment valarray& operator*= (const T&); valarray& operator/= (const T&); valarray& operator%= (const T&); valarray& operator+= (const T&); valarray& operator-= (const T&); valarray& operator^= (const T&); valarray& operator&= (const T&); valarray& operator|= (const T&); valarray& operator<<=(const T&); valarray& operator>>=(const T&); valarray& operator*= (const valarray&); valarray& operator/= (const valarray&); valarray& operator%= (const valarray&); valarray& operator+= (const valarray&); valarray& operator-= (const valarray&); valarray& operator^= (const valarray&); valarray& operator|= (const valarray&); valarray& operator&= (const valarray&); valarray& operator<<=(const valarray&); valarray& operator>>=(const valarray&); // [valarray.members], member functions void swap(valarray&) noexcept; size_t size() const; T sum() const; T min() const; T max() const; valarray shift (int) const; valarray cshift(int) const; valarray apply(T func(T)) const; valarray apply(T func(const T&)) const; void resize(size_t sz, T c = T()); }; template<class T, size_t cnt> valarray(const T(&)[cnt], size_t) -> valarray<T>; }

The class template valarray<T> is a one-dimensional smart array, with elements numbered sequentially from zero.

It is a representation of the mathematical concept of an ordered set of values.

For convenience, an object of type valarray<T> is referred to as an “array” throughout the remainder of [numarray].

The illusion of higher dimensionality may be produced by the familiar idiom of computed indices, together with the powerful subsetting capabilities provided by the generalized subscript operators.254

254)254)

The intent is to specify an array template that has the minimum functionality necessary to address aliasing ambiguities and the proliferation of temporary objects.

Thus, the valarray template is neither a matrix class nor a field class.

However, it is a very useful building block for designing such classes.

29.6.2.2 Constructors [valarray.cons]

🔗

valarray();

Effects: Constructs a valarray that has zero length.255

🔗

explicit valarray(size_t n);

Effects: Constructs a valarray that has length n.

Each element of the array is value-initialized .

🔗

valarray(const T& v, size_t n);

Effects: Constructs a valarray that has length n.

Each element of the array is initialized with v.

🔗

valarray(const T* p, size_t n);

Preconditions: [p, p + n) is a valid range.

Effects: Constructs a valarray that has length n.

The values of the elements of the array are initialized with the first n values pointed to by the first argument.256

🔗

valarray(const valarray& v);

Effects: Constructs a valarray that has the same length as v.

The elements are initialized with the values of the corresponding elements of v.257

🔗

valarray(valarray&& v) noexcept;

Effects: Constructs a valarray that has the same length as v.

The elements are initialized with the values of the corresponding elements of v.

Complexity: Constant.

🔗

valarray(initializer_list<T> il);

Effects: Equivalent to valarray(il.begin(), il.size()).

🔗

valarray(const slice_array<T>&);
valarray(const gslice_array<T>&);
valarray(const mask_array<T>&);
valarray(const indirect_array<T>&);

These conversion constructors convert one of the four reference templates to a valarray.

🔗

~valarray();

Effects: The destructor is applied to every element of *this; an implementation may return all allocated memory.

255)255)

This default constructor is essential, since arrays of valarray can be useful.

After initialization, the length of an empty array can be increased with the resize member function.

256)256)

This constructor is the preferred method for converting a C array to a valarray object.

257)257)

This copy constructor creates a distinct array rather than an alias.

Implementations in which arrays share storage are permitted, but they would need to implement a copy-on-reference mechanism to ensure that arrays are conceptually distinct.

29.6.2.3 Assignment [valarray.assign]

🔗

valarray& operator=(const valarray& v);

Effects: Each element of the *this array is assigned the value of the corresponding element of v.

If the length of v is not equal to the length of *this, resizes *this to make the two arrays the same length, as if by calling resize(v.size()), before performing the assignment.

Postconditions: size() == v.size().

Returns: *this.

🔗

valarray& operator=(valarray&& v) noexcept;

Effects: *this obtains the value of v.

The value of v after the assignment is not specified.

Returns: *this.

Complexity: Linear.

🔗

valarray& operator=(initializer_list<T> il);

Effects: Equivalent to: return *this = valarray(il);

🔗

valarray& operator=(const T& v);

Effects: Assigns v to each element of *this.

Returns: *this.

🔗

valarray& operator=(const slice_array<T>&);
valarray& operator=(const gslice_array<T>&);
valarray& operator=(const mask_array<T>&);
valarray& operator=(const indirect_array<T>&);

Preconditions: The length of the array to which the argument refers equals size().

The value of an element in the left-hand side of a valarray assignment operator does not depend on the value of another element in that left-hand side.

These operators allow the results of a generalized subscripting operation to be assigned directly to a valarray.

29.6.2.4 Element access [valarray.access]

🔗

const T&  operator[](size_t n) const;
T& operator[](size_t n);

Preconditions: n < size() is true.

Returns: A reference to the corresponding element of the array.

[Note 1:

The expression (a[i] = q, a[i]) == q evaluates to true for any non-constant valarray<T> a, any T q, and for any size_t i such that the value of i is less than the length of a.

— end note]

Remarks: The expression addressof(a[i+j]) == addressof(a[i]) + j evaluates to true for all size_t i and size_t j such that i+j < a.size().

The expression addressof(a[i]) != addressof(b[j]) evaluates to true for any two arrays a and b and for any size_t i and size_t j such that i < a.size() and j < b.size().

[Note 2:

This property indicates an absence of aliasing and can be used to advantage by optimizing compilers.

Compilers can take advantage of inlining, constant propagation, loop fusion, tracking of pointers obtained from operator new, and other techniques to generate efficient valarrays.

— end note]

The reference returned by the subscript operator for an array shall be valid until the member function resize(size_t, T) is called for that array or until the lifetime of that array ends, whichever happens first.

29.6.2.5 Subset operations [valarray.sub]

The member operator[] is overloaded to provide several ways to select sequences of elements from among those controlled by *this.

Each of these operations returns a subset of the array.

The const-qualified versions return this subset as a new valarray object.

The non-const versions return a class template object which has reference semantics to the original array, working in conjunction with various overloads of operator= and other assigning operators to allow selective replacement (slicing) of the controlled sequence.

In each case the selected element(s) shall exist.

🔗

valarray operator[](slice slicearr) const;

Returns: A valarray containing those elements of the controlled sequence designated by slicearr.

[Example 1: const valarray<char> v0("abcdefghijklmnop", 16); // v0[slice(2, 5, 3)] returns valarray<char>("cfilo", 5) — end example]

🔗

slice_array<T> operator[](slice slicearr);

Returns: An object that holds references to elements of the controlled sequence selected by slicearr.

[Example 2: valarray<char> v0("abcdefghijklmnop", 16); valarray<char> v1("ABCDE", 5); v0[slice(2, 5, 3)] = v1; // v0 == valarray<char>("abAdeBghCjkDmnEp", 16); — end example]

🔗

valarray operator[](const gslice& gslicearr) const;

Returns: A valarray containing those elements of the controlled sequence designated by gslicearr.

[Example 3: const valarray<char> v0("abcdefghijklmnop", 16); const size_t lv[] = { 2, 3 }; const size_t dv[] = { 7, 2 }; const valarray<size_t> len(lv, 2), str(dv, 2); // v0[gslice(3, len, str)] returns // valarray<char>("dfhkmo", 6) — end example]

🔗

gslice_array<T> operator[](const gslice& gslicearr);

Returns: An object that holds references to elements of the controlled sequence selected by gslicearr.

[Example 4: valarray<char> v0("abcdefghijklmnop", 16); valarray<char> v1("ABCDEF", 6); const size_t lv[] = { 2, 3 }; const size_t dv[] = { 7, 2 }; const valarray<size_t> len(lv, 2), str(dv, 2); v0[gslice(3, len, str)] = v1; // v0 == valarray<char>("abcAeBgCijDlEnFp", 16) — end example]

🔗

valarray operator[](const valarray<bool>& boolarr) const;

Returns: A valarray containing those elements of the controlled sequence designated by boolarr.

[Example 5: const valarray<char> v0("abcdefghijklmnop", 16); const bool vb[] = { false, false, true, true, false, true }; // v0[valarray<bool>(vb, 6)] returns // valarray<char>("cdf", 3) — end example]

🔗

mask_array<T> operator[](const valarray<bool>& boolarr);

Returns: An object that holds references to elements of the controlled sequence selected by boolarr.

[Example 6: valarray<char> v0("abcdefghijklmnop", 16); valarray<char> v1("ABC", 3); const bool vb[] = { false, false, true, true, false, true }; v0[valarray<bool>(vb, 6)] = v1; // v0 == valarray<char>("abABeCghijklmnop", 16) — end example]

🔗

valarray operator[](const valarray<size_t>& indarr) const;

Returns: A valarray containing those elements of the controlled sequence designated by indarr.

[Example 7: const valarray<char> v0("abcdefghijklmnop", 16); const size_t vi[] = { 7, 5, 2, 3, 8 }; // v0[valarray<size_t>(vi, 5)] returns // valarray<char>("hfcdi", 5) — end example]

🔗

indirect_array<T> operator[](const valarray<size_t>& indarr);

Returns: An object that holds references to elements of the controlled sequence selected by indarr.

[Example 8: valarray<char> v0("abcdefghijklmnop", 16); valarray<char> v1("ABCDE", 5); const size_t vi[] = { 7, 5, 2, 3, 8 }; v0[valarray<size_t>(vi, 5)] = v1; // v0 == valarray<char>("abCDeBgAEjklmnop", 16) — end example]

29.6.2.6 Unary operators [valarray.unary]

🔗

valarray operator+() const;
valarray operator-() const;
valarray operator~() const;
valarray<bool> operator!() const;

Mandates: The indicated operator can be applied to operands of type T and returns a value of type T (bool for operator!) or which may be unambiguously implicitly converted to type T (bool for operator!).

Returns: A valarray whose length is size().

Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding element of the array.

29.6.2.7 Compound assignment [valarray.cassign]

🔗

valarray& operator*= (const valarray& v);
valarray& operator/= (const valarray& v);
valarray& operator%= (const valarray& v);
valarray& operator+= (const valarray& v);
valarray& operator-= (const valarray& v);
valarray& operator^= (const valarray& v);
valarray& operator&= (const valarray& v);
valarray& operator|= (const valarray& v);
valarray& operator<<=(const valarray& v);
valarray& operator>>=(const valarray& v);

Mandates: The indicated operator can be applied to two operands of type T.

Preconditions: size() == v.size() is true.

The value of an element in the left-hand side of a valarray compound assignment operator does not depend on the value of another element in that left hand side.

Effects: Each of these operators performs the indicated operation on each of the elements of *this and the corresponding element of v.

Returns: *this.

Remarks: The appearance of an array on the left-hand side of a compound assignment does not invalidate references or pointers.

🔗

valarray& operator*= (const T& v);
valarray& operator/= (const T& v);
valarray& operator%= (const T& v);
valarray& operator+= (const T& v);
valarray& operator-= (const T& v);
valarray& operator^= (const T& v);
valarray& operator&= (const T& v);
valarray& operator|= (const T& v);
valarray& operator<<=(const T& v);
valarray& operator>>=(const T& v);

Mandates: The indicated operator can be applied to two operands of type T.

Effects: Each of these operators applies the indicated operation to each element of *this and v.

Returns: *this

Remarks: The appearance of an array on the left-hand side of a compound assignment does not invalidate references or pointers to the elements of the array.

29.6.2.8 Member functions [valarray.members]

🔗

void swap(valarray& v) noexcept;

Effects: *this obtains the value of v.

v obtains the value of *this.

Complexity: Constant.

🔗

size_t size() const;

Returns: The number of elements in the array.

Complexity: Constant time.

🔗

T sum() const;

Mandates: operator+= can be applied to operands of type T.

Preconditions: size() > 0 is true.

Returns: The sum of all the elements of the array.

If the array has length 1, returns the value of element 0.

Otherwise, the returned value is calculated by applying operator+= to a copy of an element of the array and all other elements of the array in an unspecified order.

🔗

T min() const;

Preconditions: size() > 0 is true.

Returns: The minimum value contained in *this.

For an array of length 1, the value of element 0 is returned.

For all other array lengths, the determination is made using operator<.

🔗

T max() const;

Preconditions: size() > 0 is true.

Returns: The maximum value contained in *this.

For an array of length 1, the value of element 0 is returned.

For all other array lengths, the determination is made using operator<.

🔗

valarray shift(int n) const;

Returns: A valarray of length size(), each of whose elements I is (*this)[I + n] if I + n is non-negative and less than size(), otherwise T().

[Note 1:

If element zero is taken as the leftmost element, a positive value of n shifts the elements left n places, with zero fill.

— end note]

[Example 1:

If the argument has the value

- 2

, the first two elements of the result will be value-initialized; the third element of the result will be assigned the value of the first element of *this; etc.

— end example]

🔗

valarray cshift(int n) const;

Returns: A valarray of length size() that is a circular shift of *this.

If element zero is taken as the leftmost element, a non-negative value of n shifts the elements circularly left n places and a negative value of n shifts the elements circularly right

- n

places.

🔗

valarray apply(T func(T)) const;
valarray apply(T func(const T&)) const;

Returns: A valarray whose length is size().

Each element of the returned array is assigned the value returned by applying the argument function to the corresponding element of *this.

🔗

void resize(size_t sz, T c = T());

Effects: Changes the length of the *this array to sz and then assigns to each element the value of the second argument.

Resizing invalidates all pointers and references to elements in the array.

29.6.3 valarray non-member operations [valarray.nonmembers]

29.6.3.1 Binary operators [valarray.binary]

🔗

template<class T> valarray<T> operator* (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator/ (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator% (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator+ (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator- (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator^ (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator& (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator| (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator<<(const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator>>(const valarray<T>&, const valarray<T>&);

Mandates: The indicated operator can be applied to operands of type T and returns a value of type T or which can be unambiguously implicitly converted to T.

Preconditions: The argument arrays have the same length.

Returns: A valarray whose length is equal to the lengths of the argument arrays.

Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding elements of the argument arrays.

🔗

template<class T> valarray<T> operator* (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator* (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator/ (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator/ (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator% (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator% (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator+ (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator+ (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator- (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator- (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator^ (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator^ (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator& (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator& (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator| (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator| (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator<<(const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator<<(const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator>>(const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator>>(const typename valarray<T>::value_type&,
                                         const valarray<T>&);

Mandates: The indicated operator can be applied to operands of type T and returns a value of type T or which can be unambiguously implicitly converted to T.

Returns: A valarray whose length is equal to the length of the array argument.

Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding element of the array argument and the non-array argument.

29.6.3.2 Logical operators [valarray.comparison]

🔗

template<class T> valarray<bool> operator==(const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator!=(const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator< (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator> (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator<=(const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator>=(const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator&&(const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator||(const valarray<T>&, const valarray<T>&);

Mandates: The indicated operator can be applied to operands of type T and returns a value of type bool or which can be unambiguously implicitly converted to bool.

Preconditions: The two array arguments have the same length.

Returns: A valarray<bool> whose length is equal to the length of the array arguments.

Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding elements of the argument arrays.

🔗

template<class T> valarray<bool> operator==(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator==(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator!=(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator!=(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator< (const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator< (const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator> (const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator> (const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator<=(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator<=(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator>=(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator>=(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator&&(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator&&(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator||(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator||(const typename valarray<T>::value_type&,
                                            const valarray<T>&);

Mandates: The indicated operator can be applied to operands of type T and returns a value of type bool or which can be unambiguously implicitly converted to bool.

Returns: A valarray<bool> whose length is equal to the length of the array argument.

Each element of the returned array is initialized with the result of applying the indicated operator to the corresponding element of the array and the non-array argument.

29.6.3.3 Transcendentals [valarray.transcend]

🔗

template<class T> valarray<T> abs  (const valarray<T>&);
template<class T> valarray<T> acos (const valarray<T>&);
template<class T> valarray<T> asin (const valarray<T>&);
template<class T> valarray<T> atan (const valarray<T>&);
template<class T> valarray<T> atan2(const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> atan2(const valarray<T>&, const typename valarray<T>::value_type&);
template<class T> valarray<T> atan2(const typename valarray<T>::value_type&, const valarray<T>&);
template<class T> valarray<T> cos  (const valarray<T>&);
template<class T> valarray<T> cosh (const valarray<T>&);
template<class T> valarray<T> exp  (const valarray<T>&);
template<class T> valarray<T> log  (const valarray<T>&);
template<class T> valarray<T> log10(const valarray<T>&);
template<class T> valarray<T> pow  (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> pow  (const valarray<T>&, const typename valarray<T>::value_type&);
template<class T> valarray<T> pow  (const typename valarray<T>::value_type&, const valarray<T>&);
template<class T> valarray<T> sin  (const valarray<T>&);
template<class T> valarray<T> sinh (const valarray<T>&);
template<class T> valarray<T> sqrt (const valarray<T>&);
template<class T> valarray<T> tan  (const valarray<T>&);
template<class T> valarray<T> tanh (const valarray<T>&);

Mandates: A unique function with the indicated name can be applied (unqualified) to an operand of type T.

This function returns a value of type T or which can be unambiguously implicitly converted to type T.

29.6.3.4 Specialized algorithms [valarray.special]

🔗

template<class T> void swap(valarray<T>& x, valarray<T>& y) noexcept;

Effects: Equivalent to x.swap(y).

29.6.4 Class slice [class.slice]

29.6.4.1 Overview [class.slice.overview]

🔗

namespace std { class slice { public: slice(); slice(size_t, size_t, size_t); slice(const slice&); size_t start() const; size_t size() const; size_t stride() const; friend bool operator==(const slice& x, const slice& y); }; }

The slice class represents a BLAS-like slice from an array.

Such a slice is specified by a starting index, a length, and a stride.258

258)258)

BLAS stands for Basic Linear Algebra Subprograms.

C++ programs can instantiate this class.

See, for example, Dongarra, Du Croz, Duff, and Hammerling: A set of Level 3 Basic Linear Algebra Subprograms; Technical Report MCS-P1-0888, Argonne National Laboratory (USA), Mathematics and Computer Science Division, August, 1988.

29.6.4.2 Constructors [cons.slice]

🔗

slice();
slice(size_t start, size_t length, size_t stride);

The default constructor is equivalent to slice(0, 0, 0).

A default constructor is provided only to permit the declaration of arrays of slices.

The constructor with arguments for a slice takes a start, length, and stride parameter.

[Example 1:

slice(3, 8, 2) constructs a slice which selects elements

3, 5, 7, \dots, 17

from an array.

— end example]

29.6.4.3 Access functions [slice.access]

🔗

size_t start() const;
size_t size() const;
size_t stride() const;

Returns: The start, length, or stride specified by a slice object.

Complexity: Constant time.

29.6.4.4 Operators [slice.ops]

🔗

friend bool operator==(const slice& x, const slice& y);

Effects: Equivalent to: return x.start() == y.start() && x.size() == y.size() && x.stride() == y.stride();

29.6.5 Class template slice_array [template.slice.array]

29.6.5.1 Overview [template.slice.array.overview]

🔗

namespace std { template<class T> class slice_array { public: using value_type = T; void operator= (const valarray<T>&) const; void operator*= (const valarray<T>&) const; void operator/= (const valarray<T>&) const; void operator%= (const valarray<T>&) const; void operator+= (const valarray<T>&) const; void operator-= (const valarray<T>&) const; void operator^= (const valarray<T>&) const; void operator&= (const valarray<T>&) const; void operator|= (const valarray<T>&) const; void operator<<=(const valarray<T>&) const; void operator>>=(const valarray<T>&) const; slice_array(const slice_array&); ~slice_array(); const slice_array& operator=(const slice_array&) const; void operator=(const T&) const; slice_array() = delete; // as implied by declaring copy constructor above }; }

This template is a helper template used by the slice subscript operator slice_array<T> valarray<T>::operator[](slice);

It has reference semantics to a subset of an array specified by a slice object.

[Example 1:

The expression a[slice(1, 5, 3)] = b; has the effect of assigning the elements of b to a slice of the elements in a.

For the slice shown, the elements selected from a are

1, 4, \dots, 13

— end example]

29.6.5.2 Assignment [slice.arr.assign]

🔗

void operator=(const valarray<T>&) const;
const slice_array& operator=(const slice_array&) const;

These assignment operators have reference semantics, assigning the values of the argument array elements to selected elements of the valarray<T> object to which the slice_array object refers.

29.6.5.3 Compound assignment [slice.arr.comp.assign]

🔗

void operator*= (const valarray<T>&) const;
void operator/= (const valarray<T>&) const;
void operator%= (const valarray<T>&) const;
void operator+= (const valarray<T>&) const;
void operator-= (const valarray<T>&) const;
void operator^= (const valarray<T>&) const;
void operator&= (const valarray<T>&) const;
void operator|= (const valarray<T>&) const;
void operator<<=(const valarray<T>&) const;
void operator>>=(const valarray<T>&) const;

These compound assignments have reference semantics, applying the indicated operation to the elements of the argument array and selected elements of the valarray<T> object to which the slice_array object refers.

29.6.5.4 Fill function [slice.arr.fill]

🔗

void operator=(const T&) const;

This function has reference semantics, assigning the value of its argument to the elements of the valarray<T> object to which the slice_array object refers.

29.6.6 The gslice class [class.gslice]

29.6.6.1 Overview [class.gslice.overview]

🔗

namespace std { class gslice { public: gslice(); gslice(size_t s, const valarray<size_t>& l, const valarray<size_t>& d); size_t start() const; valarray<size_t> size() const; valarray<size_t> stride() const; }; }

This class represents a generalized slice out of an array.

A gslice is defined by a starting offset (s), a set of lengths (

l_{j}

), and a set of strides (

d_{j}

The number of lengths shall equal the number of strides.

A gslice represents a mapping from a set of indices (

i_{j}

), equal in number to the number of strides, to a single index k.

It is useful for building multidimensional array classes using the valarray template, which is one-dimensional.

The set of one-dimensional index values specified by a gslice are

k = s + \sum j i_{j} d_{j}

where the multidimensional indices

i_{j}

range in value from 0 to

l_{i j} - 1

[Example 1:

The gslice specification start = 3 length = {2, 4, 3} stride = {19, 4, 1} yields the sequence of one-dimensional indices

k = 3 + (0, 1) \times 19 + (0, 1, 2, 3) \times 4 + (0, 1, 2) \times 1

which are ordered as shown in the following table:

	 $(i_{0}, i_{1}, i_{2}, k) =$ 
		(0,  0,  0,   3),    
		(0,  0,  1,   4),    
		(0,  0,  2,   5),    
		(0,  1,  0,   7),    
		(0,  1,  1,   8),    
		(0,  1,  2,   9),    
		(0,  2,  0,  11), 
		(0,  2,  1,  12), 
		(0,  2,  2,  13), 
		(0,  3,  0,  15), 
		(0,  3,  1,  16), 
		(0,  3,  2,  17), 
		(1,  0,  0,  22), 
		(1,  0,  1,  23), 
		…      
		(1,  3,  2,  36)

That is, the highest-ordered index turns fastest.

— end example]

It is possible to have degenerate generalized slices in which an address is repeated.

[Example 2:

If the stride parameters in the previous example are changed to {1, 1, 1}, the first few elements of the resulting sequence of indices will be

	(0,  0,  0,   3),  
	(0,  0,  1,   4),  
	(0,  0,  2,   5),  
	(0,  1,  0,   4),  
	(0,  1,  1,   5),  
	(0,  1,  2,   6),  
	…

— end example]

If a degenerate slice is used as the argument to the non-const version of operator[](const gslice&), the behavior is undefined.

29.6.6.2 Constructors [gslice.cons]

🔗

gslice();
gslice(size_t start, const valarray<size_t>& lengths,
       const valarray<size_t>& strides);

The default constructor is equivalent to gslice(0, valarray<size_t>(), valarray<size_t>()).

The constructor with arguments builds a gslice based on a specification of start, lengths, and strides, as explained in the previous subclause.

29.6.6.3 Access functions [gslice.access]

🔗

size_t           start()  const;
valarray<size_t> size() const;
valarray<size_t> stride() const;

Returns: The representation of the start, lengths, or strides specified for the gslice.

Complexity: start() is constant time.

size() and stride() are linear in the number of strides.

29.6.7 Class template gslice_array [template.gslice.array]

29.6.7.1 Overview [template.gslice.array.overview]

🔗

namespace std { template<class T> class gslice_array { public: using value_type = T; void operator= (const valarray<T>&) const; void operator*= (const valarray<T>&) const; void operator/= (const valarray<T>&) const; void operator%= (const valarray<T>&) const; void operator+= (const valarray<T>&) const; void operator-= (const valarray<T>&) const; void operator^= (const valarray<T>&) const; void operator&= (const valarray<T>&) const; void operator|= (const valarray<T>&) const; void operator<<=(const valarray<T>&) const; void operator>>=(const valarray<T>&) const; gslice_array(const gslice_array&); ~gslice_array(); const gslice_array& operator=(const gslice_array&) const; void operator=(const T&) const; gslice_array() = delete; // as implied by declaring copy constructor above }; }

This template is a helper template used by the gslice subscript operator

🔗

gslice_array<T> valarray<T>::operator[](const gslice&);

It has reference semantics to a subset of an array specified by a gslice object.

Thus, the expression a[gslice(1, length, stride)] = b has the effect of assigning the elements of b to a generalized slice of the elements in a.

29.6.7.2 Assignment [gslice.array.assign]

🔗

void operator=(const valarray<T>&) const;
const gslice_array& operator=(const gslice_array&) const;

These assignment operators have reference semantics, assigning the values of the argument array elements to selected elements of the valarray<T> object to which the gslice_array refers.

29.6.7.3 Compound assignment [gslice.array.comp.assign]

🔗

void operator*= (const valarray<T>&) const;
void operator/= (const valarray<T>&) const;
void operator%= (const valarray<T>&) const;
void operator+= (const valarray<T>&) const;
void operator-= (const valarray<T>&) const;
void operator^= (const valarray<T>&) const;
void operator&= (const valarray<T>&) const;
void operator|= (const valarray<T>&) const;
void operator<<=(const valarray<T>&) const;
void operator>>=(const valarray<T>&) const;

29.6.7.4 Fill function [gslice.array.fill]

🔗

void operator=(const T&) const;

This function has reference semantics, assigning the value of its argument to the elements of the valarray<T> object to which the gslice_array object refers.

29.6.8 Class template mask_array [template.mask.array]

29.6.8.1 Overview [template.mask.array.overview]

🔗

namespace std { template<class T> class mask_array { public: using value_type = T; void operator= (const valarray<T>&) const; void operator*= (const valarray<T>&) const; void operator/= (const valarray<T>&) const; void operator%= (const valarray<T>&) const; void operator+= (const valarray<T>&) const; void operator-= (const valarray<T>&) const; void operator^= (const valarray<T>&) const; void operator&= (const valarray<T>&) const; void operator|= (const valarray<T>&) const; void operator<<=(const valarray<T>&) const; void operator>>=(const valarray<T>&) const; mask_array(const mask_array&); ~mask_array(); const mask_array& operator=(const mask_array&) const; void operator=(const T&) const; mask_array() = delete; // as implied by declaring copy constructor above }; }

This template is a helper template used by the mask subscript operator:

🔗

mask_array<T> valarray<T>::operator[](const valarray<bool>&);

It has reference semantics to a subset of an array specified by a boolean mask.

Thus, the expression a[mask] = b; has the effect of assigning the elements of b to the masked elements in a (those for which the corresponding element in mask is true).

29.6.8.2 Assignment [mask.array.assign]

🔗

void operator=(const valarray<T>&) const;
const mask_array& operator=(const mask_array&) const;

These assignment operators have reference semantics, assigning the values of the argument array elements to selected elements of the valarray<T> object to which the mask_array object refers.

29.6.8.3 Compound assignment [mask.array.comp.assign]

🔗

void operator*= (const valarray<T>&) const;
void operator/= (const valarray<T>&) const;
void operator%= (const valarray<T>&) const;
void operator+= (const valarray<T>&) const;
void operator-= (const valarray<T>&) const;
void operator^= (const valarray<T>&) const;
void operator&= (const valarray<T>&) const;
void operator|= (const valarray<T>&) const;
void operator<<=(const valarray<T>&) const;
void operator>>=(const valarray<T>&) const;

29.6.8.4 Fill function [mask.array.fill]

🔗

void operator=(const T&) const;

This function has reference semantics, assigning the value of its argument to the elements of the valarray<T> object to which the mask_array object refers.

29.6.9 Class template indirect_array [template.indirect.array]

29.6.9.1 Overview [template.indirect.array.overview]

🔗

namespace std { template<class T> class indirect_array { public: using value_type = T; void operator= (const valarray<T>&) const; void operator*= (const valarray<T>&) const; void operator/= (const valarray<T>&) const; void operator%= (const valarray<T>&) const; void operator+= (const valarray<T>&) const; void operator-= (const valarray<T>&) const; void operator^= (const valarray<T>&) const; void operator&= (const valarray<T>&) const; void operator|= (const valarray<T>&) const; void operator<<=(const valarray<T>&) const; void operator>>=(const valarray<T>&) const; indirect_array(const indirect_array&); ~indirect_array(); const indirect_array& operator=(const indirect_array&) const; void operator=(const T&) const; indirect_array() = delete; // as implied by declaring copy constructor above }; }

This template is a helper template used by the indirect subscript operator

🔗

indirect_array<T> valarray<T>::operator[](const valarray<size_t>&);

It has reference semantics to a subset of an array specified by an indirect_array.

Thus, the expression a[indirect] = b; has the effect of assigning the elements of b to the elements in a whose indices appear in indirect.

29.6.9.2 Assignment [indirect.array.assign]

🔗

void operator=(const valarray<T>&) const;
const indirect_array& operator=(const indirect_array&) const;

These assignment operators have reference semantics, assigning the values of the argument array elements to selected elements of the valarray<T> object to which it refers.

If the indirect_array specifies an element in the valarray<T> object to which it refers more than once, the behavior is undefined.

[Example 1:

int addr[] = {2, 3, 1, 4, 4}; valarray<size_t> indirect(addr, 5); valarray<double> a(0., 10), b(1., 5); a[indirect] = b; results in undefined behavior since element 4 is specified twice in the indirection.

— end example]

29.6.9.3 Compound assignment [indirect.array.comp.assign]

🔗

void operator*= (const valarray<T>&) const;
void operator/= (const valarray<T>&) const;
void operator%= (const valarray<T>&) const;
void operator+= (const valarray<T>&) const;
void operator-= (const valarray<T>&) const;
void operator^= (const valarray<T>&) const;
void operator&= (const valarray<T>&) const;
void operator|= (const valarray<T>&) const;
void operator<<=(const valarray<T>&) const;
void operator>>=(const valarray<T>&) const;

If the indirect_array specifies an element in the valarray<T> object to which it refers more than once, the behavior is undefined.

29.6.9.4 Fill function [indirect.array.fill]

🔗

void operator=(const T&) const;

This function has reference semantics, assigning the value of its argument to the elements of the valarray<T> object to which the indirect_array object refers.

29.6.10 valarray range access [valarray.range]

In the begin and end function templates that follow, unspecified1 is a type that meets the requirements of a mutable Cpp17RandomAccessIterator ([random.access.iterators]) and models contiguous_iterator ([iterator.concept.contiguous]), whose value_type is the template parameter T and whose reference type is T&.

unspecified2 is a type that meets the requirements of a constant Cpp17RandomAccessIterator and models contiguous_iterator, whose value_type is the template parameter T and whose reference type is const T&.

The iterators returned by begin and end for an array are guaranteed to be valid until the member function resize(size_t, T) is called for that array or until the lifetime of that array ends, whichever happens first.

🔗

template<class T> unspecified1 begin(valarray<T>& v);
template<class T> unspecified2 begin(const valarray<T>& v);

Returns: An iterator referencing the first value in the array.

🔗

template<class T> unspecified1 end(valarray<T>& v);
template<class T> unspecified2 end(const valarray<T>& v);

Returns: An iterator referencing one past the last value in the array.

29.7 Mathematical functions for floating-point types [c.math]

29.7.1 Header <cmath> synopsis [cmath.syn]

🔗

namespace std { using float_t = see below; using double_t = see below; } #define HUGE_VAL see below #define HUGE_VALF see below #define HUGE_VALL see below #define INFINITY see below #define NAN see below #define FP_INFINITE see below #define FP_NAN see below #define FP_NORMAL see below #define FP_SUBNORMAL see below #define FP_ZERO see below #define FP_FAST_FMA see below #define FP_FAST_FMAF see below #define FP_FAST_FMAL see below #define FP_ILOGB0 see below #define FP_ILOGBNAN see below #define MATH_ERRNO see below #define MATH_ERREXCEPT see below #define math_errhandling see below namespace std { constexpr floating-point-type acos(floating-point-type x); constexpr float acosf(float x); constexpr long double acosl(long double x); constexpr floating-point-type asin(floating-point-type x); constexpr float asinf(float x); constexpr long double asinl(long double x); constexpr floating-point-type atan(floating-point-type x); constexpr float atanf(float x); constexpr long double atanl(long double x); constexpr floating-point-type atan2(floating-point-type y, floating-point-type x); constexpr float atan2f(float y, float x); constexpr long double atan2l(long double y, long double x); constexpr floating-point-type cos(floating-point-type x); constexpr float cosf(float x); constexpr long double cosl(long double x); constexpr floating-point-type sin(floating-point-type x); constexpr float sinf(float x); constexpr long double sinl(long double x); constexpr floating-point-type tan(floating-point-type x); constexpr float tanf(float x); constexpr long double tanl(long double x); constexpr floating-point-type acosh(floating-point-type x); constexpr float acoshf(float x); constexpr long double acoshl(long double x); constexpr floating-point-type asinh(floating-point-type x); constexpr float asinhf(float x); constexpr long double asinhl(long double x); constexpr floating-point-type atanh(floating-point-type x); constexpr float atanhf(float x); constexpr long double atanhl(long double x); constexpr floating-point-type cosh(floating-point-type x); constexpr float coshf(float x); constexpr long double coshl(long double x); constexpr floating-point-type sinh(floating-point-type x); constexpr float sinhf(float x); constexpr long double sinhl(long double x); constexpr floating-point-type tanh(floating-point-type x); constexpr float tanhf(float x); constexpr long double tanhl(long double x); constexpr floating-point-type exp(floating-point-type x); constexpr float expf(float x); constexpr long double expl(long double x); constexpr floating-point-type exp2(floating-point-type x); constexpr float exp2f(float x); constexpr long double exp2l(long double x); constexpr floating-point-type expm1(floating-point-type x); constexpr float expm1f(float x); constexpr long double expm1l(long double x); constexpr floating-point-type frexp(floating-point-type value, int* exp); constexpr float frexpf(float value, int* exp); constexpr long double frexpl(long double value, int* exp); constexpr int ilogb(floating-point-type x); constexpr int ilogbf(float x); constexpr int ilogbl(long double x); constexpr floating-point-type ldexp(floating-point-type x, int exp); constexpr float ldexpf(float x, int exp); constexpr long double ldexpl(long double x, int exp); constexpr floating-point-type log(floating-point-type x); constexpr float logf(float x); constexpr long double logl(long double x); constexpr floating-point-type log10(floating-point-type x); constexpr float log10f(float x); constexpr long double log10l(long double x); constexpr floating-point-type log1p(floating-point-type x); constexpr float log1pf(float x); constexpr long double log1pl(long double x); constexpr floating-point-type log2(floating-point-type x); constexpr float log2f(float x); constexpr long double log2l(long double x); constexpr floating-point-type logb(floating-point-type x); constexpr float logbf(float x); constexpr long double logbl(long double x); constexpr floating-point-type modf(floating-point-type value, floating-point-type* iptr); constexpr float modff(float value, float* iptr); constexpr long double modfl(long double value, long double* iptr); constexpr floating-point-type scalbn(floating-point-type x, int n); constexpr float scalbnf(float x, int n); constexpr long double scalbnl(long double x, int n); constexpr floating-point-type scalbln(floating-point-type x, long int n); constexpr float scalblnf(float x, long int n); constexpr long double scalblnl(long double x, long int n); constexpr floating-point-type cbrt(floating-point-type x); constexpr float cbrtf(float x); constexpr long double cbrtl(long double x); // [c.math.abs], absolute values constexpr int abs(int j); // freestanding constexpr long int abs(long int j); // freestanding constexpr long long int abs(long long int j); // freestanding constexpr floating-point-type abs(floating-point-type j); // freestanding-deleted constexpr floating-point-type fabs(floating-point-type x); constexpr float fabsf(float x); constexpr long double fabsl(long double x); constexpr floating-point-type hypot(floating-point-type x, floating-point-type y); constexpr float hypotf(float x, float y); constexpr long double hypotl(long double x, long double y); // [c.math.hypot3], three-dimensional hypotenuse constexpr floating-point-type hypot(floating-point-type x, floating-point-type y, floating-point-type z); constexpr floating-point-type pow(floating-point-type x, floating-point-type y); constexpr float powf(float x, float y); constexpr long double powl(long double x, long double y); constexpr floating-point-type sqrt(floating-point-type x); constexpr float sqrtf(float x); constexpr long double sqrtl(long double x); constexpr floating-point-type erf(floating-point-type x); constexpr float erff(float x); constexpr long double erfl(long double x); constexpr floating-point-type erfc(floating-point-type x); constexpr float erfcf(float x); constexpr long double erfcl(long double x); constexpr floating-point-type lgamma(floating-point-type x); constexpr float lgammaf(float x); constexpr long double lgammal(long double x); constexpr floating-point-type tgamma(floating-point-type x); constexpr float tgammaf(float x); constexpr long double tgammal(long double x); constexpr floating-point-type ceil(floating-point-type x); constexpr float ceilf(float x); constexpr long double ceill(long double x); constexpr floating-point-type floor(floating-point-type x); constexpr float floorf(float x); constexpr long double floorl(long double x); floating-point-type nearbyint(floating-point-type x); float nearbyintf(float x); long double nearbyintl(long double x); floating-point-type rint(floating-point-type x); float rintf(float x); long double rintl(long double x); long int lrint(floating-point-type x); long int lrintf(float x); long int lrintl(long double x); long long int llrint(floating-point-type x); long long int llrintf(float x); long long int llrintl(long double x); constexpr floating-point-type round(floating-point-type x); constexpr float roundf(float x); constexpr long double roundl(long double x); constexpr long int lround(floating-point-type x); constexpr long int lroundf(float x); constexpr long int lroundl(long double x); constexpr long long int llround(floating-point-type x); constexpr long long int llroundf(float x); constexpr long long int llroundl(long double x); constexpr floating-point-type trunc(floating-point-type x); constexpr float truncf(float x); constexpr long double truncl(long double x); constexpr floating-point-type fmod(floating-point-type x, floating-point-type y); constexpr float fmodf(float x, float y); constexpr long double fmodl(long double x, long double y); constexpr floating-point-type remainder(floating-point-type x, floating-point-type y); constexpr float remainderf(float x, float y); constexpr long double remainderl(long double x, long double y); constexpr floating-point-type remquo(floating-point-type x, floating-point-type y, int* quo); constexpr float remquof(float x, float y, int* quo); constexpr long double remquol(long double x, long double y, int* quo); constexpr floating-point-type copysign(floating-point-type x, floating-point-type y); constexpr float copysignf(float x, float y); constexpr long double copysignl(long double x, long double y); double nan(const char* tagp); float nanf(const char* tagp); long double nanl(const char* tagp); constexpr floating-point-type nextafter(floating-point-type x, floating-point-type y); constexpr float nextafterf(float x, float y); constexpr long double nextafterl(long double x, long double y); constexpr floating-point-type nexttoward(floating-point-type x, long double y); constexpr float nexttowardf(float x, long double y); constexpr long double nexttowardl(long double x, long double y); constexpr floating-point-type fdim(floating-point-type x, floating-point-type y); constexpr float fdimf(float x, float y); constexpr long double fdiml(long double x, long double y); constexpr floating-point-type fmax(floating-point-type x, floating-point-type y); constexpr float fmaxf(float x, float y); constexpr long double fmaxl(long double x, long double y); constexpr floating-point-type fmin(floating-point-type x, floating-point-type y); constexpr float fminf(float x, float y); constexpr long double fminl(long double x, long double y); constexpr floating-point-type fma(floating-point-type x, floating-point-type y, floating-point-type z); constexpr float fmaf(float x, float y, float z); constexpr long double fmal(long double x, long double y, long double z); // [c.math.lerp], linear interpolation constexpr floating-point-type lerp(floating-point-type a, floating-point-type b, floating-point-type t) noexcept; // [c.math.fpclass], classification / comparison functions constexpr int fpclassify(floating-point-type x); constexpr bool isfinite(floating-point-type x); constexpr bool isinf(floating-point-type x); constexpr bool isnan(floating-point-type x); constexpr bool isnormal(floating-point-type x); constexpr bool signbit(floating-point-type x); constexpr bool isgreater(floating-point-type x, floating-point-type y); constexpr bool isgreaterequal(floating-point-type x, floating-point-type y); constexpr bool isless(floating-point-type x, floating-point-type y); constexpr bool islessequal(floating-point-type x, floating-point-type y); constexpr bool islessgreater(floating-point-type x, floating-point-type y); constexpr bool isunordered(floating-point-type x, floating-point-type y); // [sf.cmath], mathematical special functions // [sf.cmath.assoc.laguerre], associated Laguerre polynomials floating-point-type assoc_laguerre(unsigned n, unsigned m, floating-point-type x); float assoc_laguerref(unsigned n, unsigned m, float x); long double assoc_laguerrel(unsigned n, unsigned m, long double x); // [sf.cmath.assoc.legendre], associated Legendre functions floating-point-type assoc_legendre(unsigned l, unsigned m, floating-point-type x); float assoc_legendref(unsigned l, unsigned m, float x); long double assoc_legendrel(unsigned l, unsigned m, long double x); // [sf.cmath.beta], beta function floating-point-type beta(floating-point-type x, floating-point-type y); float betaf(float x, float y); long double betal(long double x, long double y); // [sf.cmath.comp.ellint.1], complete elliptic integral of the first kind floating-point-type comp_ellint_1(floating-point-type k); float comp_ellint_1f(float k); long double comp_ellint_1l(long double k); // [sf.cmath.comp.ellint.2], complete elliptic integral of the second kind floating-point-type comp_ellint_2(floating-point-type k); float comp_ellint_2f(float k); long double comp_ellint_2l(long double k); // [sf.cmath.comp.ellint.3], complete elliptic integral of the third kind floating-point-type comp_ellint_3(floating-point-type k, floating-point-type nu); float comp_ellint_3f(float k, float nu); long double comp_ellint_3l(long double k, long double nu); // [sf.cmath.cyl.bessel.i], regular modified cylindrical Bessel functions floating-point-type cyl_bessel_i(floating-point-type nu, floating-point-type x); float cyl_bessel_if(float nu, float x); long double cyl_bessel_il(long double nu, long double x); // [sf.cmath.cyl.bessel.j], cylindrical Bessel functions of the first kind floating-point-type cyl_bessel_j(floating-point-type nu, floating-point-type x); float cyl_bessel_jf(float nu, float x); long double cyl_bessel_jl(long double nu, long double x); // [sf.cmath.cyl.bessel.k], irregular modified cylindrical Bessel functions floating-point-type cyl_bessel_k(floating-point-type nu, floating-point-type x); float cyl_bessel_kf(float nu, float x); long double cyl_bessel_kl(long double nu, long double x); // [sf.cmath.cyl.neumann], cylindrical Neumann functions // cylindrical Bessel functions of the second kind floating-point-type cyl_neumann(floating-point-type nu, floating-point-type x); float cyl_neumannf(float nu, float x); long double cyl_neumannl(long double nu, long double x); // [sf.cmath.ellint.1], incomplete elliptic integral of the first kind floating-point-type ellint_1(floating-point-type k, floating-point-type phi); float ellint_1f(float k, float phi); long double ellint_1l(long double k, long double phi); // [sf.cmath.ellint.2], incomplete elliptic integral of the second kind floating-point-type ellint_2(floating-point-type k, floating-point-type phi); float ellint_2f(float k, float phi); long double ellint_2l(long double k, long double phi); // [sf.cmath.ellint.3], incomplete elliptic integral of the third kind floating-point-type ellint_3(floating-point-type k, floating-point-type nu, floating-point-type phi); float ellint_3f(float k, float nu, float phi); long double ellint_3l(long double k, long double nu, long double phi); // [sf.cmath.expint], exponential integral floating-point-type expint(floating-point-type x); float expintf(float x); long double expintl(long double x); // [sf.cmath.hermite], Hermite polynomials floating-point-type hermite(unsigned n, floating-point-type x); float hermitef(unsigned n, float x); long double hermitel(unsigned n, long double x); // [sf.cmath.laguerre], Laguerre polynomials floating-point-type laguerre(unsigned n, floating-point-type x); float laguerref(unsigned n, float x); long double laguerrel(unsigned n, long double x); // [sf.cmath.legendre], Legendre polynomials floating-point-type legendre(unsigned l, floating-point-type x); float legendref(unsigned l, float x); long double legendrel(unsigned l, long double x); // [sf.cmath.riemann.zeta], Riemann zeta function floating-point-type riemann_zeta(floating-point-type x); float riemann_zetaf(float x); long double riemann_zetal(long double x); // [sf.cmath.sph.bessel], spherical Bessel functions of the first kind floating-point-type sph_bessel(unsigned n, floating-point-type x); float sph_besself(unsigned n, float x); long double sph_bessell(unsigned n, long double x); // [sf.cmath.sph.legendre], spherical associated Legendre functions floating-point-type sph_legendre(unsigned l, unsigned m, floating-point-type theta); float sph_legendref(unsigned l, unsigned m, float theta); long double sph_legendrel(unsigned l, unsigned m, long double theta); // [sf.cmath.sph.neumann], spherical Neumann functions; // spherical Bessel functions of the second kind floating-point-type sph_neumann(unsigned n, floating-point-type x); float sph_neumannf(unsigned n, float x); long double sph_neumannl(unsigned n, long double x); }

The contents and meaning of the header <cmath> are the same as the C standard library header <math.h>, with the addition of a three-dimensional hypotenuse function, a linear interpolation function, and the mathematical special functions described in [sf.cmath].

[Note 1:

Several functions have additional overloads in this document, but they have the same behavior as in the C standard library .

— end note]

For each function with at least one parameter of type floating-point-type, the implementation provides an overload for each cv-unqualified floating-point type ([basic.fundamental]) where all uses of floating-point-type in the function signature are replaced with that floating-point type.

For each function with at least one parameter of type floating-point-type other than abs, the implementation also provides additional overloads sufficient to ensure that, if every argument corresponding to a floating-point-type parameter has arithmetic type, then every such argument is effectively cast to the floating-point type with the greatest floating-point conversion rank and greatest floating-point conversion subrank among the types of all such arguments, where arguments of integer type are considered to have the same floating-point conversion rank as double.

If no such floating-point type with the greatest rank and subrank exists, then overload resolution does not result in a usable candidate ([over.match.general]) from the overloads provided by the implementation.

An invocation of nexttoward is ill-formed if the argument corresponding to the floating-point-type parameter has extended floating-point type.

29.7.2 Absolute values [c.math.abs]

[Note 1:

The headers <cstdlib> and <cmath> declare the functions described in this subclause.

— end note]

🔗

constexpr int abs(int j);
constexpr long int abs(long int j);
constexpr long long int abs(long long int j);

Effects: These functions have the semantics specified in the C standard library for the functions abs, labs, and llabs, respectively.

Remarks: If abs is called with an argument of type X for which is_unsigned_v<X> is true and if X cannot be converted to int by integral promotion, the program is ill-formed.

[Note 2:

Allowing arguments that can be promoted to int provides compatibility with C.

— end note]

🔗

constexpr floating-point-type abs(floating-point-type x);

Returns: The absolute value of x.

See also: ISO/IEC 9899:2018, 7.12.7.2, 7.22.6.1

29.7.3 Three-dimensional hypotenuse [c.math.hypot3]

🔗

constexpr floating-point-type hypot(floating-point-type x, floating-point-type y,
                                    floating-point-type z);

Returns:

\sqrt{x^{2} + y^{2} + z^{2}}

29.7.4 Linear interpolation [c.math.lerp]

🔗

constexpr floating-point-type lerp(floating-point-type a, floating-point-type b,
                                   floating-point-type t) noexcept;

Returns:

a + t (b - a)

Remarks: Let r be the value returned.

If isfinite(a) && isfinite(b), then:

(2.1)
If t == 0, then r == a.
(2.2)
If t == 1, then r == b.
(2.3)
If t >= 0 && t <= 1, then isfinite(r).
(2.4)
If isfinite(t) && a == b, then r == a.
(2.5)
If isfinite(t) || !isnan(t) && b-a != 0, then !isnan(r).

Let CMP(x,y) be 1 if x > y, -1 if x < y, and 0 otherwise.

For any t1 and t2, the product of CMP(lerp(a, b, t2), lerp(a, b, t1)), CMP(t2, t1), and CMP(b, a) is non-negative.

29.7.5 Classification / comparison functions [c.math.fpclass]

The classification / comparison functions behave the same as the C macros with the corresponding names defined in the C standard library.

See also: ISO/IEC 9899:2018, 7.12.3, 7.12.4

29.7.6 Mathematical special functions [sf.cmath]

29.7.6.1 General [sf.cmath.general]

If any argument value to any of the functions specified in [sf.cmath] is a NaN (Not a Number), the function shall return a NaN but it shall not report a domain error.

Otherwise, the function shall report a domain error for just those argument values for which:

(1.1)
the function description's Returns: element explicitly specifies a domain and those argument values fall outside the specified domain, or
(1.2)
the corresponding mathematical function value has a nonzero imaginary component, or
(1.3)
the corresponding mathematical function is not mathematically defined.259

Unless otherwise specified, each function is defined for all finite values, for negative infinity, and for positive infinity.

259)259)

A mathematical function is mathematically defined for a given set of argument values (a) if it is explicitly defined for that set of argument values, or (b) if its limiting value exists and does not depend on the direction of approach.

29.7.6.2 Associated Laguerre polynomials [sf.cmath.assoc.laguerre]

🔗

floating-point-type assoc_laguerre(unsigned n, unsigned m, floating-point-type x);
float        assoc_laguerref(unsigned n, unsigned m, float x);
long double  assoc_laguerrel(unsigned n, unsigned m, long double x);

Effects: These functions compute the associated Laguerre polynomials of their respective arguments n, m, and x.

Returns:

L_{n}^{m} (x)

, where

L_{n}^{m}

is given by Formula 29.22,

L_{n + m}

is given by Formula 29.37, n is n, m is m, and x is x.

\begin{matrix} L_{n}^{m} (x) = (- 1)^{m} \frac{d^{m}}{d x^{m}} L_{n + m} (x), for x \geq 0 \\ (29.22) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if n >= 128 or if m >= 128.

29.7.6.3 Associated Legendre functions [sf.cmath.assoc.legendre]

🔗

floating-point-type assoc_legendre(unsigned l, unsigned m, floating-point-type x);
float        assoc_legendref(unsigned l, unsigned m, float x);
long double  assoc_legendrel(unsigned l, unsigned m, long double x);

Effects: These functions compute the associated Legendre functions of their respective arguments l, m, and x.

Returns:

P_{ℓ}^{m} (x)

, where

P_{ℓ}^{m}

is given by Formula 29.23,

P_{ℓ}

is given by Formula 29.38, ℓ is l, m is m, and x is x.

\begin{matrix} P_{ℓ}^{m} (x) = (1 - x^{2})^{m / 2} \frac{d^{m}}{d x^{m}} P_{ℓ} (x), for | x | \leq 1 \\ (29.23) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if l >= 128.

29.7.6.4 Beta function [sf.cmath.beta]

🔗

floating-point-type beta(floating-point-type x, floating-point-type y);
float        betaf(float x, float y);
long double  betal(long double x, long double y);

Effects: These functions compute the beta function of their respective arguments x and y.

Returns:

B (x, y)

, where B is given by Formula 29.24, x is x and y is y.

\begin{matrix} B (x, y) = \frac{Γ (x) Γ (y)}{Γ (x + y)}, for x > 0, y > 0 \\ (29.24) \end{matrix}

29.7.6.5 Complete elliptic integral of the first kind [sf.cmath.comp.ellint.1]

🔗

floating-point-type comp_ellint_1(floating-point-type k);
float        comp_ellint_1f(float k);
long double  comp_ellint_1l(long double k);

Effects: These functions compute the complete elliptic integral of the first kind of their respective arguments k.

Returns: K(k), where K is given by Formula 29.25 and k is k.

\begin{matrix} K (k) = F (k, π / 2), for | k | \leq 1 \\ (29.25) \end{matrix}

29.7.6.6 Complete elliptic integral of the second kind [sf.cmath.comp.ellint.2]

🔗

floating-point-type comp_ellint_2(floating-point-type k);
float        comp_ellint_2f(float k);
long double  comp_ellint_2l(long double k);

Effects: These functions compute the complete elliptic integral of the second kind of their respective arguments k.

Returns: E(k), where E is given by Formula 29.26 and k is k.

\begin{matrix} E (k) = E (k, π / 2), for | k | \leq 1 \\ (29.26) \end{matrix}

29.7.6.7 Complete elliptic integral of the third kind [sf.cmath.comp.ellint.3]

🔗

floating-point-type comp_ellint_3(floating-point-type k, floating-point-type nu);
float        comp_ellint_3f(float k, float nu);
long double  comp_ellint_3l(long double k, long double nu);

Effects: These functions compute the complete elliptic integral of the third kind of their respective arguments k and nu.

Returns:

Π (ν, k)

, where Π is given by Formula 29.27, k is k, and ν is nu.

\begin{matrix} Π (ν, k) = Π (ν, k, π / 2), for | k | \leq 1 \\ (29.27) \end{matrix}

29.7.6.8 Regular modified cylindrical Bessel functions [sf.cmath.cyl.bessel.i]

🔗

floating-point-type cyl_bessel_i(floating-point-type nu, floating-point-type x);
float        cyl_bessel_if(float nu, float x);
long double  cyl_bessel_il(long double nu, long double x);

Effects: These functions compute the regular modified cylindrical Bessel functions of their respective arguments nu and x.

Returns:

I_{ν} (x)

, where

I_{ν}

is given by Formula 29.28, ν is nu, and x is x.

\begin{matrix} I_{ν} (x) = i^{- ν} J_{ν} (i x) = \infty \sum k = 0 \frac{(x / 2)^{ν + 2 k}}{k! Γ (ν + k + 1)}, for x \geq 0 \\ (29.28) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if nu >= 128.

29.7.6.9 Cylindrical Bessel functions of the first kind [sf.cmath.cyl.bessel.j]

🔗

floating-point-type cyl_bessel_j(floating-point-type nu, floating-point-type x);
float        cyl_bessel_jf(float nu, float x);
long double  cyl_bessel_jl(long double nu, long double x);

Effects: These functions compute the cylindrical Bessel functions of the first kind of their respective arguments nu and x.

Returns:

J_{ν} (x)

, where

J_{ν}

is given by Formula 29.29, ν is nu, and x is x.

\begin{matrix} J_{ν} (x) = \infty \sum k = 0 \frac{(- 1)^{k} (x / 2)^{ν + 2 k}}{k! Γ (ν + k + 1)}, for x \geq 0 \\ (29.29) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if nu >= 128.

29.7.6.10 Irregular modified cylindrical Bessel functions [sf.cmath.cyl.bessel.k]

🔗

floating-point-type cyl_bessel_k(floating-point-type nu, floating-point-type x);
float        cyl_bessel_kf(float nu, float x);
long double  cyl_bessel_kl(long double nu, long double x);

Effects: These functions compute the irregular modified cylindrical Bessel functions of their respective arguments nu and x.

Returns:

K_{ν} (x)

, where

K_{ν}

is given by Formula 29.30, ν is nu, and x is x.

\begin{matrix} K_{ν} (x) = (π / 2) i^{ν + 1} (J_{ν} (i x) + i N_{ν} (i x)) = ⎧ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎨ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎩ \begin{matrix} \frac{π}{2} \frac{I_{- ν} (x) - I_{ν} (x)}{sin ν π}, & for x \geq 0 and non-integral ν \frac{π}{2} lim_{μ \to ν} \frac{I_{- μ} (x) - I_{μ} (x)}{sin μ π}, & for x \geq 0 and integral ν \end{matrix} \\ (29.30) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if nu >= 128.

29.7.6.11 Cylindrical Neumann functions [sf.cmath.cyl.neumann]

🔗

floating-point-type cyl_neumann(floating-point-type nu, floating-point-type x);
float        cyl_neumannf(float nu, float x);
long double  cyl_neumannl(long double nu, long double x);

Effects: These functions compute the cylindrical Neumann functions, also known as the cylindrical Bessel functions of the second kind, of their respective arguments nu and x.

Returns:

N_{ν} (x)

, where

N_{ν}

is given by Formula 29.31, ν is nu, and x is x.

\begin{matrix} N_{ν} (x) = ⎧ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎨ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎩ \begin{matrix} \frac{J_{ν} (x) cos ν π - J_{- ν} (x)}{sin ν π}, & for x \geq 0 and non-integral ν lim_{μ \to ν} \frac{J_{μ} (x) cos μ π - J_{- μ} (x)}{sin μ π}, & for x \geq 0 and integral ν \end{matrix} \\ (29.31) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if nu >= 128.

29.7.6.12 Incomplete elliptic integral of the first kind [sf.cmath.ellint.1]

🔗

floating-point-type ellint_1(floating-point-type k, floating-point-type phi);
float        ellint_1f(float k, float phi);
long double  ellint_1l(long double k, long double phi);

Effects: These functions compute the incomplete elliptic integral of the first kind of their respective arguments k and phi (phi measured in radians).

Returns: F(k, φ), where F is given by Formula 29.32, k is k, and φ is phi.

\begin{matrix} F (k, ϕ) = \int_{0}^{ϕ} \frac{d θ}{\sqrt{1 - k^{2} {sin}^{2} θ}}, for | k | \leq 1 \\ (29.32) \end{matrix}

29.7.6.13 Incomplete elliptic integral of the second kind [sf.cmath.ellint.2]

🔗

floating-point-type ellint_2(floating-point-type k, floating-point-type phi);
float        ellint_2f(float k, float phi);
long double  ellint_2l(long double k, long double phi);

Effects: These functions compute the incomplete elliptic integral of the second kind of their respective arguments k and phi (phi measured in radians).

Returns: E(k, φ), where E is given by Formula 29.33, k is k, and φ is phi.

\begin{matrix} E (k, ϕ) = \int_{0}^{ϕ} \sqrt{1 - k^{2} {sin}^{2} θ} d θ, for | k | \leq 1 \\ (29.33) \end{matrix}

29.7.6.14 Incomplete elliptic integral of the third kind [sf.cmath.ellint.3]

🔗

floating-point-type ellint_3(floating-point-type k, floating-point-type nu,
                             floating-point-type phi);
float        ellint_3f(float k, float nu, float phi);
long double  ellint_3l(long double k, long double nu, long double phi);

Effects: These functions compute the incomplete elliptic integral of the third kind of their respective arguments k, nu, and phi (phi measured in radians).

Returns:

Π (ν, k, ϕ)

, where Π is given by Formula 29.34, ν is nu, k is k, and φ is phi.

\begin{matrix} Π (ν, k, ϕ) = \int_{0}^{ϕ} \frac{d θ}{(1 - ν {sin}^{2} θ) \sqrt{1 - k^{2} {sin}^{2} θ}}, for | k | \leq 1 \\ (29.34) \end{matrix}

29.7.6.15 Exponential integral [sf.cmath.expint]

🔗

floating-point-type expint(floating-point-type x);
float        expintf(float x);
long double  expintl(long double x);

Effects: These functions compute the exponential integral of their respective arguments x.

Returns: Ei(x), where Ei is given by Formula 29.35 and x is x.

\begin{matrix} E i (x) = - \int_{- x}^{\infty} \frac{e^{- t}}{t} d t \\ (29.35) \end{matrix}

29.7.6.16 Hermite polynomials [sf.cmath.hermite]

🔗

floating-point-type hermite(unsigned n, floating-point-type x);
float        hermitef(unsigned n, float x);
long double  hermitel(unsigned n, long double x);

Effects: These functions compute the Hermite polynomials of their respective arguments n and x.

Returns:

H_{n} (x)

, where

H_{n}

is given by Formula 29.36, n is n, and x is x.

\begin{matrix} H_{n} (x) = (- 1)^{n} e^{x^{2}} \frac{d^{n}}{d x^{n}} e^{- x^{2}} \\ (29.36) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if n >= 128.

29.7.6.17 Laguerre polynomials [sf.cmath.laguerre]

🔗

floating-point-type laguerre(unsigned n, floating-point-type x);
float        laguerref(unsigned n, float x);
long double  laguerrel(unsigned n, long double x);

Effects: These functions compute the Laguerre polynomials of their respective arguments n and x.

Returns:

L_{n} (x)

, where

L_{n}

is given by Formula 29.37, n is n, and x is x.

\begin{matrix} L_{n} (x) = \frac{e^{x}}{n!} \frac{d^{n}}{d x^{n}} (x^{n} e^{- x}), for x \geq 0 \\ (29.37) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if n >= 128.

29.7.6.18 Legendre polynomials [sf.cmath.legendre]

🔗

floating-point-type legendre(unsigned l, floating-point-type x);
float        legendref(unsigned l, float x);
long double  legendrel(unsigned l, long double x);

Effects: These functions compute the Legendre polynomials of their respective arguments l and x.

Returns:

P_{ℓ} (x)

, where

P_{ℓ}

is given by Formula 29.38, l is l, and x is x.

\begin{matrix} P_{ℓ} (x) = \frac{1}{2^{ℓ} ℓ!} \frac{d^{ℓ}}{d x^{ℓ}} (x^{2} - 1)^{ℓ}, for | x | \leq 1 \\ (29.38) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if l >= 128.

29.7.6.19 Riemann zeta function [sf.cmath.riemann.zeta]

🔗

floating-point-type riemann_zeta(floating-point-type x);
float        riemann_zetaf(float x);
long double  riemann_zetal(long double x);

Effects: These functions compute the Riemann zeta function of their respective arguments x.

Returns: ζ(x), where ζ is given by Formula 29.39 and x is x.

\begin{matrix} ζ (x) = ⎧ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎨ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎪ ⎩ \begin{matrix} \infty \sum k = 1 k^{- x}, & for x > 1 \frac{1}{1 - 2^{1 - x}} \infty \sum k = 1 (- 1)^{k - 1} k^{- x}, & for 0 \leq x \leq 1 2^{x} π^{x - 1} sin (\frac{π x}{2}) Γ (1 - x) ζ (1 - x), & for x < 0 \end{matrix} \\ (29.39) \end{matrix}

29.7.6.20 Spherical Bessel functions of the first kind [sf.cmath.sph.bessel]

🔗

floating-point-type sph_bessel(unsigned n, floating-point-type x);
float        sph_besself(unsigned n, float x);
long double  sph_bessell(unsigned n, long double x);

Effects: These functions compute the spherical Bessel functions of the first kind of their respective arguments n and x.

Returns:

j_{n} (x)

, where

j_{n}

is given by Formula 29.40, n is n, and x is x.

\begin{matrix} j_{n} (x) = (π / 2 x)^{1 / 2} J_{n + 1 / 2} (x), for x \geq 0 \\ (29.40) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if n >= 128.

29.7.6.21 Spherical associated Legendre functions [sf.cmath.sph.legendre]

🔗

floating-point-type sph_legendre(unsigned l, unsigned m, floating-point-type theta);
float        sph_legendref(unsigned l, unsigned m, float theta);
long double  sph_legendrel(unsigned l, unsigned m, long double theta);

Effects: These functions compute the spherical associated Legendre functions of their respective arguments l, m, and theta (theta measured in radians).

Returns:

Y_{ℓ}^{m} (θ, 0)

, where

Y_{ℓ}^{m}

is given by Formula 29.41, l is l, m is m, and θ is theta.

\begin{matrix} Y_{ℓ}^{m} (θ, ϕ) = (- 1)^{m} {[\frac{(2 ℓ + 1)}{4 π} \frac{(ℓ - m)!}{(ℓ + m)!}]}^{1 / 2} P_{ℓ}^{m} (cos θ) e^{i m ϕ}, for | m | \leq ℓ \\ (29.41) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if l >= 128.

29.7.6.22 Spherical Neumann functions [sf.cmath.sph.neumann]

🔗

floating-point-type sph_neumann(unsigned n, floating-point-type x);
float        sph_neumannf(unsigned n, float x);
long double  sph_neumannl(unsigned n, long double x);

Effects: These functions compute the spherical Neumann functions, also known as the spherical Bessel functions of the second kind, of their respective arguments n and x.

Returns:

n_{n} (x)

, where

n_{n}

is given by Formula 29.42, n is n, and x is x.

\begin{matrix} n_{n} (x) = (π / 2 x)^{1 / 2} N_{n + 1 / 2} (x), for x \geq 0 \\ (29.42) \end{matrix}

Remarks: The effect of calling each of these functions is implementation-defined if n >= 128.

29.8 Numbers [numbers]

29.8.1 Header <numbers> synopsis [numbers.syn]

🔗

namespace std::numbers { template<class T> constexpr T e_v = unspecified; template<class T> constexpr T log2e_v = unspecified; template<class T> constexpr T log10e_v = unspecified; template<class T> constexpr T pi_v = unspecified; template<class T> constexpr T inv_pi_v = unspecified; template<class T> constexpr T inv_sqrtpi_v = unspecified; template<class T> constexpr T ln2_v = unspecified; template<class T> constexpr T ln10_v = unspecified; template<class T> constexpr T sqrt2_v = unspecified; template<class T> constexpr T sqrt3_v = unspecified; template<class T> constexpr T inv_sqrt3_v = unspecified; template<class T> constexpr T egamma_v = unspecified; template<class T> constexpr T phi_v = unspecified; template<floating_point T> constexpr T e_v<T> = see below; template<floating_point T> constexpr T log2e_v<T> = see below; template<floating_point T> constexpr T log10e_v<T> = see below; template<floating_point T> constexpr T pi_v<T> = see below; template<floating_point T> constexpr T inv_pi_v<T> = see below; template<floating_point T> constexpr T inv_sqrtpi_v<T> = see below; template<floating_point T> constexpr T ln2_v<T> = see below; template<floating_point T> constexpr T ln10_v<T> = see below; template<floating_point T> constexpr T sqrt2_v<T> = see below; template<floating_point T> constexpr T sqrt3_v<T> = see below; template<floating_point T> constexpr T inv_sqrt3_v<T> = see below; template<floating_point T> constexpr T egamma_v<T> = see below; template<floating_point T> constexpr T phi_v<T> = see below; inline constexpr double e = e_v<double>; inline constexpr double log2e = log2e_v<double>; inline constexpr double log10e = log10e_v<double>; inline constexpr double pi = pi_v<double>; inline constexpr double inv_pi = inv_pi_v<double>; inline constexpr double inv_sqrtpi = inv_sqrtpi_v<double>; inline constexpr double ln2 = ln2_v<double>; inline constexpr double ln10 = ln10_v<double>; inline constexpr double sqrt2 = sqrt2_v<double>; inline constexpr double sqrt3 = sqrt3_v<double>; inline constexpr double inv_sqrt3 = inv_sqrt3_v<double>; inline constexpr double egamma = egamma_v<double>; inline constexpr double phi = phi_v<double>; }

29.8.2 Mathematical constants [math.constants]

The library-defined partial specializations of mathematical constant variable templates are initialized with the nearest representable values of e,

log_{2} e

log_{10} e

, π,

\frac{1}{π}

\frac{1}{\sqrt{π}}

, ln2, ln10,

\sqrt{2}

\sqrt{3}

\frac{1}{\sqrt{3}}

, the Euler-Mascheroni γ constant, and the golden ratio φ constant

\frac{1 + \sqrt{5}}{2}

, respectively.

Pursuant to [namespace.std], a program may partially or explicitly specialize a mathematical constant variable template provided that the specialization depends on a program-defined type.

A program that instantiates a primary template of a mathematical constant variable template is ill-formed.

29.9 Basic linear algebra algorithms [linalg]

29.9.1 Overview [linalg.overview]

Subclause [linalg] defines basic linear algebra algorithms.

The algorithms that access the elements of arrays view those elements through mdspan ([views.multidim]).

29.9.2 Header <linalg> synopsis [linalg.syn]

🔗

namespace std::linalg { // [linalg.tags.order], storage order tags struct column_major_t; inline constexpr column_major_t column_major; struct row_major_t; inline constexpr row_major_t row_major; // [linalg.tags.triangle], triangle tags struct upper_triangle_t; inline constexpr upper_triangle_t upper_triangle; struct lower_triangle_t; inline constexpr lower_triangle_t lower_triangle; // [linalg.tags.diagonal], diagonal tags struct implicit_unit_diagonal_t; inline constexpr implicit_unit_diagonal_t implicit_unit_diagonal; struct explicit_diagonal_t; inline constexpr explicit_diagonal_t explicit_diagonal; // [linalg.layout.packed], class template layout_blas_packed template<class Triangle, class StorageOrder> class layout_blas_packed; // [linalg.helpers], exposition-only helpers // [linalg.helpers.concepts], linear algebra argument concepts template<class T> constexpr bool is-mdspan = see below; // exposition only template<class T> concept in-vector = see below; // exposition only template<class T> concept out-vector = see below; // exposition only template<class T> concept inout-vector = see below; // exposition only template<class T> concept in-matrix = see below; // exposition only template<class T> concept out-matrix = see below; // exposition only template<class T> concept inout-matrix = see below; // exposition only template<class T> concept possibly-packed-inout-matrix = see below; // exposition only template<class T> concept in-object = see below; // exposition only template<class T> concept out-object = see below; // exposition only template<class T> concept inout-object = see below; // exposition only // [linalg.scaled], scaled in-place transformation // [linalg.scaled.scaledaccessor], class template scaled_accessor template<class ScalingFactor, class NestedAccessor> class scaled_accessor; // [linalg.scaled.scaled], function template scaled template<class ScalingFactor, class ElementType, class Extents, class Layout, class Accessor> constexpr auto scaled(ScalingFactor alpha, mdspan<ElementType, Extents, Layout, Accessor> x); // [linalg.conj], conjugated in-place transformation // [linalg.conj.conjugatedaccessor], class template conjugated_accessor template<class NestedAccessor> class conjugated_accessor; // [linalg.conj.conjugated], function template conjugated template<class ElementType, class Extents, class Layout, class Accessor> constexpr auto conjugated(mdspan<ElementType, Extents, Layout, Accessor> a); // [linalg.transp], transpose in-place transformation // [linalg.transp.layout.transpose], class template layout_transpose template<class Layout> class layout_transpose; // [linalg.transp.transposed], function template transposed template<class ElementType, class Extents, class Layout, class Accessor> constexpr auto transposed(mdspan<ElementType, Extents, Layout, Accessor> a); // [linalg.conjtransposed], conjugated transpose in-place transformation template<class ElementType, class Extents, class Layout, class Accessor> constexpr auto conjugate_transposed(mdspan<ElementType, Extents, Layout, Accessor> a); // [linalg.algs.blas1], BLAS 1 algorithms // [linalg.algs.blas1.givens], Givens rotations // [linalg.algs.blas1.givens.lartg], compute Givens rotation template<class Real> struct setup_givens_rotation_result { Real c; Real s; Real r; }; template<class Real> struct setup_givens_rotation_result<complex<Real>> { Real c; complex<Real> s; complex<Real> r; }; template<class Real> setup_givens_rotation_result<Real> setup_givens_rotation(Real a, Real b) noexcept; template<class Real> setup_givens_rotation_result<complex<Real>> setup_givens_rotation(complex<Real> a, complex<Real> b) noexcept; // [linalg.algs.blas1.givens.rot], apply computed Givens rotation template<inout-vector InOutVec1, inout-vector InOutVec2, class Real> void apply_givens_rotation(InOutVec1 x, InOutVec2 y, Real c, Real s); template<class ExecutionPolicy, inout-vector InOutVec1, inout-vector InOutVec2, class Real> void apply_givens_rotation(ExecutionPolicy&& exec, InOutVec1 x, InOutVec2 y, Real c, Real s); template<inout-vector InOutVec1, inout-vector InOutVec2, class Real> void apply_givens_rotation(InOutVec1 x, InOutVec2 y, Real c, complex<Real> s); template<class ExecutionPolicy, inout-vector InOutVec1, inout-vector InOutVec2, class Real> void apply_givens_rotation(ExecutionPolicy&& exec, InOutVec1 x, InOutVec2 y, Real c, complex<Real> s); // [linalg.algs.blas1.swap], swap elements template<inout-object InOutObj1, inout-object InOutObj2> void swap_elements(InOutObj1 x, InOutObj2 y); template<class ExecutionPolicy, inout-object InOutObj1, inout-object InOutObj2> void swap_elements(ExecutionPolicy&& exec, InOutObj1 x, InOutObj2 y); // [linalg.algs.blas1.scal], multiply elements by scalar template<class Scalar, inout-object InOutObj> void scale(Scalar alpha, InOutObj x); template<class ExecutionPolicy, class Scalar, inout-object InOutObj> void scale(ExecutionPolicy&& exec, Scalar alpha, InOutObj x); // [linalg.algs.blas1.copy], copy elements template<in-object InObj, out-object OutObj> void copy(InObj x, OutObj y); template<class ExecutionPolicy, in-object InObj, out-object OutObj> void copy(ExecutionPolicy&& exec, InObj x, OutObj y); // [linalg.algs.blas1.add], add elementwise template<in-object InObj1, in-object InObj2, out-object OutObj> void add(InObj1 x, InObj2 y, OutObj z); template<class ExecutionPolicy, in-object InObj1, in-object InObj2, out-object OutObj> void add(ExecutionPolicy&& exec, InObj1 x, InObj2 y, OutObj z); // [linalg.algs.blas1.dot], dot product of two vectors template<in-vector InVec1, in-vector InVec2, class Scalar> Scalar dot(InVec1 v1, InVec2 v2, Scalar init); template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, class Scalar> Scalar dot(ExecutionPolicy&& exec, InVec1 v1, InVec2 v2, Scalar init); template<in-vector InVec1, in-vector InVec2> auto dot(InVec1 v1, InVec2 v2); template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2> auto dot(ExecutionPolicy&& exec, InVec1 v1, InVec2 v2); template<in-vector InVec1, in-vector InVec2, class Scalar> Scalar dotc(InVec1 v1, InVec2 v2, Scalar init); template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, class Scalar> Scalar dotc(ExecutionPolicy&& exec, InVec1 v1, InVec2 v2, Scalar init); template<in-vector InVec1, in-vector InVec2> auto dotc(InVec1 v1, InVec2 v2); template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2> auto dotc(ExecutionPolicy&& exec, InVec1 v1, InVec2 v2); // [linalg.algs.blas1.ssq], scaled sum of squares of a vector's elements template<class Scalar> struct sum_of_squares_result { Scalar scaling_factor; Scalar scaled_sum_of_squares; }; template<in-vector InVec, class Scalar> sum_of_squares_result<Scalar> vector_sum_of_squares(InVec v, sum_of_squares_result<Scalar> init); template<class ExecutionPolicy, in-vector InVec, class Scalar> sum_of_squares_result<Scalar> vector_sum_of_squares(ExecutionPolicy&& exec, InVec v, sum_of_squares_result<Scalar> init); // [linalg.algs.blas1.nrm2], Euclidean norm of a vector template<in-vector InVec, class Scalar> Scalar vector_two_norm(InVec v, Scalar init); template<class ExecutionPolicy, in-vector InVec, class Scalar> Scalar vector_two_norm(ExecutionPolicy&& exec, InVec v, Scalar init); template<in-vector InVec> auto vector_two_norm(InVec v); template<class ExecutionPolicy, in-vector InVec> auto vector_two_norm(ExecutionPolicy&& exec, InVec v); // [linalg.algs.blas1.asum], sum of absolute values of vector elements template<in-vector InVec, class Scalar> Scalar vector_abs_sum(InVec v, Scalar init); template<class ExecutionPolicy, in-vector InVec, class Scalar> Scalar vector_abs_sum(ExecutionPolicy&& exec, InVec v, Scalar init); template<in-vector InVec> auto vector_abs_sum(InVec v); template<class ExecutionPolicy, in-vector InVec> auto vector_abs_sum(ExecutionPolicy&& exec, InVec v); // [linalg.algs.blas1.iamax], index of maximum absolute value of vector elements template<in-vector InVec> typename InVec::extents_type vector_idx_abs_max(InVec v); template<class ExecutionPolicy, in-vector InVec> typename InVec::extents_type vector_idx_abs_max(ExecutionPolicy&& exec, InVec v); // [linalg.algs.blas1.matfrobnorm], Frobenius norm of a matrix template<in-matrix InMat, class Scalar> Scalar matrix_frob_norm(InMat A, Scalar init); template<class ExecutionPolicy, in-matrix InMat, class Scalar> Scalar matrix_frob_norm(ExecutionPolicy&& exec, InMat A, Scalar init); template<in-matrix InMat> auto matrix_frob_norm(InMat A); template<class ExecutionPolicy, in-matrix InMat> auto matrix_frob_norm(ExecutionPolicy&& exec, InMat A); // [linalg.algs.blas1.matonenorm], one norm of a matrix template<in-matrix InMat, class Scalar> Scalar matrix_one_norm(InMat A, Scalar init); template<class ExecutionPolicy, in-matrix InMat, class Scalar> Scalar matrix_one_norm(ExecutionPolicy&& exec, InMat A, Scalar init); template<in-matrix InMat> auto matrix_one_norm(InMat A); template<class ExecutionPolicy, in-matrix InMat> auto matrix_one_norm(ExecutionPolicy&& exec, InMat A); // [linalg.algs.blas1.matinfnorm], infinity norm of a matrix template<in-matrix InMat, class Scalar> Scalar matrix_inf_norm(InMat A, Scalar init); template<class ExecutionPolicy, in-matrix InMat, class Scalar> Scalar matrix_inf_norm(ExecutionPolicy&& exec, InMat A, Scalar init); template<in-matrix InMat> auto matrix_inf_norm(InMat A); template<class ExecutionPolicy, in-matrix InMat> auto matrix_inf_norm(ExecutionPolicy&& exec, InMat A); // [linalg.algs.blas2], BLAS 2 algorithms // [linalg.algs.blas2.gemv], general matrix-vector product template<in-matrix InMat, in-vector InVec, out-vector OutVec> void matrix_vector_product(InMat A, InVec x, OutVec y); template<class ExecutionPolicy, in-matrix InMat, in-vector InVec, out-vector OutVec> void matrix_vector_product(ExecutionPolicy&& exec, InMat A, InVec x, OutVec y); template<in-matrix InMat, in-vector InVec1, in-vector InVec2, out-vector OutVec> void matrix_vector_product(InMat A, InVec1 x, InVec2 y, OutVec z); template<class ExecutionPolicy, in-matrix InMat, in-vector InVec1, in-vector InVec2, out-vector OutVec> void matrix_vector_product(ExecutionPolicy&& exec, InMat A, InVec1 x, InVec2 y, OutVec z); // [linalg.algs.blas2.symv], symmetric matrix-vector product template<in-matrix InMat, class Triangle, in-vector InVec, out-vector OutVec> void symmetric_matrix_vector_product(InMat A, Triangle t, InVec x, OutVec y); template<class ExecutionPolicy, in-matrix InMat, class Triangle, in-vector InVec, out-vector OutVec> void symmetric_matrix_vector_product(ExecutionPolicy&& exec, InMat A, Triangle t, InVec x, OutVec y); template<in-matrix InMat, class Triangle, in-vector InVec1, in-vector InVec2, out-vector OutVec> void symmetric_matrix_vector_product(InMat A, Triangle t, InVec1 x, InVec2 y, OutVec z); template<class ExecutionPolicy, in-matrix InMat, class Triangle, in-vector InVec1, in-vector InVec2, out-vector OutVec> void symmetric_matrix_vector_product(ExecutionPolicy&& exec, InMat A, Triangle t, InVec1 x, InVec2 y, OutVec z); // [linalg.algs.blas2.hemv], Hermitian matrix-vector product template<in-matrix InMat, class Triangle, in-vector InVec, out-vector OutVec> void hermitian_matrix_vector_product(InMat A, Triangle t, InVec x, OutVec y); template<class ExecutionPolicy, in-matrix InMat, class Triangle, in-vector InVec, out-vector OutVec> void hermitian_matrix_vector_product(ExecutionPolicy&& exec, InMat A, Triangle t, InVec x, OutVec y); template<in-matrix InMat, class Triangle, in-vector InVec1, in-vector InVec2, out-vector OutVec> void hermitian_matrix_vector_product(InMat A, Triangle t, InVec1 x, InVec2 y, OutVec z); template<class ExecutionPolicy, in-matrix InMat, class Triangle, in-vector InVec1, in-vector InVec2, out-vector OutVec> void hermitian_matrix_vector_product(ExecutionPolicy&& exec, InMat A, Triangle t, InVec1 x, InVec2 y, OutVec z); // [linalg.algs.blas2.trmv], triangular matrix-vector product // Overwriting triangular matrix-vector product template<in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec, out-vector OutVec> void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d, InVec x, OutVec y); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec, out-vector OutVec> void triangular_matrix_vector_product(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InVec x, OutVec y); // In-place triangular matrix-vector product template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec> void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d, InOutVec y); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec> void triangular_matrix_vector_product(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutVec y); // Updating triangular matrix-vector product template<in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec1, in-vector InVec2, out-vector OutVec> void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d, InVec1 x, InVec2 y, OutVec z); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec1, in-vector InVec2, out-vector OutVec> void triangular_matrix_vector_product(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InVec1 x, InVec2 y, OutVec z); // [linalg.algs.blas2.trsv], solve a triangular linear system // Solve a triangular linear system, not in place template<in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec, out-vector OutVec, class BinaryDivideOp> void triangular_matrix_vector_solve(InMat A, Triangle t, DiagonalStorage d, InVec b, OutVec x, BinaryDivideOp divide); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec, out-vector OutVec, class BinaryDivideOp> void triangular_matrix_vector_solve(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InVec b, OutVec x, BinaryDivideOp divide); template<in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec, out-vector OutVec> void triangular_matrix_vector_solve(InMat A, Triangle t, DiagonalStorage d, InVec b, OutVec x); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec, out-vector OutVec> void triangular_matrix_vector_solve(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InVec b, OutVec x); // Solve a triangular linear system, in place template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec, class BinaryDivideOp> void triangular_matrix_vector_solve(InMat A, Triangle t, DiagonalStorage d, InOutVec b, BinaryDivideOp divide); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec, class BinaryDivideOp> void triangular_matrix_vector_solve(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutVec b, BinaryDivideOp divide); template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec> void triangular_matrix_vector_solve(InMat A, Triangle t, DiagonalStorage d, InOutVec b); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec> void triangular_matrix_vector_solve(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutVec b); // [linalg.algs.blas2.rank1], nonsymmetric rank-1 matrix update template<in-vector InVec1, in-vector InVec2, inout-matrix InOutMat> void matrix_rank_1_update(InVec1 x, InVec2 y, InOutMat A); template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, inout-matrix InOutMat> void matrix_rank_1_update(ExecutionPolicy&& exec, InVec1 x, InVec2 y, InOutMat A); template<in-vector InVec1, in-vector InVec2, inout-matrix InOutMat> void matrix_rank_1_update_c(InVec1 x, InVec2 y, InOutMat A); template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, inout-matrix InOutMat> void matrix_rank_1_update_c(ExecutionPolicy&& exec, InVec1 x, InVec2 y, InOutMat A); // [linalg.algs.blas2.symherrank1], symmetric or Hermitian rank-1 matrix update template<class Scalar, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_1_update(Scalar alpha, InVec x, InOutMat A, Triangle t); template<class ExecutionPolicy, class Scalar, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_1_update(ExecutionPolicy&& exec, Scalar alpha, InVec x, InOutMat A, Triangle t); template<in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_1_update(InVec x, InOutMat A, Triangle t); template<class ExecutionPolicy, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_1_update(ExecutionPolicy&& exec, InVec x, InOutMat A, Triangle t); template<class Scalar, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_1_update(Scalar alpha, InVec x, InOutMat A, Triangle t); template<class ExecutionPolicy, class Scalar, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_1_update(ExecutionPolicy&& exec, Scalar alpha, InVec x, InOutMat A, Triangle t); template<in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_1_update(InVec x, InOutMat A, Triangle t); template<class ExecutionPolicy, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_1_update(ExecutionPolicy&& exec, InVec x, InOutMat A, Triangle t); // [linalg.algs.blas2.rank2], symmetric and Hermitian rank-2 matrix updates // symmetric rank-2 matrix update template<in-vector InVec1, in-vector InVec2, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_2_update(InVec1 x, InVec2 y, InOutMat A, Triangle t); template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_2_update(ExecutionPolicy&& exec, InVec1 x, InVec2 y, InOutMat A, Triangle t); // Hermitian rank-2 matrix update template<in-vector InVec1, in-vector InVec2, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_2_update(InVec1 x, InVec2 y, InOutMat A, Triangle t); template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_2_update(ExecutionPolicy&& exec, InVec1 x, InVec2 y, InOutMat A, Triangle t); // [linalg.algs.blas3], BLAS 3 algorithms // [linalg.algs.blas3.gemm], general matrix-matrix product template<in-matrix InMat1, in-matrix InMat2, out-matrix OutMat> void matrix_product(InMat1 A, InMat2 B, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, out-matrix OutMat> void matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, OutMat C); template<in-matrix InMat1, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat> void matrix_product(InMat1 A, InMat2 B, InMat3 E, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat> void matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, InMat3 E, OutMat C); // [linalg.algs.blas3.xxmm], symmetric, Hermitian, and triangular matrix-matrix product template<in-matrix InMat1, class Triangle, in-matrix InMat2, out-matrix OutMat> void symmetric_matrix_product(InMat1 A, Triangle t, InMat2 B, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, in-matrix InMat2, out-matrix OutMat> void symmetric_matrix_product(ExecutionPolicy&& exec, InMat1 A, Triangle t, InMat2 B, OutMat C); template<in-matrix InMat1, class Triangle, in-matrix InMat2, out-matrix OutMat> void hermitian_matrix_product(InMat1 A, Triangle t, InMat2 B, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, in-matrix InMat2, out-matrix OutMat> void hermitian_matrix_product(ExecutionPolicy&& exec, InMat1 A, Triangle t, InMat2 B, OutMat C); template<in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat> void triangular_matrix_product(InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat> void triangular_matrix_product(ExecutionPolicy&& exec, InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat C); template<in-matrix InMat1, in-matrix InMat2, class Triangle, out-matrix OutMat> void symmetric_matrix_product(InMat1 A, InMat2 B, Triangle t, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, class Triangle, out-matrix OutMat> void symmetric_matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, Triangle t, OutMat C); template<in-matrix InMat1, in-matrix InMat2, class Triangle, out-matrix OutMat> void hermitian_matrix_product(InMat1 A, InMat2 B, Triangle t, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, class Triangle, out-matrix OutMat> void hermitian_matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, Triangle t, OutMat C); template<in-matrix InMat1, in-matrix InMat2, class Triangle, class DiagonalStorage, out-matrix OutMat> void triangular_matrix_product(InMat1 A, InMat2 B, Triangle t, DiagonalStorage d, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, class Triangle, class DiagonalStorage, out-matrix OutMat> void triangular_matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, Triangle t, DiagonalStorage d, OutMat C); template<in-matrix InMat1, class Triangle, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat> void symmetric_matrix_product(InMat1 A, Triangle t, InMat2 B, InMat3 E, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat> void symmetric_matrix_product(ExecutionPolicy&& exec, InMat1 A, Triangle t, InMat2 B, InMat3 E, OutMat C); template<in-matrix InMat1, class Triangle, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat> void hermitian_matrix_product(InMat1 A, Triangle t, InMat2 B, InMat3 E, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat> void hermitian_matrix_product(ExecutionPolicy&& exec, InMat1 A, Triangle t, InMat2 B, InMat3 E, OutMat C); template<in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat> void triangular_matrix_product(InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, InMat3 E, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat> void triangular_matrix_product(ExecutionPolicy&& exec, InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, InMat3 E, OutMat C); template<in-matrix InMat1, in-matrix InMat2, class Triangle, in-matrix InMat3, out-matrix OutMat> void symmetric_matrix_product(InMat1 A, InMat2 B, Triangle t, InMat3 E, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, class Triangle, in-matrix InMat3, out-matrix OutMat> void symmetric_matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, Triangle t, InMat3 E, OutMat C); template<in-matrix InMat1, in-matrix InMat2, class Triangle, in-matrix InMat3, out-matrix OutMat> void hermitian_matrix_product(InMat1 A, InMat2 B, Triangle t, InMat3 E, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, class Triangle, in-matrix InMat3, out-matrix OutMat> void hermitian_matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, Triangle t, InMat3 E, OutMat C); template<in-matrix InMat1, in-matrix InMat2, class Triangle, class DiagonalStorage, in-matrix InMat3, out-matrix OutMat> void triangular_matrix_product(InMat1 A, InMat2 B, Triangle t, DiagonalStorage d, InMat3 E, OutMat C); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, class Triangle, class DiagonalStorage, in-matrix InMat3, out-matrix OutMat> void triangular_matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, Triangle t, DiagonalStorage d, InMat3 E, OutMat C); // [linalg.algs.blas3.trmm], in-place triangular matrix-matrix product template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat> void triangular_matrix_left_product(InMat A, Triangle t, DiagonalStorage d, InOutMat C); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat> void triangular_matrix_left_product(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutMat C); template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat> void triangular_matrix_right_product(InMat A, Triangle t, DiagonalStorage d, InOutMat C); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat> void triangular_matrix_right_product(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutMat C); // [linalg.algs.blas3.rankk], rank-k update of a symmetric or Hermitian matrix // rank-k symmetric matrix update template<class Scalar, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_k_update(Scalar alpha, InMat A, InOutMat C, Triangle t); template<class ExecutionPolicy, class Scalar, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_k_update(ExecutionPolicy&& exec, Scalar alpha, InMat A, InOutMat C, Triangle t); template<in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_k_update(InMat A, InOutMat C, Triangle t); template<class ExecutionPolicy, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_k_update(ExecutionPolicy&& exec, InMat A, InOutMat C, Triangle t); // rank-k Hermitian matrix update template<class Scalar, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_k_update(Scalar alpha, InMat A, InOutMat C, Triangle t); template<class ExecutionPolicy, class Scalar, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_k_update(ExecutionPolicy&& exec, Scalar alpha, InMat A, InOutMat C, Triangle t); template<in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_k_update(InMat A, InOutMat C, Triangle t); template<class ExecutionPolicy, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_k_update(ExecutionPolicy&& exec, InMat A, InOutMat C, Triangle t); // [linalg.algs.blas3.rank2k], rank-2k update of a symmetric or Hermitian matrix // rank-2k symmetric matrix update template<in-matrix InMat1, in-matrix InMat2, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_2k_update(InMat1 A, InMat2 B, InOutMat C, Triangle t); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, possibly-packed-inout-matrix InOutMat, class Triangle> void symmetric_matrix_rank_2k_update(ExecutionPolicy&& exec, InMat1 A, InMat2 B, InOutMat C, Triangle t); // rank-2k Hermitian matrix update template<in-matrix InMat1, in-matrix InMat2, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_2k_update(InMat1 A, InMat2 B, InOutMat C, Triangle t); template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, possibly-packed-inout-matrix InOutMat, class Triangle> void hermitian_matrix_rank_2k_update(ExecutionPolicy&& exec, InMat1 A, InMat2 B, InOutMat C, Triangle t); // [linalg.algs.blas3.trsm], solve multiple triangular linear systems // solve multiple triangular systems on the left, not-in-place template<in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat, class BinaryDivideOp> void triangular_matrix_matrix_left_solve(InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat X, BinaryDivideOp divide); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat, class BinaryDivideOp> void triangular_matrix_matrix_left_solve(ExecutionPolicy&& exec, InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat X, BinaryDivideOp divide); template<in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat> void triangular_matrix_matrix_left_solve(InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat X); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat> void triangular_matrix_matrix_left_solve(ExecutionPolicy&& exec, InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat X); // solve multiple triangular systems on the right, not-in-place template<in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat, class BinaryDivideOp> void triangular_matrix_matrix_right_solve(InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat X, BinaryDivideOp divide); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat, class BinaryDivideOp> void triangular_matrix_matrix_right_solve(ExecutionPolicy&& exec, InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat X, BinaryDivideOp divide); template<in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat> void triangular_matrix_matrix_right_solve(InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat X); template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage, in-matrix InMat2, out-matrix OutMat> void triangular_matrix_matrix_right_solve(ExecutionPolicy&& exec, InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat X); // solve multiple triangular systems on the left, in-place template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat, class BinaryDivideOp> void triangular_matrix_matrix_left_solve(InMat A, Triangle t, DiagonalStorage d, InOutMat B, BinaryDivideOp divide); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat, class BinaryDivideOp> void triangular_matrix_matrix_left_solve(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutMat B, BinaryDivideOp divide); template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat> void triangular_matrix_matrix_left_solve(InMat A, Triangle t, DiagonalStorage d, InOutMat B); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat> void triangular_matrix_matrix_left_solve(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutMat B); // solve multiple triangular systems on the right, in-place template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat, class BinaryDivideOp> void triangular_matrix_matrix_right_solve(InMat A, Triangle t, DiagonalStorage d, InOutMat B, BinaryDivideOp divide); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat, class BinaryDivideOp> void triangular_matrix_matrix_right_solve(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutMat B, BinaryDivideOp divide); template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat> void triangular_matrix_matrix_right_solve(InMat A, Triangle t, DiagonalStorage d, InOutMat B); template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat> void triangular_matrix_matrix_right_solve(ExecutionPolicy&& exec, InMat A, Triangle t, DiagonalStorage d, InOutMat B); }

29.9.3 General [linalg.general]

For the effects of all functions in [linalg], when the effects are described as “computes

R = E

” or “compute

R = E

” (for some R and mathematical expression E), the following apply:

(1.1)
E has the conventional mathematical meaning as written.
(1.2)
The pattern $x^{T}$ should be read as “the transpose of x.”
(1.3)
The pattern $x^{H}$ should be read as “the conjugate transpose of x.”
(1.4)
When R is the same name as a function parameter whose type is a template parameter with Out in its name, the intent is that the result of the computation is written to the elements of the function parameter R.

Some of the functions and types in [linalg] distinguish between the “rows” and the “columns” of a matrix.

For a matrix A and a multidimensional index i, j in A.extents(),

(2.1)
row i of A is the set of elements A[i, k1] for all k1 such that i, k1 is in A.extents(); and
(2.2)
column j of A is the set of elements A[k0, j] for all k0 such that k0, j is in A.extents().

Some of the functions in [linalg] distinguish between the “upper triangle,” “lower triangle,” and “diagonal” of a matrix.

(3.1)
The diagonal is the set of all elements of A accessed by A[i,i] for 0 ≤ i < min(A.extent(0), A.extent(1)).
(3.2)
The upper triangle of a matrix A is the set of all elements of A accessed by A[i,j] with i ≤ j.

It includes the diagonal.
(3.3)
The lower triangle of A is the set of all elements of A accessed by A[i,j] with i ≥ j.

It includes the diagonal.

For any function F that takes a parameter named t, t applies to accesses done through the parameter preceding t in the parameter list of F.

Let m be such an access-modified function parameter.

F will only access the triangle of m specified by t.

For accesses m[i, j] outside the triangle specified by t, F will use the value

(4.1)
conj-if-needed(m[j, i]) if the name of F starts with hermitian,
(4.2)
m[j, i] if the name of F starts with symmetric, or
(4.3)
the additive identity if the name of F starts with triangular.

[Example 1:

Small vector product accessing only specified triangle.

It would not be a precondition violation for the non-accessed matrix element to be non-zero.

template<class Triangle> void triangular_matrix_vector_2x2_product( mdspan<const float, extents<int, 2, 2>> m, Triangle t, mdspan<const float, extents<int, 2>> x, mdspan<float, extents<int, 2>> y) { static_assert(is_same_v<Triangle, lower_triangle_t> || is_same_v<Triangle, upper_triangle_t>); if constexpr (is_same_v<Triangle, lower_triangle_t>) { y[0] = m[0,0] * x[0]; // + 0 * x[1] y[1] = m[1,0] * x[0] + m[1,1] * x[1]; } else { // upper_triangle_t y[0] = m[0,0] * x[0] + m[0,1] * x[1]; y[1] = /* 0 * x[0] + */ m[1,1] * x[1]; } } — end example]

For any function F that takes a parameter named d, d applies to accesses done through the previous-of-the-previous parameter of d in the parameter list of F.

Let m be such an access-modified function parameter.

If d specifies that an implicit unit diagonal is to be assumed, then

(5.1)
F will not access the diagonal of m; and
(5.2)
the algorithm will interpret m as if it has a unit diagonal, that is, a diagonal each of whose elements behaves as a two-sided multiplicative identity (even if m's value type does not have a two-sided multiplicative identity).

Otherwise, if d specifies that an explicit diagonal is to be assumed, then F will access the diagonal of m.

Within all the functions in [linalg], any calls to abs, conj, imag, and real are unqualified.

Two mdspan objects x and y alias each other, if they have the same extents e, and for every pack of integers i which is a multidimensional index in e, x[i...] and y[i...] refer to the same element.

[Note 1:

This means that x and y view the same elements in the same order.

— end note]

Two mdspan objects x and y overlap each other, if for some pack of integers i that is a multidimensional index in x.extents(), there exists a pack of integers j that is a multidimensional index in y.extents(), such that x[i....] and y[j...] refer to the same element.

[Note 2:

Aliasing is a special case of overlapping.

If x and y do not overlap, then they also do not alias each other.

— end note]

29.9.4 Requirements [linalg.reqs]

29.9.4.1 Linear algebra value types [linalg.reqs.val]

Throughout [linalg], the following types are linear algebra value type:

(1.1)
the value_type type alias of any input or output mdspan parameter(s) of any function in [linalg]; and
(1.2)
the Scalar template parameter (if any) of any function or class in [linalg].

Linear algebra value types shall model semiregular .

A value-initialized object of linear algebra value type shall act as the additive identity.

29.9.4.2 Algorithm and class requirements [linalg.reqs.alg]

[linalg.reqs.alg] lists common requirements for all algorithms and classes in [linalg].

All of the following statements presume that the algorithm's asymptotic complexity requirements, if any, are satisfied.

(2.1)
The function may make arbitrarily many objects of any linear algebra value type, value-initializing or direct-initializing them with any existing object of that type.
(2.2)
The triangular solve algorithms in [linalg.algs.blas2.trsv], [linalg.algs.blas3.trmm], [linalg.algs.blas3.trsm], and [linalg.algs.blas3.inplacetrsm] either have a BinaryDivideOp template parameter (see [linalg.algs.reqs]) and a binary function object parameter divide of that type, or they have effects equivalent to invoking such an algorithm.

Triangular solve algorithms interpret divide(a, b) as a times the multiplicative inverse of b.

Each triangular solve algorithm uses a sequence of evaluations of *, *=, divide, unary +, binary +, +=, unary -, binary -, -=, and = operators that would produce the result specified by the algorithm's Effects and Remarks when operating on elements of a field with noncommutative multiplication.

It is a precondition of the algorithm that any addend, any subtrahend, any partial sum of addends in any order (treating any difference as a sum with the second term negated), any factor, any partial product of factors respecting their order, any numerator (first argument of divide), any denominator (second argument of divide), and any assignment is a well-formed expression.
(2.3)
Each function in [linalg.algs.blas1], [linalg.algs.blas2], and [linalg.algs.blas3] that is not a triangular solve algorithm will use a sequence of evaluations of *, *=, +, +=, and = operators that would produce the result specified by the algorithm's Effects and Remarks when operating on elements of a semiring with noncommutative multiplication.

It is a precondition of the algorithm that any addend, any partial sum of addends in any order, any factor, any partial product of factors respecting their order, and any assignment is a well-formed expression.
(2.4)
If the function has an output mdspan, then all addends, subtrahends (for the triangular solve algorithms), or results of the divide parameter on intermediate terms (if the function takes a divide parameter) are assignable and convertible to the output mdspan's value_type.
(2.5)
The function may reorder addends and partial sums arbitrarily.

[Note 1:
Factors in each product are not reordered; multiplication is not necessarily commutative.
— end note]

[Note 2:

The above requirements do not prohibit implementation approaches and optimization techniques which are not user-observable.

In particular, if for all input and output arguments the value_type is a floating-point type, implementers are free to leverage approximations, use arithmetic operations not explicitly listed above, and compute floating point sums in any way that improves their accuracy.

— end note]

[Note 3:

For all functions in [linalg], suppose that all input and output mdspan have as value_type a floating-point type, and any Scalar template argument has a floating-point type.

Then, functions can do all of the following:

(3.1)
compute floating-point sums in any way that improves their accuracy for arbitrary input;
(3.2)
perform additional arithmetic operations (other than those specified by the function's wording and [linalg.reqs.alg]) in order to improve performance or accuracy; and
(3.3)
use approximations (that might not be exact even if computing with real numbers), instead of computations that would be exact if it were possible to compute without rounding error;

as long as

(3.4)
the function satisfies the complexity requirements; and
(3.5)
the function is logarithmically stable, as defined in Demmel 2007[bib].
Strassen's algorithm for matrix-matrix multiply is an example of a logarithmically stable algorithm.

— end note]

29.9.5 Tag classes [linalg.tags]

29.9.5.1 Storage order tags [linalg.tags.order]

The storage order tags describe the order of elements in an mdspan with layout_blas_packed ([linalg.layout.packed]) layout.

🔗

struct column_major_t {
  explicit column_major_t() = default;
};
inline constexpr column_major_t column_major{};

struct row_major_t {
  explicit row_major_t() = default;
};
inline constexpr row_major_t row_major{};

column_major_t indicates a column-major order, and row_major_t indicates a row-major order.

29.9.5.2 Triangle tags [linalg.tags.triangle]

🔗

struct upper_triangle_t {
  explicit upper_triangle_t() = default;
};
inline constexpr upper_triangle_t upper_triangle{};

struct lower_triangle_t {
  explicit lower_triangle_t() = default;
};
inline constexpr lower_triangle_t lower_triangle{};

These tag classes specify whether algorithms and other users of a matrix (represented as an mdspan) access the upper triangle (upper_triangle_t) or lower triangle (lower_triangle_t) of the matrix (see also [linalg.general]).

This is also subject to the restrictions of implicit_unit_diagonal_t if that tag is also used as a function argument; see below.

29.9.5.3 Diagonal tags [linalg.tags.diagonal]

🔗

struct implicit_unit_diagonal_t {
  explicit implicit_unit_diagonal_t() = default;
};
inline constexpr implicit_unit_diagonal_t implicit_unit_diagonal{};

struct explicit_diagonal_t {
  explicit explicit_diagonal_t() = default;
};
inline constexpr explicit_diagonal_t explicit_diagonal{};

These tag classes specify whether algorithms access the matrix's diagonal entries, and if not, then how algorithms interpret the matrix's implicitly represented diagonal values.

The implicit_unit_diagonal_t tag indicates that an implicit unit diagonal is to be assumed ([linalg.general]).

The explicit_diagonal_t tag indicates that an explicit diagonal is used ([linalg.general]).

29.9.6 Layouts for packed matrix types [linalg.layout.packed]

29.9.6.1 Overview [linalg.layout.packed.overview]

layout_blas_packed is an mdspan layout mapping policy that represents a square matrix that stores only the entries in one triangle, in a packed contiguous format.

Its Triangle template parameter determines whether an mdspan with this layout stores the upper or lower triangle of the matrix.

Its StorageOrder template parameter determines whether the layout packs the matrix's elements in column-major or row-major order.

A StorageOrder of column_major_t indicates column-major ordering.

This packs matrix elements starting with the leftmost (least column index) column, and proceeding column by column, from the top entry (least row index).

A StorageOrder of row_major_t indicates row-major ordering.

This packs matrix elements starting with the topmost (least row index) row, and proceeding row by row, from the leftmost (least column index) entry.

[Note 1:

layout_blas_packed describes the data layout used by the BLAS' Symmetric Packed (SP), Hermitian Packed (HP), and Triangular Packed (TP) matrix types.

— end note]

namespace std::linalg { template<class Triangle, class StorageOrder> class layout_blas_packed { public: using triangle_type = Triangle; using storage_order_type = StorageOrder; template<class Extents> struct mapping { public: using extents_type = Extents; using index_type = typename extents_type::index_type; using size_type = typename extents_type::size_type; using rank_type = typename extents_type::rank_type; using layout_type = layout_blas_packed; // [linalg.layout.packed.cons], constructors constexpr mapping() noexcept = default; constexpr mapping(const mapping&) noexcept = default; constexpr mapping(const extents_type&) noexcept; template<class OtherExtents> constexpr explicit(!is_convertible_v<OtherExtents, extents_type>) mapping(const mapping<OtherExtents>& other) noexcept; constexpr mapping& operator=(const mapping&) noexcept = default; // [linalg.layout.packed.obs], observers constexpr const extents_type& extents() const noexcept { return extents_; } constexpr index_type required_span_size() const noexcept; template<class Index0, class Index1> constexpr index_type operator() (Index0 ind0, Index1 ind1) const noexcept; static constexpr bool is_always_unique() noexcept { return (extents_type::static_extent(0) != dynamic_extent && extents_type::static_extent(0) < 2) || (extents_type::static_extent(1) != dynamic_extent && extents_type::static_extent(1) < 2); } static constexpr bool is_always_exhaustive() noexcept { return true; } static constexpr bool is_always_strided() noexcept { return is_always_unique(); } constexpr bool is_unique() const noexcept { return extents_.extent(0) < 2; } constexpr bool is_exhaustive() const noexcept { return true; } constexpr bool is_strided() const noexcept { return extents_.extent(0) < 2; } constexpr index_type stride(rank_type) const noexcept; template<class OtherExtents> friend constexpr bool operator==(const mapping&, const mapping<OtherExtents>&) noexcept; private: extents_type extents_{}; // exposition only }; }; }

Mandates:

(5.1)
Triangle is either upper_triangle_t or lower_triangle_t,
(5.2)
StorageOrder is either column_major_t or row_major_t,
(5.3)
Extents is a specialization of std::extents,
(5.4)
Extents::rank() equals 2,
(5.5)
one of extents_type::static_extent(0) == dynamic_extent, extents_type::static_extent(1) == dynamic_extent, or extents_type::static_extent(0) == extents_type::static_extent(1) is true, and
(5.6)
if Extents::rank_dynamic() == 0 is true, let $N_{s}$ be equal to Extents::static_extent(0); then, $N_{s} \times (N_{s} + 1)$ is representable as a value of type index_type.

layout_blas_packed<T, SO>::mapping<E> is a trivially copyable type that models regular for each T, SO, and E.

29.9.6.2 Constructors [linalg.layout.packed.cons]

🔗

constexpr mapping(const extents_type& e) noexcept;

Preconditions:

(1.1)
Let N be equal to e.extent(0).

Then, $N \times (N + 1)$ is representable as a value of type index_type ([basic.fundamental]).
(1.2)
e.extent(0) equals e.extent(1).

Effects: Direct-non-list-initializes extents_ with e.

🔗

template<class OtherExtents>
  explicit(!is_convertible_v<OtherExtents, extents_type>)
    constexpr mapping(const mapping<OtherExtents>& other) noexcept;

Constraints: is_constructible_v<extents_type, OtherExtents> is true.

Preconditions: Let N be other.extents().extent(0).

Then,

N \times (N + 1)

is representable as a value of type index_type ([basic.fundamental]).

Effects: Direct-non-list-initializes extents_ with other.extents().

29.9.6.3 Observers [linalg.layout.packed.obs]

🔗

constexpr index_type required_span_size() const noexcept;

Returns: extents_.extent(0) * (extents_.extent(0) + 1)/2.

[Note 1:

For example, a 5 x 5 packed matrix only stores 15 matrix elements.

— end note]

🔗

template<class Index0, class Index1>
  constexpr index_type operator() (Index0 ind0, Index1 ind1) const noexcept;

Constraints:

(2.1)
is_convertible_v<Index0, index_type> is true,
(2.2)
is_convertible_v<Index1, index_type> is true,
(2.3)
is_nothrow_constructible_v<index_type, Index0> is true, and
(2.4)
is_nothrow_constructible_v<index_type, Index1> is true.

Let i be extents_type::index-cast(ind0), and let j be extents_type::index-cast(ind1).

Preconditions: i, j is a multidimensional index in extents_ ([mdspan.overview]).

Returns: Let N be extents_.extent(0).

Then

(5.1)
(*this)(j, i) if i > j is true; otherwise
(5.2)
i + j * (j + 1)/2 if is_same_v<StorageOrder, column_major_t> && is_same_v<Triangle, upper_triangle_t> is true or is_same_v<StorageOrder, row_major_t> && is_same_v<Triangle, lower_triangle_t> is true; otherwise
(5.3)
j + N * i - i * (i + 1)/2.

🔗

constexpr index_type stride(rank_type r) const noexcept;

Preconditions:

(6.1)
is_strided() is true, and
(6.2)
r < extents_type::rank() is true.

Returns: 1.

🔗

template<class OtherExtents>
  friend constexpr bool operator==(const mapping& x, const mapping<OtherExtents>& y) noexcept;

Effects: Equivalent to: return x.extents() == y.extents();

29.9.7 Exposition-only helpers [linalg.helpers]

29.9.7.1 abs-if-needed [linalg.helpers.abs]

The name abs-if-needed denotes an exposition-only function object.

The expression abs-if-needed(E) for a subexpression E whose type is T is expression-equivalent to:

(1.1)
E if T is an unsigned integer;
(1.2)
otherwise, std::abs(E) if T is an arithmetic type,
(1.3)
otherwise, abs(E), if that expression is valid, with overload resolution performed in a context that includes the declaration template<class T> T abs(T) = delete;
If the function selected by overload resolution does not return the absolute value of its input, the program is ill-formed, no diagnostic required.

29.9.7.2 conj-if-needed [linalg.helpers.conj]

The name conj-if-needed denotes an exposition-only function object.

The expression conj-if-needed(E) for a subexpression E whose type is T is expression-equivalent to:

(1.1)
conj(E), if T is not an arithmetic type and the expression conj(E) is valid, with overload resolution performed in a context that includes the declaration template<class T> T conj(const T&) = delete;
If the function selected by overload resolution does not return the complex conjugate of its input, the program is ill-formed, no diagnostic required;
(1.2)
otherwise, E.

29.9.7.3 real-if-needed [linalg.helpers.real]

The name real-if-needed denotes an exposition-only function object.

The expression real-if-needed(E) for a subexpression E whose type is T is expression-equivalent to:

(1.1)
real(E), if T is not an arithmetic type and the expression real(E) is valid, with overload resolution performed in a context that includes the declaration template<class T> T real(const T&) = delete;
If the function selected by overload resolution does not return the real part of its input, the program is ill-formed, no diagnostic required;
(1.2)
otherwise, E.

29.9.7.4 imag-if-needed [linalg.helpers.imag]

The name imag-if-needed denotes an exposition-only function object.

The expression imag-if-needed(E) for a subexpression E whose type is T is expression-equivalent to:

(1.1)
imag(E), if T is not an arithmetic type and the expression imag(E) is valid, with overload resolution performed in a context that includes the declaration template<class T> T imag(const T&) = delete;
If the function selected by overload resolution does not return the imaginary part of its input, the program is ill-formed, no diagnostic required;
(1.2)
otherwise, ((void)E, T{}).

29.9.7.5 Argument concepts [linalg.helpers.concepts]

The exposition-only concepts defined in this section constrain the algorithms in [linalg].

template<class T> constexpr bool is-mdspan = false; template<class ElementType, class Extents, class Layout, class Accessor> constexpr bool is-mdspan<mdspan<ElementType, Extents, Layout, Accessor>> = true; template<class T> concept in-vector = is-mdspan<T> && T::rank() == 1; template<class T> concept out-vector = is-mdspan<T> && T::rank() == 1 && is_assignable_v<typename T::reference, typename T::element_type> && T::is_always_unique(); template<class T> concept inout-vector = is-mdspan<T> && T::rank() == 1 && is_assignable_v<typename T::reference, typename T::element_type> && T::is_always_unique(); template<class T> concept in-matrix = is-mdspan<T> && T::rank() == 2; template<class T> concept out-matrix = is-mdspan<T> && T::rank() == 2 && is_assignable_v<typename T::reference, typename T::element_type> && T::is_always_unique(); template<class T> concept inout-matrix = is-mdspan<T> && T::rank() == 2 && is_assignable_v<typename T::reference, typename T::element_type> && T::is_always_unique(); template<class T> constexpr bool is-layout-blas-packed = false; // exposition only template<class Triangle, class StorageOrder> constexpr bool is-layout-blas-packed<layout_blas_packed<Triangle, StorageOrder>> = true; template<class T> concept possibly-packed-inout-matrix = is-mdspan<T> && T::rank() == 2 && is_assignable_v<typename T::reference, typename T::element_type> && (T::is_always_unique() || is-layout-blas-packed<typename T::layout_type>); template<class T> concept in-object = is-mdspan<T> && (T::rank() == 1 || T::rank() == 2); template<class T> concept out-object = is-mdspan<T> && (T::rank() == 1 || T::rank() == 2) && is_assignable_v<typename T::reference, typename T::element_type> && T::is_always_unique(); template<class T> concept inout-object = is-mdspan<T> && (T::rank() == 1 || T::rank() == 2) && is_assignable_v<typename T::reference, typename T::element_type> && T::is_always_unique();

If a function in [linalg] accesses the elements of a parameter constrained by in-vector, in-matrix, or in-object, those accesses will not modify the elements.

Unless explicitly permitted, any inout-vector, inout-matrix, inout-object, out-vector, out-matrix, out-object, or possibly-packed-inout-matrix parameter of a function in [linalg] shall not overlap any other mdspan parameter of the function.

29.9.7.6 Mandates [linalg.helpers.mandates]

[Note 1:

These exposition-only helper functions use the less constraining input concepts even for the output arguments, because the additional constraint for assignability of elements is not necessary, and they are sometimes used in a context where the third argument is an input type too.

— end note]

template<class MDS1, class MDS2> requires(is-mdspan<MDS1> && is-mdspan<MDS2>) constexpr bool compatible-static-extents(size_t r1, size_t r2) { // exposition only return MDS1::static_extent(r1) == dynamic_extent || MDS2::static_extent(r2) == dynamic_extent || MDS1::static_extent(r1) == MDS2::static_extent(r2)); } template<in-vector In1, in-vector In2, in-vector Out> constexpr bool possibly-addable() { // exposition only return compatible-static-extents<Out, In1>(0, 0) && compatible-static-extents<Out, In2>(0, 0) && compatible-static-extents<In1, In2>(0, 0); } template<in-matrix In1, in-matrix In2, in-matrix Out> constexpr bool possibly-addable() { // exposition only return compatible-static-extents<Out, In1>(0, 0) && compatible-static-extents<Out, In1>(1, 1) && compatible-static-extents<Out, In2>(0, 0) && compatible-static-extents<Out, In2>(1, 1) && compatible-static-extents<In1, In2>(0, 0) && compatible-static-extents<In1, In2>(1, 1); } template<in-matrix InMat, in-vector InVec, in-vector OutVec> constexpr bool possibly-multipliable() { // exposition only return compatible-static-extents<OutVec, InMat>(0, 0) && compatible-static-extents<InMat, InVec>(1, 0); } template<in-vector InVec, in-matrix InMat, in-vector OutVec> constexpr bool possibly-multipliable() { // exposition only return compatible-static-extents<OutVec, InMat>(0, 1) && compatible-static-extents<InMat, InVec>(0, 0); } template<in-matrix InMat1, in-matrix InMat2, in-matrix OutMat> constexpr bool possibly-multipliable() { // exposition only return compatible-static-extents<OutMat, InMat1>(0, 0) && compatible-static-extents<OutMat, InMat2>(1, 1) && compatible-static-extents<InMat1, InMat2>(1, 0); }

29.9.7.7 Preconditions [linalg.helpers.precond]

[Note 1:

— end note]

constexpr bool addable( // exposition only const in-vector auto& in1, const in-vector auto& in2, const in-vector auto& out) { return out.extent(0) == in1.extent(0) && out.extent(0) == in2.extent(0); } constexpr bool addable( // exposition only const in-matrix auto& in1, const in-matrix auto& in2, const in-matrix auto& out) { return out.extent(0) == in1.extent(0) && out.extent(1) == in1.extent(1) && out.extent(0) == in2.extent(0) && out.extent(1) == in2.extent(1); } constexpr bool multipliable( // exposition only const in-matrix auto& in_mat, const in-vector auto& in_vec, const in-vector auto& out_vec) { return out_vec.extent(0) == in_mat.extent(0) && in_mat.extent(1) == in_vec.extent(0); } constexpr bool multipliable( // exposition only const in-vector auto& in_vec, const in-matrix auto& in_mat, const in-vector auto& out_vec) { return out_vec.extent(0) == in_mat.extent(1) && in_mat.extent(0) == in_vec.extent(0); } constexpr bool multipliable( // exposition only const in-matrix auto& in_mat1, const in-matrix auto& in_mat2, const in-matrix auto& out_mat) { return out_mat.extent(0) == in_mat1.extent(0) && out_mat.extent(1) == in_mat2.extent(1) && in1_mat.extent(1) == in_mat2.extent(0); }

29.9.8 Scaled in-place transformation [linalg.scaled]

29.9.8.1 Introduction [linalg.scaled.intro]

The scaled function takes a value alpha and an mdspan x, and returns a new read-only mdspan that represents the elementwise product of alpha with each element of x.

[Example 1: using Vec = mdspan<double, dextents<size_t, 1>>; // z = alpha * x + y void z_equals_alpha_times_x_plus_y(double alpha, Vec x, Vec y, Vec z) { add(scaled(alpha, x), y, z); } // z = alpha * x + beta * y void z_equals_alpha_times_x_plus_beta_times_y(double alpha, Vec x, double beta, Vec y, Vec z) { add(scaled(alpha, x), scaled(beta, y), z); } — end example]

29.9.8.2 Class template scaled_accessor [linalg.scaled.scaledaccessor]

The class template scaled_accessor is an mdspan accessor policy which upon access produces scaled elements.

It is part of the implementation of scaled ([linalg.scaled.scaled]).

namespace std::linalg { template<class ScalingFactor, class NestedAccessor> class scaled_accessor { public: using element_type = add_const_t<decltype(declval<ScalingFactor>() * declval<NestedAccessor::element_type>())>; using reference = remove_const_t<element_type>; using data_handle_type = NestedAccessor::data_handle_type; using offset_policy = scaled_accessor<ScalingFactor, NestedAccessor::offset_policy>; constexpr scaled_accessor() = default; template<class OtherNestedAccessor> explicit(!is_convertible_v<OtherNestedAccessor, NestedAccessor>) constexpr scaled_accessor(const scaled_accessor<ScalingFactor, OtherNestedAccessor>& other); constexpr scaled_accessor(const ScalingFactor& s, const NestedAccessor& a); constexpr reference access(data_handle_type p, size_t i) const; constexpr offset_policy::data_handle_type offset(data_handle_type p, size_t i) const; constexpr const ScalingFactor& scaling_factor() const noexcept { return scaling-factor; } constexpr const NestedAccessor& nested_accessor() const noexcept { return nested-accessor; } private: ScalingFactor scaling-factor{}; // exposition only NestedAccessor nested-accessor{}; // exposition only }; }

Mandates:

(2.1)
element_type is valid and denotes a type,
(2.2)
is_copy_constructible_v<reference> is true,
(2.3)
is_reference_v<element_type> is false,
(2.4)
ScalingFactor models semiregular, and
(2.5)
NestedAccessor meets the accessor policy requirements ([mdspan.accessor.reqmts]).

🔗

template<class OtherNestedAccessor>
  explicit(!is_convertible_v<OtherNestedAccessor, NestedAccessor>)
    constexpr scaled_accessor(const scaled_accessor<ScalingFactor, OtherNestedAccessor>& other);

Constraints: is_constructible_v<NestedAccessor, const OtherNestedAccessor&> is true.

Effects:

(4.1)
Direct-non-list-initializes scaling-factor with other.scaling_factor(), and
(4.2)
direct-non-list-initializes nested-accessor with other.nested_accessor().

🔗

constexpr scaled_accessor(const ScalingFactor& s, const NestedAccessor& a);

Effects:

(5.1)
Direct-non-list-initializes scaling-factor with s, and
(5.2)
direct-non-list-initializes nested-accessor with a.

🔗

constexpr reference access(data_handle_type p, size_t i) const;

Returns: scaling_factor() * NestedAccessor::element_type(nested-accessor.access(p, i))

🔗

constexpr offset_policy::data_handle_type offset(data_handle_type p, size_t i) const;

Returns: nested-accessor.offset(p, i)

29.9.8.3 Function template scaled [linalg.scaled.scaled]

The scaled function template takes a scaling factor alpha and an mdspan x, and returns a new read-only mdspan with the same domain as x, that represents the elementwise product of alpha with each element of x.

🔗

  template<class ScalingFactor,
           class ElementType, class Extents, class Layout, class Accessor>
    constexpr auto scaled(ScalingFactor alpha, mdspan<ElementType, Extents, Layout, Accessor> x);

Let SA be scaled_accessor<ScalingFactor, Accessor>.

Returns: mdspan<typename SA::element_type, Extents, Layout, SA>(x.data_handle(), x.mapping(), SA(alpha, x.accessor()))

[Example 1: void test_scaled(mdspan<double, extents<int, 10>> x) { auto x_scaled = scaled(5.0, x); for (int i = 0; i < x.extent(0); ++i) { assert(x_scaled[i] == 5.0 * x[i]); } } — end example]

29.9.9 Conjugated in-place transformation [linalg.conj]

29.9.9.1 Introduction [linalg.conj.intro]

The conjugated function takes an mdspan x, and returns a new read-only mdspan y with the same domain as x, whose elements are the complex conjugates of the corresponding elements of x.

29.9.9.2 Class template conjugated_accessor [linalg.conj.conjugatedaccessor]

The class template conjugated_accessor is an mdspan accessor policy which upon access produces conjugate elements.

It is part of the implementation of conjugated ([linalg.conj.conjugated]).

namespace std::linalg { template<class NestedAccessor> class conjugated_accessor { public: using element_type = add_const_t<decltype(conj-if-needed(declval<NestedAccessor::element_type>()))>; using reference = remove_const_t<element_type>; using data_handle_type = typename NestedAccessor::data_handle_type; using offset_policy = conjugated_accessor<NestedAccessor::offset_policy>; constexpr conjugated_accessor() = default; template<class OtherNestedAccessor> explicit(!is_convertible_v<OtherNestedAccessor, NestedAccessor>>) constexpr conjugated_accessor(const conjugated_accessor<OtherNestedAccessor>& other); constexpr reference access(data_handle_type p, size_t i) const; constexpr typename offset_policy::data_handle_type offset(data_handle_type p, size_t i) const; constexpr const Accessor& nested_accessor() const noexcept { return nested-accessor_; } private: NestedAccessor nested-accessor_{}; // exposition only }; }

Mandates:

(2.1)
element_type is valid and denotes a type,
(2.2)
is_copy_constructible_v<reference> is true,
(2.3)
is_reference_v<element_type> is false, and
(2.4)
NestedAccessor meets the accessor policy requirements ([mdspan.accessor.reqmts]).

🔗

constexpr conjugated_accessor(const NestedAccessor& acc);

Effects: Direct-non-list-initializes nested-accessor_ with acc.

🔗

template<class OtherNestedAccessor>
  explicit(!is_convertible_v<OtherNestedAccessor, NestedAccessor>>)
    constexpr conjugated_accessor(const conjugated_accessor<OtherNestedAccessor>& other);

Constraints: is_constructible_v<NestedAccessor, const OtherNestedAccessor&> is true.

Effects: Direct-non-list-initializes nested-accessor_ with other.nested_accessor().

🔗

constexpr reference access(data_handle_type p, size_t i) const;

Returns: conj-if-needed(NestedAccessor::element_type(nested-accessor_.access(p, i)))

🔗

constexpr typename offset_policy::data_handle_type offset(data_handle_type p, size_t i) const;

Returns: nested-accessor_.offset(p, i)

29.9.9.3 Function template conjugated [linalg.conj.conjugated]

🔗

  template<class ElementType, class Extents, class Layout, class Accessor>
    constexpr auto conjugated(mdspan<ElementType, Extents, Layout, Accessor> a);

Let A be remove_cvref_t<decltype(a.accessor().nested_accessor())> if Accessor is a specialization of conjugated_accessor, and otherwise conjugated_accessor<Accessor>.

Returns:

(2.1)
If Accessor is a specialization of conjugated_accessor, mdspan<typename A::element_type, Extents, Layout, A>(a.data_handle(), a.mapping(), a.accessor().nested_accessor())
(2.2)
otherwise, mdspan<typename A::element_type, Extents, Layout, A>(a.data_handle(), a.mapping(), conjugated_accessor(a.accessor()))

[Example 1: void test_conjugated_complex(mdspan<complex<double>, extents<int, 10>> a) { auto a_conj = conjugated(a); for (int i = 0; i < a.extent(0); ++i) { assert(a_conj[i] == conj(a[i]); } auto a_conj_conj = conjugated(a_conj); for (int i = 0; i < a.extent(0); ++i) { assert(a_conj_conj[i] == a[i]); } } void test_conjugated_real(mdspan<double, extents<int, 10>> a) { auto a_conj = conjugated(a); for (int i = 0; i < a.extent(0); ++i) { assert(a_conj[i] == a[i]); } auto a_conj_conj = conjugated(a_conj); for (int i = 0; i < a.extent(0); ++i) { assert(a_conj_conj[i] == a[i]); } } — end example]

29.9.10 Transpose in-place transformation [linalg.transp]

29.9.10.1 Introduction [linalg.transp.intro]

layout_transpose is an mdspan layout mapping policy that swaps the two indices, extents, and strides of any unique mdspan layout mapping policy.

The transposed function takes an mdspan representing a matrix, and returns a new mdspan representing the transpose of the input matrix.

29.9.10.2 Exposition-only helpers for layout_transpose and transposed [linalg.transp.helpers]

The exposition-only transpose-extents function takes an extents object representing the extents of a matrix, and returns a new extents object representing the extents of the transpose of the matrix.

The exposition-only alias template transpose-extents-t<InputExtents> gives the type of transpose-extents(e) for a given extents object e of type InputExtents.

🔗

template<class IndexType, size_t InputExtent0, size_t InputExtent1>
  constexpr extents<IndexType, InputExtent1, InputExtent0>
    transpose-extents(const extents<IndexType, InputExtent0, InputExtent1>& in);   // exposition only

Returns: extents<IndexType, InputExtent1, InputExtent0>(in.extent(1), in.extent(0))

template<class InputExtents> using transpose-extents-t = decltype(transpose-extents(declval<InputExtents>())); // exposition only

29.9.10.3 Class template layout_transpose [linalg.transp.layout.transpose]

layout_transpose is an mdspan layout mapping policy that swaps the two indices, extents, and strides of any mdspan layout mapping policy.

namespace std::linalg { template<class Layout> class layout_transpose { public: using nested_layout_type = Layout; template<class Extents> struct mapping { private: using nested-mapping-type = typename Layout::template mapping<transpose-extents-t<Extents>>; // exposition only public: using extents_type = Extents; using index_type = typename extents_type::index_type; using size_type = typename extents_type::size_type; using rank_type = typename extents_type::rank_type; using layout_type = layout_transpose; constexpr explicit mapping(const nested-mapping-type&); constexpr const extents_type& extents() const noexcept { return extents_; } constexpr index_type required_span_size() const { return nested-mapping_.required_span_size(); template<class Index0, class Index1> constexpr index_type operator()(Index0 ind0, Index1 ind1) const { return nested-mapping_(ind1, ind0); } constexpr const nested-mapping-type& nested_mapping() const noexcept { return nested-mapping_; } static constexpr bool is_always_unique() noexcept { return nested-mapping-type::is_always_unique(); } static constexpr bool is_always_exhaustive() noexcept { return nested-mapping-type::is_always_exhaustive(); } static constexpr bool is_always_strided() noexcept { return nested-mapping-type::is_always_strided(); } constexpr bool is_unique() const { return nested-mapping_.is_unique(); } constexpr bool is_exhaustive() const { return nested-mapping_.is_exhaustive(); } constexpr bool is_strided() const { return nested-mapping_.is_strided(); } constexpr index_type stride(size_t r) const; template<class OtherExtents> friend constexpr bool operator==(const mapping& x, const mapping<OtherExtents>& y); }; private: nested-mapping-type nested-mapping_; // exposition only extents_type extents_; // exposition only }; }

Layout shall meet the layout mapping policy requirements ([mdspan.layout.policy.reqmts]).

Mandates:

(3.1)
Extents is a specialization of std::extents, and
(3.2)
Extents::rank() equals 2.

🔗

constexpr explicit mapping(const nested-mapping-type& map);

Effects:

(4.1)
Initializes nested-mapping_ with map, and
(4.2)
initializes extents_ with transpose-extents(map.extents()).

🔗

constexpr index_type stride(size_t r) const;

Preconditions:

(5.1)
is_strided() is true, and
(5.2)
r < 2 is true.

Returns: nested-mapping_.stride(r == 0 ? 1 : 0)

🔗

template<class OtherExtents>
  friend constexpr bool operator==(const mapping& x, const mapping<OtherExtents>& y);

Constraints: The expression x.nested-mapping_ == y.nested-mapping_ is well-formed and its result is convertible to bool.

Returns: x.nested-mapping_ == y.nested-mapping_.

29.9.10.4 Function template transposed [linalg.transp.transposed]

The transposed function takes a rank-2 mdspan representing a matrix, and returns a new mdspan representing the input matrix's transpose.

The input matrix's data are not modified, and the returned mdspan accesses the input matrix's data in place.

🔗

  template<class ElementType, class Extents, class Layout, class Accessor>
    constexpr auto transposed(mdspan<ElementType, Extents, Layout, Accessor> a);

Mandates: Extents::rank() == 2 is true.

Let ReturnExtents be transpose-extents-t<Extents>.

Let R be mdspan<ElementType, ReturnExtents, ReturnLayout, Accessor>, where ReturnLayout is:

(3.1)
layout_right if Layout is layout_left;
(3.2)
otherwise, layout_left if Layout is layout_right;
(3.3)
otherwise, layout_stride if Layout is layout_stride;
(3.4)
otherwise, layout_blas_packed<OppositeTriangle, OppositeStorageOrder>, if Layout is
layout_blas_packed<Triangle, StorageOrder> for some Triangle and StorageOrder, where
- (3.4.1)
  OppositeTriangle is conditional_t<is_same_v<Triangle, upper_triangle_t>, lower_triangle_t, upper_triangle_t> and
- (3.4.2)
  OppositeStorageOrder is conditional_t<is_same_v<StorageOrder, column_major_t>, row_major_t, column_major_t>
(3.5)
otherwise, NestedLayout if Layout is layout_transpose<NestedLayout> for some NestedLayout;
(3.6)
otherwise, layout_transpose<Layout>.

Returns: With ReturnMapping being the type typename ReturnLayout::template mapping<ReturnExtents>:

(4.1)
if Layout is layout_left, layout_right, or a specialization of layout_blas_packed, R(a.data_handle(), ReturnMapping(transpose-extents(a.mapping().extents())), a.accessor())
(4.2)
otherwise, if Layout is layout_stride, R(a.data_handle(), ReturnMapping(transpose-extents(a.mapping().extents()), array{a.mapping().stride(1), a.mapping().stride(0)}), a.accessor())
(4.3)
otherwise, if Layout is a specialization of layout_transpose, R(a.data_handle(), a.mapping().nested_mapping(), a.accessor())
(4.4)
otherwise, R(a.data_handle(), ReturnMapping(a.mapping()), a.accessor())

[Example 1: void test_transposed(mdspan<double, extents<size_t, 3, 4>> a) { const auto num_rows = a.extent(0); const auto num_cols = a.extent(1); auto a_t = transposed(a); assert(num_rows == a_t.extent(1)); assert(num_cols == a_t.extent(0)); assert(a.stride(0) == a_t.stride(1)); assert(a.stride(1) == a_t.stride(0)); for (size_t row = 0; row < num_rows; ++row) { for (size_t col = 0; col < num_rows; ++col) { assert(a[row, col] == a_t[col, row]); } } auto a_t_t = transposed(a_t); assert(num_rows == a_t_t.extent(0)); assert(num_cols == a_t_t.extent(1)); assert(a.stride(0) == a_t_t.stride(0)); assert(a.stride(1) == a_t_t.stride(1)); for (size_t row = 0; row < num_rows; ++row) { for (size_t col = 0; col < num_rows; ++col) { assert(a[row, col] == a_t_t[row, col]); } } } — end example]

29.9.11 Conjugate transpose in-place transform [linalg.conjtransposed]

The conjugate_transposed function returns a conjugate transpose view of an object.

This combines the effects of transposed and conjugated.

🔗

  template<class ElementType, class Extents, class Layout, class Accessor>
    constexpr auto conjugate_transposed(mdspan<ElementType, Extents, Layout, Accessor> a);

Effects: Equivalent to: return conjugated(transposed(a));

[Example 1: void test_conjugate_transposed(mdspan<complex<double>, extents<size_t, 3, 4>> a) { const auto num_rows = a.extent(0); const auto num_cols = a.extent(1); auto a_ct = conjugate_transposed(a); assert(num_rows == a_ct.extent(1)); assert(num_cols == a_ct.extent(0)); assert(a.stride(0) == a_ct.stride(1)); assert(a.stride(1) == a_ct.stride(0)); for (size_t row = 0; row < num_rows; ++row) { for (size_t col = 0; col < num_rows; ++col) { assert(a[row, col] == conj(a_ct[col, row])); } } auto a_ct_ct = conjugate_transposed(a_ct); assert(num_rows == a_ct_ct.extent(0)); assert(num_cols == a_ct_ct.extent(1)); assert(a.stride(0) == a_ct_ct.stride(0)); assert(a.stride(1) == a_ct_ct.stride(1)); for (size_t row = 0; row < num_rows; ++row) { for (size_t col = 0; col < num_rows; ++col) { assert(a[row, col] == a_ct_ct[row, col]); assert(conj(a_ct[col, row]) == a_ct_ct[row, col]); } } } — end example]

29.9.12 Algorithm requirements based on template parameter name [linalg.algs.reqs]

Throughout [linalg.algs.blas1], [linalg.algs.blas2], and [linalg.algs.blas3], where the template parameters are not constrained, the names of template parameters are used to express the following constraints.

(1.1)
is_execution_policy<ExecutionPolicy>::value is true ([execpol.type]).
(1.2)
Real is any type such that complex<Real> is specified ([complex.numbers.general]).
(1.3)
Triangle is either upper_triangle_t or lower_triangle_t.
(1.4)
DiagonalStorage is either implicit_unit_diagonal_t or explicit_diagonal_t.

[Note 1:

Function templates that have a template parameter named ExecutionPolicy are parallel algorithms ([algorithms.parallel.defns]).

— end note]

29.9.13 BLAS 1 algorithms [linalg.algs.blas1]

29.9.13.1 Complexity [linalg.algs.blas1.complexity]

Complexity: All algorithms in [linalg.algs.blas1] with mdspan parameters perform a count of mdspan array accesses and arithmetic operations that is linear in the maximum product of extents of any mdspan parameter.

29.9.13.2 Givens rotations [linalg.algs.blas1.givens]

29.9.13.2.1 Compute Givens rotation [linalg.algs.blas1.givens.lartg]

🔗

template<class Real>
  setup_givens_rotation_result<Real> setup_givens_rotation(Real a, Real b) noexcept;

template<class Real>
  setup_givens_rotation_result<complex<Real>>
    setup_givens_rotation(complex<Real> a, complex<Real> b) noexcept;

These functions compute the Givens plane rotation represented by the two values c and s such that the 2 x 2 system of equations

[\begin{matrix} c & s - ¯ ¯ ¯ s & c \end{matrix}] \cdot [\begin{matrix} a b \end{matrix}] = [\begin{matrix} r 0 \end{matrix}]

holds, where c is always a real scalar, and

c^{2} + | s |^{2} = 1

That is, c and s represent a 2 x 2 matrix, that when multiplied by the right by the input vector whose components are a and b, produces a result vector whose first component r is the Euclidean norm of the input vector, and whose second component is zero.

[Note 1:

These functions correspond to the LAPACK function xLARTG[bib].

— end note]

Returns: c, s, r, where c and s form the Givens plane rotation corresponding to the input a and b, and r is the Euclidean norm of the two-component vector formed by a and b.

29.9.13.2.2 Apply a computed Givens rotation to vectors [linalg.algs.blas1.givens.rot]

🔗

template<inout-vector InOutVec1, inout-vector InOutVec2, class Real>
  void apply_givens_rotation(InOutVec1 x, InOutVec2 y, Real c, Real s);
template<class ExecutionPolicy, inout-vector InOutVec1, inout-vector InOutVec2, class Real>
  void apply_givens_rotation(ExecutionPolicy&& exec,
                             InOutVec1 x, InOutVec2 y, Real c, Real s);
template<inout-vector InOutVec1, inout-vector InOutVec2, class Real>
  void apply_givens_rotation(InOutVec1 x, InOutVec2 y, Real c, complex<Real> s);
template<class ExecutionPolicy, inout-vector InOutVec1, inout-vector InOutVec2, class Real>
  void apply_givens_rotation(ExecutionPolicy&& exec,
                             InOutVec1 x, InOutVec2 y, Real c, complex<Real> s);

[Note 1:

These functions correspond to the BLAS function xROT[bib].

— end note]

Mandates: compatible-static-extents<InOutVec1, InOutVec2>(0, 0) is true.

Preconditions: x.extent(0) equals y.extent(0).

Effects: Applies the plane rotation specified by c and s to the input vectors x and y, as if the rotation were a 2 x 2 matrix and the input vectors were successive rows of a matrix with two rows.

29.9.13.3 Swap matrix or vector elements [linalg.algs.blas1.swap]

🔗

template<inout-object InOutObj1, inout-object InOutObj2>
  void swap_elements(InOutObj1 x, InOutObj2 y);
template<class ExecutionPolicy, inout-object InOutObj1, inout-object InOutObj2>
  void swap_elements(ExecutionPolicy&& exec, InOutObj1 x, InOutObj2 y);

[Note 1:

These functions correspond to the BLAS function xSWAP[bib].

— end note]

Constraints: x.rank() equals y.rank().

Mandates: For all r in the range [0, x.rank()), compatible-static-extents<InOutObj1, InOutObj2>(r, r) is true.

Preconditions: x.extents() equals y.extents().

Effects: Swaps all corresponding elements of x and y.

29.9.13.4 Multiply the elements of an object in place by a scalar [linalg.algs.blas1.scal]

🔗

template<class Scalar, inout-object InOutObj>
  void scale(Scalar alpha, InOutObj x);
template<class ExecutionPolicy, class Scalar, inout-object InOutObj>
  void scale(ExecutionPolicy&& exec, Scalar alpha, InOutObj x);

[Note 1:

These functions correspond to the BLAS function xSCAL[bib].

— end note]

Effects: Overwrites x with the result of computing the elementwise multiplication αx, where the scalar α is alpha.

29.9.13.5 Copy elements of one matrix or vector into another [linalg.algs.blas1.copy]

🔗

template<in-object InObj, out-object OutObj>
  void copy(InObj x, OutObj y);
template<class ExecutionPolicy, in-object InObj, out-object OutObj>
  void copy(ExecutionPolicy&& exec, InObj x, OutObj y);

[Note 1:

These functions correspond to the BLAS function xCOPY[bib].

— end note]

Constraints: x.rank() equals y.rank().

Mandates: For all r in the range

[0, x.rank())

, compatible-static-extents<InObj, OutObj>(r, r) is true.

Preconditions: x.extents() equals y.extents().

Effects: Assigns each element of x to the corresponding element of y.

29.9.13.6 Add vectors or matrices elementwise [linalg.algs.blas1.add]

🔗

template<in-object InObj1, in-object InObj2, out-object OutObj>
  void add(InObj1 x, InObj2 y, OutObj z);
template<class ExecutionPolicy, in-object InObj1, in-object InObj2, out-object OutObj>
  void add(ExecutionPolicy&& exec,
           InObj1 x, InObj2 y, OutObj z);

[Note 1:

These functions correspond to the BLAS function xAXPY[bib].

— end note]

Constraints: x.rank(), y.rank(), and z.rank() are all equal.

Mandates: possibly-addable<InObj1, InObj2, OutObj>() is true.

Preconditions: addable(x,y,z) is true.

Effects: Computes

z = x + y

Remarks: z may alias x or y.

29.9.13.7 Dot product of two vectors [linalg.algs.blas1.dot]

[Note 1:

The functions in this section correspond to the BLAS functions xDOT, xDOTU, and xDOTC[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas1.dot].

Mandates: compatible-static-extents<InVec1, InVec2>(0, 0) is true.

Preconditions: v1.extent(0) equals v2.extent(0).

🔗

template<in-vector InVec1, in-vector InVec2, class Scalar>
  Scalar dot(InVec1 v1, InVec2 v2, Scalar init);
template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, class Scalar>
  Scalar dot(ExecutionPolicy&& exec,
             InVec1 v1, InVec2 v2, Scalar init);

These functions compute a non-conjugated dot product with an explicitly specified result type.

Returns: Let N be v1.extent(0).

(6.1)
init if N is zero;
(6.2)
otherwise, GENERALIZED_SUM(plus<>(), init, v1[0]*v2[0], …, v1[N-1]*v2[N-1]).

Remarks: If InVec1::value_type, InVec2::value_type, and Scalar are all floating-point types or specializations of complex, and if Scalar has higher precision than InVec1::value_type or InVec2::value_type, then intermediate terms in the sum use Scalar's precision or greater.

🔗

  template<in-vector InVec1, in-vector InVec2>
    auto dot(InVec1 v1, InVec2 v2);
  template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2>
    auto dot(ExecutionPolicy&& exec,
             InVec1 v1, InVec2 v2);

These functions compute a non-conjugated dot product with a default result type.

Effects: Let T be decltype(declval<typename InVec1::value_type>() * declval<typename InVec2::value_type>()).

Then,

(9.1)
the two-parameter overload is equivalent to: return dot(v1, v2, T{}); and
(9.2)
the three-parameter overload is equivalent to: return dot(std::forward<ExecutionPolicy>(exec), v1, v2, T{});

🔗

template<in-vector InVec1, in-vector InVec2, class Scalar>
  Scalar dotc(InVec1 v1, InVec2 v2, Scalar init);
template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, class Scalar>
  Scalar dotc(ExecutionPolicy&& exec,
              InVec1 v1, InVec2 v2, Scalar init);

These functions compute a conjugated dot product with an explicitly specified result type.

Effects:

(11.1)
The three-parameter overload is equivalent to: return dot(conjugated(v1), v2, init); and
(11.2)
the four-parameter overload is equivalent to: return dot(std::forward<ExecutionPolicy>(exec), conjugated(v1), v2, init);

🔗

template<in-vector InVec1, in-vector InVec2>
  auto dotc(InVec1 v1, InVec2 v2);
template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2>
  auto dotc(ExecutionPolicy&& exec,
            InVec1 v1, InVec2 v2);

These functions compute a conjugated dot product with a default result type.

Effects: Let T be decltype(conj-if-needed(declval<typename InVec1::value_type>()) * declval<typename InVec2::value_type>()).

Then,

(13.1)
the two-parameter overload is equivalent to: return dotc(v1, v2, T{}); and
(13.2)
the three-parameter overload is equivalent to return dotc(std::forward<ExecutionPolicy>(exec), v1, v2, T{});

29.9.13.8 Scaled sum of squares of a vector's elements [linalg.algs.blas1.ssq]

🔗

template<in-vector InVec, class Scalar>
  sum_of_squares_result<Scalar> vector_sum_of_squares(InVec v, sum_of_squares_result<Scalar> init);
template<class ExecutionPolicy, in-vector InVec, class Scalar>
  sum_of_squares_result<Scalar> vector_sum_of_squares(ExecutionPolicy&& exec,
                                                      InVec v, sum_of_squares_result<Scalar> init);

[Note 1:

These functions correspond to the LAPACK function xLASSQ[bib].

— end note]

Mandates: decltype(abs-if-needed(declval<typename InVec::value_type>())) is convertible to Scalar.

Effects: Returns a value result such that

(3.1)
result.scaling_factor is the maximum of init.scaling_factor and abs-if-needed(x[i]) for all i in the domain of v; and
(3.2)
let s2init be init.scaling_factor * init.scaling_factor * init.scaled_sum_of_squares then result.scaling_factor * result.scaling_factor * result.scaled_sum_of_squares equals the sum of s2init and the squares of abs-if-needed(x[i]) for all i in the domain of v.

Remarks: If InVec::value_type, and Scalar are all floating-point types or specializations of complex, and if Scalar has higher precision than InVec::value_type, then intermediate terms in the sum use Scalar's precision or greater.

29.9.13.9 Euclidean norm of a vector [linalg.algs.blas1.nrm2]

🔗

template<in-vector InVec, class Scalar>
  Scalar vector_two_norm(InVec v, Scalar init);
template<class ExecutionPolicy, in-vector InVec, class Scalar>
  Scalar vector_two_norm(ExecutionPolicy&& exec, InVec v, Scalar init);

[Note 1:

These functions correspond to the BLAS function xNRM2[bib].

— end note]

Mandates: Let a be abs-if-needed(declval<typename InVec::value_type>()).

Then, decltype(init + a * a is convertible to Scalar.

Returns: The square root of the sum of the square of init and the squares of the absolute values of the elements of v.

[Note 2:

For init equal to zero, this is the Euclidean norm (also called 2-norm) of the vector v.

— end note]

[Note 3:

An implementation of this function for floating-point types T can use the scaled_sum_of_squares result from vector_sum_of_squares(x, {.scaling_factor=1.0, .scaled_sum_of_squares=init}).

— end note]

🔗

template<in-vector InVec>
  auto vector_two_norm(InVec v);
template<class ExecutionPolicy, in-vector InVec>
  auto vector_two_norm(ExecutionPolicy&& exec, InVec v);

Effects: Let a be abs-if-needed(declval<typename InVec::value_type>()).

Let T be decltype(a * a).

Then,

(5.1)
the one-parameter overload is equivalent to: return vector_two_norm(v, T{}); and
(5.2)
the two-parameter overload is equivalent to: return vector_two_norm(std::forward<ExecutionPolicy>(exec), v, T{});

29.9.13.10 Sum of absolute values of vector elements [linalg.algs.blas1.asum]

🔗

template<in-vector InVec, class Scalar>
  Scalar vector_abs_sum(InVec v, Scalar init);
template<class ExecutionPolicy, in-vector InVec, class Scalar>
  Scalar vector_abs_sum(ExecutionPolicy&& exec, InVec v, Scalar init);

[Note 1:

These functions correspond to the BLAS functions SASUM, DASUM, SCASUM, and DZASUM[bib].

— end note]

Mandates: decltype(init + abs-if-needed(real-if-needed(declval<typename InVec::value_type>())) + abs-if-needed(imag-if-needed(declval<typename InVec::value_type>()))) is convertible to Scalar.

Returns: Let N be v.extent(0).

(3.1)
init if N is zero;
(3.2)
otherwise, if InVec::value_type is an arithmetic type, GENERALIZED_SUM(plus<>(), init, abs-if-needed(v[0]), …, abs-if-needed(v[N-1]))
(3.3)
otherwise, GENERALIZED_SUM(plus<>(), init, abs-if-needed(real-if-needed(v[0])) + abs-if-needed(imag-if-needed(v[0])), …, abs-if-needed(real-if-needed(v[N-1])) + abs-if-needed(imag-if-needed(v[N-1])))

Remarks: If InVec::value_type and Scalar are all floating-point types or specializations of complex, and if Scalar has higher precision than InVec::value_type, then intermediate terms in the sum use Scalar's precision or greater.

🔗

template<in-vector InVec>
  auto vector_abs_sum(InVec v);
template<class ExecutionPolicy, in-vector InVec>
  auto vector_abs_sum(ExecutionPolicy&& exec, InVec v);

Effects: Let T be typename InVec::value_type.

Then,

(5.1)
the one-parameter overload is equivalent to: return vector_abs_sum(v, T{}); and
(5.2)
the two-parameter overload is equivalent to: return vector_abs_sum(std::forward<ExecutionPolicy>(exec), v, T{});

29.9.13.11 Index of maximum absolute value of vector elements [linalg.algs.blas1.iamax]

🔗

template<in-vector InVec>
  typename InVec::extents_type vector_idx_abs_max(InVec v);
template<class ExecutionPolicy, in-vector InVec>
  typename InVec::extents_type vector_idx_abs_max(ExecutionPolicy&& exec, InVec v);

[Note 1:

These functions correspond to the BLAS function IxAMAX[bib].

— end note]

Let T be decltype(abs-if-needed(real-if-needed(declval<typename InVec::value_type>())) + abs-if-needed(imag-if-needed(declval<typename InVec::value_type>())))

Mandates: declval<T>() < declval<T>() is a valid expression.

Returns:

(4.1)
numeric_limits<typename InVec::size_type>::max() if v has zero elements;
(4.2)
otherwise, the index of the first element of v having largest absolute value, if InVec::value_type is an arithmetic type;
(4.3)
otherwise, the index of the first element $v_{e}$ of v for which abs-if-needed(real-if-needed( $v_{e}$ )) + abs-if-needed(imag-if-needed( $v_{e}$ )) has the largest value.

29.9.13.12 Frobenius norm of a matrix [linalg.algs.blas1.matfrobnorm]

[Note 1:

These functions exist in the BLAS standard[bib] but are not part of the reference implementation.

— end note]

🔗

template<in-matrix InMat, class Scalar>
  Scalar matrix_frob_norm(InMat A, Scalar init);
template<class ExecutionPolicy, in-matrix InMat, class Scalar>
  Scalar matrix_frob_norm(ExecutionPolicy&& exec, InMat A, Scalar init);

Mandates: Let a be abs-if-needed(declval<typename InMat::value_type>()).

Then, decltype(init + a * a) is convertible to Scalar.

Returns: The square root of the sum of squares of init and the absolute values of the elements of A.

[Note 2:

For init equal to zero, this is the Frobenius norm of the matrix A.

— end note]

Remarks: If InMat::value_type and Scalar are all floating-point types or specializations of complex, and if Scalar has higher precision than InMat::value_type, then intermediate terms in the sum use Scalar's precision or greater.

🔗

template<in-matrix InMat>
  auto matrix_frob_norm(InMat A);
template<class ExecutionPolicy, in-matrix InMat>
  auto matrix_frob_norm(ExecutionPolicy&& exec, InMat A);

Effects: Let a be abs-if-needed(declval<typename InMat::value_type>()).

Let T be decltype(a * a).

Then,

(5.1)
the one-parameter overload is equivalent to: return matrix_frob_norm(A, T{}); and
(5.2)
the two-parameter overload is equivalent to: return matrix_frob_norm(std::forward<ExecutionPolicy>(exec), A, T{});

29.9.13.13 One norm of a matrix [linalg.algs.blas1.matonenorm]

[Note 1:

These functions exist in the BLAS standard[bib] but are not part of the reference implementation.

— end note]

🔗

template<in-matrix InMat, class Scalar>
  Scalar matrix_one_norm(InMat A, Scalar init);
template<class ExecutionPolicy, in-matrix InMat, class Scalar>
  Scalar matrix_one_norm(ExecutionPolicy&& exec, InMat A, Scalar init);

Mandates: decltype(abs-if-needed(declval<typename InMat::value_type>())) is convertible to Scalar.

Returns:

(3.1)
init if A.extent(1) is zero;
(3.2)
otherwise, the sum of init and the one norm of the matrix A.

[Note 2:

The one norm of the matrix A is the maximum over all columns of A, of the sum of the absolute values of the elements of the column.

— end note]

🔗

template<in-matrix InMat>
  auto matrix_one_norm(InMat A);
template<class ExecutionPolicy, in-matrix InMat>
  auto matrix_one_norm(ExecutionPolicy&& exec, InMat A);

Effects: Let T be decltype(abs-if-needed(declval<typename InMat::value_type>()).

Then,

(5.1)
the one-parameter overload is equivalent to: return matrix_one_norm(A, T{}); and
(5.2)
the two-parameter overload is equivalent to: return matrix_one_norm(std::forward<ExecutionPolicy>(exec), A, T{});

29.9.13.14 Infinity norm of a matrix [linalg.algs.blas1.matinfnorm]

[Note 1:

These functions exist in the BLAS standard[bib] but are not part of the reference implementation.

— end note]

🔗

template<in-matrix InMat, class Scalar>
  Scalar matrix_inf_norm(InMat A, Scalar init);
template<class ExecutionPolicy, in-matrix InMat, class Scalar>
  Scalar matrix_inf_norm(ExecutionPolicy&& exec, InMat A, Scalar init);

Mandates: decltype(abs-if-needed(declval<typename InMat::value_type>())) is convertible to Scalar.

Returns:

(3.1)
init if A.extent(0) is zero;
(3.2)
otherwise, the sum of init and the infinity norm of the matrix A.

[Note 2:

The infinity norm of the matrix A is the maximum over all rows of A, of the sum of the absolute values of the elements of the row.

— end note]

🔗

template<in-matrix InMat>
  auto matrix_inf_norm(InMat A);
template<class ExecutionPolicy, in-matrix InMat>
  auto matrix_inf_norm(ExecutionPolicy&& exec, InMat A);

Effects: Let T be decltype(abs-if-needed(declval<typename InMat::value_type>()).

Then,

(5.1)
the one-parameter overload is equivalent to: return matrix_inf_norm(A, T{}); and
(5.2)
the two-parameter overload is equivalent to: return matrix_inf_norm(std::forward<ExecutionPolicy>(exec), A, T{});

29.9.14 BLAS 2 algorithms [linalg.algs.blas2]

29.9.14.1 General matrix-vector product [linalg.algs.blas2.gemv]

[Note 1:

These functions correspond to the BLAS function xGEMV.

— end note]

The following elements apply to all functions in [linalg.algs.blas2.gemv].

Mandates:

(3.1)
possibly-multipliable<decltype(A), decltype(x), decltype(y)>() is true, and
(3.2)
possibly-addable<decltype(x), decltype(y), decltype(z)>() is true for those overloads that take a z parameter.

Preconditions:

(4.1)
multipliable(A,x,y) is true, and
(4.2)
addable(x,y,z) is true for those overloads that take a z parameter.

Complexity:

O (x.extent(0) \times A.extent(1))

🔗

template<in-matrix InMat, in-vector InVec, out-vector OutVec>
  void matrix_vector_product(InMat A, InVec x, OutVec y);
template<class ExecutionPolicy, in-matrix InMat, in-vector InVec, out-vector OutVec>
  void matrix_vector_product(ExecutionPolicy&& exec, InMat A, InVec x, OutVec y);

These functions perform an overwriting matrix-vector product.

Effects: Computes

y = A x

[Example 1: constexpr size_t num_rows = 5; constexpr size_t num_cols = 6; // y = 3.0 * A * x void scaled_matvec_1(mdspan<double, extents<size_t, num_rows, num_cols>> A, mdspan<double, extents<size_t, num_cols>> x, mdspan<double, extents<size_t, num_rows>> y) { matrix_vector_product(scaled(3.0, A), x, y); } // z = 7.0 times the transpose of A, times y void scaled_transposed_matvec(mdspan<double, extents<size_t, num_rows, num_cols>> A, mdspan<double, extents<size_t, num_rows>> y, mdspan<double, extents<size_t, num_cols>> z) { matrix_vector_product(scaled(7.0, transposed(A)), y, z); } — end example]

🔗

  template<in-matrix InMat, in-vector InVec1, in-vector InVec2, out-vector OutVec>
    void matrix_vector_product(InMat A, InVec1 x, InVec2 y, OutVec z);
  template<class ExecutionPolicy,
           in-matrix InMat, in-vector InVec1, in-vector InVec2, out-vector OutVec>
    void matrix_vector_product(ExecutionPolicy&& exec,
                               InMat A, InVec1 x, InVec2 y, OutVec z);

These functions performs an updating matrix-vector product.

Effects: Computes

z = y + A x

Remarks: z may alias y.

[Example 2: // y = 3.0 * A * x + 2.0 * y void scaled_matvec_2(mdspan<double, extents<size_t, num_rows, num_cols>> A, mdspan<double, extents<size_t, num_cols>> x, mdspan<double, extents<size_t, num_rows>> y) { matrix_vector_product(scaled(3.0, A), x, scaled(2.0, y), y); } — end example]

29.9.14.2 Symmetric matrix-vector product [linalg.algs.blas2.symv]

[Note 1:

These functions correspond to the BLAS functions xSYMV and xSPMV[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas2.symv].

Mandates:

(3.1)
If InMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
compatible-static-extents<decltype(A), decltype(A)>(0, 1) is true;
(3.3)
possibly-multipliable<decltype(A), decltype(x), decltype(y)>() is true; and
(3.4)
possibly-addable<decltype(x), decltype(y), decltype(z)>() is true for those overloads that take a z parameter.

Preconditions:

(4.1)
A.extent(0) equals A.extent(1),
(4.2)
multipliable(A,x,y) is true, and
(4.3)
addable(x,y,z) is true for those overloads that take a z parameter.

Complexity:

O (x.extent(0) \times A.extent(1))

🔗

template<in-matrix InMat, class Triangle, in-vector InVec, out-vector OutVec>
  void symmetric_matrix_vector_product(InMat A, Triangle t, InVec x, OutVec y);
template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, in-vector InVec, out-vector OutVec>
  void symmetric_matrix_vector_product(ExecutionPolicy&& exec,
                                       InMat A, Triangle t, InVec x, OutVec y);

These functions perform an overwriting symmetric matrix-vector product, taking into account the Triangle parameter that applies to the symmetric matrix A ([linalg.general]).

Effects: Computes

y = A x

🔗

template<in-matrix InMat, class Triangle, in-vector InVec1, in-vector InVec2, out-vector OutVec>
  void symmetric_matrix_vector_product(InMat A, Triangle t, InVec1 x, InVec2 y, OutVec z);
template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, in-vector InVec1, in-vector InVec2, out-vector OutVec>
  void symmetric_matrix_vector_product(ExecutionPolicy&& exec,
                                       InMat A, Triangle t, InVec1 x, InVec2 y, OutVec z);

These functions perform an updating symmetric matrix-vector product, taking into account the Triangle parameter that applies to the symmetric matrix A ([linalg.general]).

Effects: Computes

z = y + A x

Remarks: z may alias y.

29.9.14.3 Hermitian matrix-vector product [linalg.algs.blas2.hemv]

[Note 1:

These functions correspond to the BLAS functions xHEMV and xHPMV[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas2.hemv].

Mandates:

(3.1)
If InMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
compatible-static-extents<decltype(A), decltype(A)>(0, 1) is true;
(3.3)
possibly-multipliable<decltype(A), decltype(x), decltype(y)>() is true; and
(3.4)
possibly-addable<decltype(x), decltype(y), decltype(z)>() is true for those overloads that take a z parameter.

Preconditions:

(4.1)
A.extent(0) equals A.extent(1),
(4.2)
multipliable(A, x, y) is true, and
(4.3)
addable(x, y, z) is true for those overloads that take a z parameter.

Complexity:

O (x.extent(0) \times A.extent(1))

🔗

template<in-matrix InMat, class Triangle, in-vector InVec, out-vector OutVec>
  void hermitian_matrix_vector_product(InMat A, Triangle t, InVec x, OutVec y);
template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, in-vector InVec, out-vector OutVec>
  void hermitian_matrix_vector_product(ExecutionPolicy&& exec,
                                       InMat A, Triangle t, InVec x, OutVec y);

These functions perform an overwriting Hermitian matrix-vector product, taking into account the Triangle parameter that applies to the Hermitian matrix A ([linalg.general]).

Effects: Computes

y = A x

🔗

template<in-matrix InMat, class Triangle, in-vector InVec1, in-vector InVec2, out-vector OutVec>
  void hermitian_matrix_vector_product(InMat A, Triangle t, InVec1 x, InVec2 y, OutVec z);
template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, in-vector InVec1, in-vector InVec2, out-vector OutVec>
  void hermitian_matrix_vector_product(ExecutionPolicy&& exec,
                                       InMat A, Triangle t, InVec1 x, InVec2 y, OutVec z);

These functions perform an updating Hermitian matrix-vector product, taking into account the Triangle parameter that applies to the Hermitian matrix A ([linalg.general]).

Effects: Computes

z = y + A x

Remarks: z may alias y.

29.9.14.4 Triangular matrix-vector product [linalg.algs.blas2.trmv]

[Note 1:

These functions correspond to the BLAS functions xTRMV and xTPMV[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas2.trmv].

Mandates:

(3.1)
If InMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
compatible-static-extents<decltype(A), decltype(A)>(0, 1) is true;
(3.3)
compatible-static-extents<decltype(A), decltype(y)>(0, 0) is true;
(3.4)
compatible-static-extents<decltype(A), decltype(x)>(0, 0) is true for those overloads that take an x parameter; and
(3.5)
compatible-static-extents<decltype(A), decltype(z)>(0, 0) is true for those overloads that take a z parameter.

Preconditions:

(4.1)
A.extent(0) equals A.extent(1),
(4.2)
A.extent(0) equals y.extent(0),
(4.3)
A.extent(0) equals x.extent(0) for those overloads that take an x parameter, and
(4.4)
A.extent(0) equals z.extent(0) for those overloads that take a z parameter.

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec,
         out-vector OutVec>
  void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d, InVec x, OutVec y);
template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, class DiagonalStorage, in-vector InVec,
         out-vector OutVec>
  void triangular_matrix_vector_product(ExecutionPolicy&& exec,
                                        InMat A, Triangle t, DiagonalStorage d, InVec x, OutVec y);

These functions perform an overwriting triangular matrix-vector product, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

Effects: Computes

y = A x

Complexity:

O (x.extent(0) \times A.extent(1))

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec>
  void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d, InOutVec y);
template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec>
  void triangular_matrix_vector_product(ExecutionPolicy&& exec,
                                        InMat A, Triangle t, DiagonalStorage d, InOutVec y);

These functions perform an in-place triangular matrix-vector product, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

[Note 2:

Performing this operation in place hinders parallelization.

However, other ExecutionPolicy specific optimizations, such as vectorization, are still possible.

— end note]

Effects: Computes a vector

y^{'}

such that

y^{'} = A y

, and assigns each element of

y^{'}

to the corresponding element of y.

Complexity:

O (y.extent(0) \times A.extent(1))

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage,
         in-vector InVec1, in-vector InVec2, out-vector OutVec>
  void triangular_matrix_vector_product(InMat A, Triangle t, DiagonalStorage d,
                                        InVec1 x, InVec2 y, OutVec z);
template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage,
         in-vector InVec1, in-vector InVec2, out-vector OutVec>
  void triangular_matrix_vector_product(ExecutionPolicy&& exec,
                                        InMat A, Triangle t, DiagonalStorage d,
                                        InVec1 x, InVec2 y, OutVec z);

These functions perform an updating triangular matrix-vector product, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

Effects: Computes

z = y + A x

Complexity:

O (x.extent(0) \times A.extent(1))

Remarks: z may alias y.

29.9.14.5 Solve a triangular linear system [linalg.algs.blas2.trsv]

[Note 1:

These functions correspond to the BLAS functions xTRSV and xTPSV[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas2.trsv].

Mandates:

(3.1)
If InMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
compatible-static-extents<decltype(A), decltype(A)>(0, 1) is true;
(3.3)
compatible-static-extents<decltype(A), decltype(b)>(0, 0) is true; and
(3.4)
compatible-static-extents<decltype(A), decltype(x)>(0, 0) is true for those overloads that take an x parameter.

Preconditions:

(4.1)
A.extent(0) equals A.extent(1),
(4.2)
A.extent(0) equals b.extent(0), and
(4.3)
A.extent(0) equals x.extent(0) for those overloads that take an x parameter.

🔗

  template<in-matrix InMat, class Triangle, class DiagonalStorage,
           in-vector InVec, out-vector OutVec, class BinaryDivideOp>
    void triangular_matrix_vector_solve(InMat A, Triangle t, DiagonalStorage d,
                                        InVec b, OutVec x, BinaryDivideOp divide);
  template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage,
           in-vector InVec, out-vector OutVec, class BinaryDivideOp>
    void triangular_matrix_vector_solve(ExecutionPolicy&& exec,
                                        InMat A, Triangle t, DiagonalStorage d,
                                        InVec b, OutVec x, BinaryDivideOp divide);

These functions perform a triangular solve, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

Effects: Computes a vector

x^{'}

such that

b = A x^{'}

, and assigns each element of

x^{'}

to the corresponding element of x.

If no such

x^{'}

exists, then the elements of x are valid but unspecified.

Complexity:

O (A.extent(1) \times b.extent(0))

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage,
         in-vector InVec, out-vector OutVec>
  void triangular_matrix_vector_solve(InMat A, Triangle t, DiagonalStorage d, InVec b, OutVec x);

Effects: Equivalent to: triangular_matrix_vector_solve(A, t, d, b, x, divides<void>{});

🔗

template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage,
         in-vector InVec, out-vector OutVec>
  void triangular_matrix_vector_solve(ExecutionPolicy&& exec,
                                      InMat A, Triangle t, DiagonalStorage d, InVec b, OutVec x);

Effects: Equivalent to: triangular_matrix_vector_solve(std::forward<ExecutionPolicy>(exec), A, t, d, b, x, divides<void>{});

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage,
         inout-vector InOutVec, class BinaryDivideOp>
  void triangular_matrix_vector_solve(InMat A, Triangle t, DiagonalStorage d,
                                      InOutVec b, BinaryDivideOp divide);
template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage,
         inout-vector InOutVec, class BinaryDivideOp>
  void triangular_matrix_vector_solve(ExecutionPolicy&& exec,
                                      InMat A, Triangle t, DiagonalStorage d,
                                      InOutVec b, BinaryDivideOp divide);

These functions perform an in-place triangular solve, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

[Note 2:

Performing triangular solve in place hinders parallelization.

However, other ExecutionPolicy specific optimizations, such as vectorization, are still possible.

— end note]

Effects: Computes a vector

x^{'}

such that

b = A x^{'}

, and assigns each element of

x^{'}

to the corresponding element of b.

If no such

x^{'}

exists, then the elements of b are valid but unspecified.

Complexity:

O (A.extent(1) \times b.extent(0))

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec>
  void triangular_matrix_vector_solve(InMat A, Triangle t, DiagonalStorage d, InOutVec b);

Effects: Equivalent to: triangular_matrix_vector_solve(A, t, d, b, divides<void>{});

🔗

template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, class DiagonalStorage, inout-vector InOutVec>
  void triangular_matrix_vector_solve(ExecutionPolicy&& exec,
                                      InMat A, Triangle t, DiagonalStorage d, InOutVec b);

Effects: Equivalent to: triangular_matrix_vector_solve(std::forward<ExecutionPolicy>(exec), A, t, d, b, divides<void>{});

29.9.14.6 Rank-1 (outer product) update of a matrix [linalg.algs.blas2.rank1]

🔗

template<in-vector InVec1, in-vector InVec2, inout-matrix InOutMat>
  void matrix_rank_1_update(InVec1 x, InVec2 y, InOutMat A);
template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, inout-matrix InOutMat>
  void matrix_rank_1_update(ExecutionPolicy&& exec, InVec1 x, InVec2 y, InOutMat A);

These functions perform a nonsymmetric nonconjugated rank-1 update.

[Note 1:

These functions correspond to the BLAS functions xGER (for real element types) and xGERU (for complex element types)[bib].

— end note]

Mandates: possibly-multipliable<InOutMat, InVec2, InVec1>() is true.

Preconditions: multipliable(A, y, x) is true.

Effects: Computes a matrix

A^{'}

such that

A^{'} = A + x y^{T}

, and assigns each element of

A^{'}

to the corresponding element of A.

Complexity:

O (x.extent(0) \times y.extent(0))

🔗

template<in-vector InVec1, in-vector InVec2, inout-matrix InOutMat>
  void matrix_rank_1_update_c(InVec1 x, InVec2 y, InOutMat A);
template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2, inout-matrix InOutMat>
  void matrix_rank_1_update_c(ExecutionPolicy&& exec, InVec1 x, InVec2 y, InOutMat A);

These functions perform a nonsymmetric conjugated rank-1 update.

[Note 2:

These functions correspond to the BLAS functions xGER (for real element types) and xGERC (for complex element types)[bib].

— end note]

Effects:

(7.1)
For the overloads without an ExecutionPolicy argument, equivalent to: matrix_rank_1_update(x, conjugated(y), A);
(7.2)
otherwise, equivalent to: matrix_rank_1_update(std::forward<ExecutionPolicy>(exec), x, conjugated(y), A);

29.9.14.7 Symmetric or Hermitian Rank-1 (outer product) update of a matrix [linalg.algs.blas2.symherrank1]

[Note 1:

These functions correspond to the BLAS functions xSYR, xSPR, xHER, and xHPR[bib].

They have overloads taking a scaling factor alpha, because it would be impossible to express the update

A = A - x x^{T}

otherwise.

— end note]

The following elements apply to all functions in [linalg.algs.blas2.symherrank1].

Mandates:

(3.1)
If InOutMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
compatible-static-extents<decltype(A), decltype(A)>(0, 1) is true; and
(3.3)
compatible-static-extents<decltype(A), decltype(x)>(0, 0) is true.

Preconditions:

(4.1)
A.extent(0) equals A.extent(1), and
(4.2)
A.extent(0) equals x.extent(0).

Complexity:

O (x.extent(0) \times x.extent(0))

🔗

template<class Scalar, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_1_update(Scalar alpha, InVec x, InOutMat A, Triangle t);
template<class ExecutionPolicy,
         class Scalar, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_1_update(ExecutionPolicy&& exec,
                                      Scalar alpha, InVec x, InOutMat A, Triangle t);

These functions perform a symmetric rank-1 update of the symmetric matrix A, taking into account the Triangle parameter that applies to A ([linalg.general]).

Effects: Computes a matrix

A^{'}

such that

A^{'} = A + α x x^{T}

, where the scalar α is alpha, and assigns each element of

A^{'}

to the corresponding element of A.

🔗

template<in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_1_update(InVec x, InOutMat A, Triangle t);
template<class ExecutionPolicy,
         in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_1_update(ExecutionPolicy&& exec, InVec x, InOutMat A, Triangle t);

These functions perform a symmetric rank-1 update of the symmetric matrix A, taking into account the Triangle parameter that applies to A ([linalg.general]).

Effects: Computes a matrix

A^{'}

such that

A^{'} = A + x x^{T}

and assigns each element of

A^{'}

to the corresponding element of A.

🔗

template<class Scalar, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_1_update(Scalar alpha, InVec x, InOutMat A, Triangle t);
template<class ExecutionPolicy,
         class Scalar, in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_1_update(ExecutionPolicy&& exec,
                                      Scalar alpha, InVec x, InOutMat A, Triangle t);

These functions perform a Hermitian rank-1 update of the Hermitian matrix A, taking into account the Triangle parameter that applies to A ([linalg.general]).

Effects: Computes

A^{'}

such that

A^{'} = A + α x x^{H}

, where the scalar α is alpha, and assigns each element of

A^{'}

to the corresponding element of A.

🔗

template<in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_1_update(InVec x, InOutMat A, Triangle t);
template<class ExecutionPolicy,
         in-vector InVec, possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_1_update(ExecutionPolicy&& exec, InVec x, InOutMat A, Triangle t);

These functions perform a Hermitian rank-1 update of the Hermitian matrix A, taking into account the Triangle parameter that applies to A ([linalg.general]).

Effects: Computes a matrix

A^{'}

such that

A^{'} = A + x x^{H}

and assigns each element of

A^{'}

to the corresponding element of A.

29.9.14.8 Symmetric and Hermitian rank-2 matrix updates [linalg.algs.blas2.rank2]

[Note 1:

These functions correspond to the BLAS functions xSYR2,xSPR2, xHER2 and xHPR2[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas2.rank2].

Mandates:

(3.1)
If InOutMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
compatible-static-extents<decltype(A), decltype(A)>(0, 1) is true; and
(3.3)
possibly-multipliable<decltype(A), decltype(x), decltype(y)>() is true.

Preconditions:

(4.1)
A.extent(0) equals A.extent(1), and
(4.2)
multipliable(A, x, y) is true.

Complexity:

O (x.extent(0) \times y.extent(0))

🔗

template<in-vector InVec1, in-vector InVec2,
         possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_2_update(InVec1 x, InVec2 y, InOutMat A, Triangle t);
template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2,
         possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_2_update(ExecutionPolicy&& exec,
                                      InVec1 x, InVec2 y, InOutMat A, Triangle t);

These functions perform a symmetric rank-2 update of the symmetric matrix A, taking into account the Triangle parameter that applies to A ([linalg.general]).

Effects: Computes

A^{'}

such that

A^{'} = A + x y^{T} + y x^{T}

and assigns each element of

A^{'}

to the corresponding element of A.

🔗

template<in-vector InVec1, in-vector InVec2,
         possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_2_update(InVec1 x, InVec2 y, InOutMat A, Triangle t);
template<class ExecutionPolicy, in-vector InVec1, in-vector InVec2,
         possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_2_update(ExecutionPolicy&& exec,
                                      InVec1 x, InVec2 y, InOutMat A, Triangle t);

These functions perform a Hermitian rank-2 update of the Hermitian matrix A, taking into account the Triangle parameter that applies to A ([linalg.general]).

Effects: Computes

A^{'}

such that

A^{'} = A + x y^{H} + y x^{H}

and assigns each element of

A^{'}

to the corresponding element of A.

29.9.15 BLAS 3 algorithms [linalg.algs.blas3]

29.9.15.1 General matrix-matrix product [linalg.algs.blas3.gemm]

[Note 1:

These functions correspond to the BLAS function xGEMM[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas3.gemm] in addition to function-specific elements.

Mandates: possibly-multipliable<decltype(A), decltype(B), decltype(C)>() is true.

Preconditions: multipliable(A, B, C) is true.

Complexity:

O (A.extent(0) \times A.extent(1) \times B.extent(1))

🔗

  template<in-matrix InMat1, in-matrix InMat2, out-matrix OutMat>
    void matrix_product(InMat1 A, InMat2 B, OutMat C);
  template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2, out-matrix OutMat>
    void matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, OutMat C);

Effects: Computes

C = A B

🔗

template<in-matrix InMat1, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat>
  void matrix_product(InMat1 A, InMat2 B, InMat3 E, OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, in-matrix InMat2, in-matrix InMat3, out-matrix OutMat>
  void matrix_product(ExecutionPolicy&& exec, InMat1 A, InMat2 B, InMat3 E, OutMat C);

Mandates: possibly-addable<InMat3, InMat3, OutMat>() is true.

Preconditions: addable(E, E, C) is true.

Effects: Computes

C = E + A B

Remarks: C may alias E.

29.9.15.2 Symmetric, Hermitian, and triangular matrix-matrix product [linalg.algs.blas3.xxmm]

[Note 1:

These functions correspond to the BLAS functions xSYMM, xHEMM, and xTRMM[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas3.xxmm] in addition to function-specific elements.

Mandates:

(3.1)
possibly-multipliable<decltype(A), decltype(B), decltype(C)>() is true, and
(3.2)
possibly-addable<decltype(E), decltype(E), decltype(C)>() is true for those overloads that take an E parameter.

Preconditions:

(4.1)
multipliable(A, B, C) is true, and
(4.2)
addable(E, E, C) is true for those overloads that take an E parameter.

Complexity:

O (A.extent(0) \times A.extent(1) \times B.extent(1))

🔗

template<in-matrix InMat1, class Triangle, in-matrix InMat2, out-matrix OutMat>
  void symmetric_matrix_product(InMat1 A, Triangle t, InMat2 B, OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, class Triangle, in-matrix InMat2, out-matrix OutMat>
  void symmetric_matrix_product(ExecutionPolicy&& exec, InMat1 A, Triangle t, InMat2 B, OutMat C);

template<in-matrix InMat1, class Triangle, in-matrix InMat2, out-matrix OutMat>
  void hermitian_matrix_product(InMat1 A, Triangle t, InMat2 B, OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, class Triangle, in-matrix InMat2, out-matrix OutMat>
  void hermitian_matrix_product(ExecutionPolicy&& exec, InMat1 A, Triangle t, InMat2 B, OutMat C);

template<in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat>
  void triangular_matrix_product(InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat C);
template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat>
  void triangular_matrix_product(ExecutionPolicy&& exec,
                                 InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, OutMat C);

These functions perform a matrix-matrix multiply, taking into account the Triangle and DiagonalStorage (if applicable) parameters that apply to the symmetric, Hermitian, or triangular (respectively) matrix A ([linalg.general]).

Mandates:

(7.1)
If InMat1 has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument; and
(7.2)
compatible-static-extents<InMat1, InMat1>(0, 1) is true.

Preconditions: A.extent(0) == A.extent(1) is true.

Effects: Computes

C = A B

🔗

  template<in-matrix InMat1, in-matrix InMat2, class Triangle, out-matrix OutMat>
    void symmetric_matrix_product(InMat1 A, InMat2 B, Triangle t, OutMat C);
  template<class ExecutionPolicy,
           in-matrix InMat1, in-matrix InMat2, class Triangle, out-matrix OutMat>
    void symmetric_matrix_product(ExecutionPolicy&& exec,
                                  InMat1 A, InMat2 B, Triangle t, OutMat C);

  template<in-matrix InMat1, in-matrix InMat2, class Triangle, out-matrix OutMat>
    void hermitian_matrix_product(InMat1 A, InMat2 B, Triangle t, OutMat C);
  template<class ExecutionPolicy,
           in-matrix InMat1, in-matrix InMat2, class Triangle, out-matrix OutMat>
    void hermitian_matrix_product(ExecutionPolicy&& exec,
                                  InMat1 A, InMat2 B, Triangle t, OutMat C);

  template<in-matrix InMat1, in-matrix InMat2, class Triangle, class DiagonalStorage,
           out-matrix OutMat>
    void triangular_matrix_product(InMat1 A, InMat2 B, Triangle t, DiagonalStorage d, OutMat C);
  template<class ExecutionPolicy,
           in-matrix InMat1, in-matrix InMat2, class Triangle, class DiagonalStorage,
           out-matrix OutMat>
    void triangular_matrix_product(ExecutionPolicy&& exec,
                                   InMat1 A, InMat2 B, Triangle t, DiagonalStorage d, OutMat C);

Mandates:

(11.1)
If InMat2 has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument; and
(11.2)
compatible-static-extents<InMat2, InMat2>(0, 1) is true.

Preconditions: B.extent(0) == B.extent(1) is true.

Effects: Computes

C = A B

🔗

template<in-matrix InMat1, class Triangle, in-matrix InMat2, in-matrix InMat3,
         out-matrix OutMat>
  void symmetric_matrix_product(InMat1 A, Triangle t, InMat2 B, InMat3 E, OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, class Triangle, in-matrix InMat2, in-matrix InMat3,
         out-matrix OutMat>
  void symmetric_matrix_product(ExecutionPolicy&& exec,
                                InMat1 A, Triangle t, InMat2 B, InMat3 E, OutMat C);

template<in-matrix InMat1, class Triangle, in-matrix InMat2, in-matrix InMat3,
         out-matrix OutMat>
  void hermitian_matrix_product(InMat1 A, Triangle t, InMat2 B, InMat3 E, OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, class Triangle, in-matrix InMat2, in-matrix InMat3,
         out-matrix OutMat>
  void hermitian_matrix_product(ExecutionPolicy&& exec,
                                InMat1 A, Triangle t, InMat2 B, InMat3 E, OutMat C);

template<in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, in-matrix InMat3, out-matrix OutMat>
  void triangular_matrix_product(InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, InMat3 E,
                                 OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, in-matrix InMat3, out-matrix OutMat>
  void triangular_matrix_product(ExecutionPolicy&& exec,
                                 InMat1 A, Triangle t, DiagonalStorage d, InMat2 B, InMat3 E,
                                 OutMat C);

These functions perform a potentially overwriting matrix-matrix multiply-add, taking into account the Triangle and DiagonalStorage (if applicable) parameters that apply to the symmetric, Hermitian, or triangular (respectively) matrix A ([linalg.general]).

Mandates:

(15.1)
If InMat1 has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument; and
(15.2)
compatible-static-extents<InMat1, InMat1>(0, 1) is true.

Preconditions: A.extent(0) == A.extent(1) is true.

Effects: Computes

C = E + A B

Remarks: C may alias E.

🔗

template<in-matrix InMat1, in-matrix InMat2, class Triangle, in-matrix InMat3,
         out-matrix OutMat>
  void symmetric_matrix_product(InMat1 A, InMat2 B, Triangle t, InMat3 E, OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, in-matrix InMat2, class Triangle, in-matrix InMat3,
         out-matrix OutMat>
  void symmetric_matrix_product(ExecutionPolicy&& exec,
                                InMat1 A, InMat2 B, Triangle t, InMat3 E, OutMat C);

template<in-matrix InMat1, in-matrix InMat2, class Triangle, in-matrix InMat3,
         out-matrix OutMat>
  void hermitian_matrix_product(InMat1 A, InMat2 B, Triangle t, InMat3 E, OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, in-matrix InMat2, class Triangle, in-matrix InMat3,
         out-matrix OutMat>
  void hermitian_matrix_product(ExecutionPolicy&& exec,
                                InMat1 A, InMat2 B, Triangle t, InMat3 E, OutMat C);

template<in-matrix InMat1, in-matrix InMat2, class Triangle, class DiagonalStorage,
         in-matrix InMat3, out-matrix OutMat>
  void triangular_matrix_product(InMat1 A, InMat2 B, Triangle t, DiagonalStorage d, InMat3 E,
                                 OutMat C);
template<class ExecutionPolicy,
         in-matrix InMat1, in-matrix InMat2, class Triangle, class DiagonalStorage,
         in-matrix InMat3, out-matrix OutMat>
  void triangular_matrix_product(ExecutionPolicy&& exec,
                                 InMat1 A, InMat2 B, Triangle t, DiagonalStorage d, InMat3 E,
                                 OutMat C);

Mandates:

(20.1)
If InMat2 has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument; and
(20.2)
compatible-static-extents<InMat2, InMat2>(0, 1) is true.

Preconditions: B.extent(0) == B.extent(1) is true.

Effects: Computes

C = E + A B

Remarks: C may alias E.

29.9.15.3 In-place triangular matrix-matrix product [linalg.algs.blas3.trmm]

These functions perform an in-place matrix-matrix multiply, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

[Note 1:

These functions correspond to the BLAS function xTRMM[bib].

— end note]

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat>
  void triangular_matrix_left_product(InMat A, Triangle t, DiagonalStorage d, InOutMat C);
template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat>
  void triangular_matrix_left_product(ExecutionPolicy&& exec,
                                      InMat A, Triangle t, DiagonalStorage d, InOutMat C);

Mandates:

(2.1)
If InMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(2.2)
possibly-multipliable<InMat, InOutMat, InOutMat>() is true; and
(2.3)
compatible-static-extents<InMat, InMat>(0, 1) is true.

Preconditions:

(3.1)
multipliable(A, C, C) is true, and
(3.2)
A.extent(0) == A.extent(1) is true.

Effects: Computes a matrix

C^{'}

such that

C^{'} = A C

and assigns each element of

C^{'}

to the corresponding element of C.

Complexity:

O (A.extent(0) \times A.extent(1) \times C.extent(0))

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat>
  void triangular_matrix_right_product(InMat A, Triangle t, DiagonalStorage d, InOutMat C);
template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat>
  void triangular_matrix_right_product(ExecutionPolicy&& exec,
                                       InMat A, Triangle t, DiagonalStorage d, InOutMat C);

Mandates:

(6.1)
If InMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(6.2)
possibly-multipliable<InOutMat, InMat, InOutMat>() is true; and
(6.3)
compatible-static-extents<InMat, InMat>(0, 1) is true.

Preconditions:

(7.1)
multipliable(C, A, C) is true, and
(7.2)
A.extent(0) == A.extent(1) is true.

Effects: Computes a matrix

C^{'}

such that

C^{'} = C A

and assigns each element of

C^{'}

to the corresponding element of C.

Complexity:

O (A.extent(0) \times A.extent(1) \times C.extent(0))

29.9.15.4 Rank-k update of a symmetric or Hermitian matrix [linalg.algs.blas3.rankk]

[Note 1:

These functions correspond to the BLAS functions xSYRK and xHERK[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas3.rankk].

Mandates:

(3.1)
If InOutMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
compatible-static-extents<decltype(A), decltype(A)>(0, 1) is true;
(3.3)
compatible-static-extents<decltype(C), decltype(C)>(0, 1) is true; and
(3.4)
compatible-static-extents<decltype(A), decltype(C)>(0, 0) is true.

Preconditions:

(4.1)
A.extent(0) equals A.extent(1),
(4.2)
C.extent(0) equals C.extent(1), and
(4.3)
A.extent(0) equals C.extent(0).

Complexity:

O (A.extent(0) \times A.extent(1) \times C.extent(0))

🔗

  template<class Scalar, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle>
    void symmetric_matrix_rank_k_update(Scalar alpha, InMat A, InOutMat C, Triangle t);
  template<class ExecutionPolicy, class Scalar,
           in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle>
    void symmetric_matrix_rank_k_update(ExecutionPolicy&& exec,
                                        Scalar alpha, InMat A, InOutMat C, Triangle t);

Effects: Computes a matrix

C^{'}

such that

C^{'} = C + α A A^{T}

, where the scalar α is alpha, and assigns each element of

C^{'}

to the corresponding element of C.

🔗

template<in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_k_update(InMat A, InOutMat C, Triangle t);
template<class ExecutionPolicy,
         in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_k_update(ExecutionPolicy&& exec,
                                      InMat A, InOutMat C, Triangle t);

Effects: Computes a matrix

C^{'}

such that

C^{'} = C + A A^{T}

, and assigns each element of

C^{'}

to the corresponding element of C.

🔗

template<class Scalar, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_k_update(Scalar alpha, InMat A, InOutMat C, Triangle t);
template<class ExecutionPolicy,
         class Scalar, in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_k_update(ExecutionPolicy&& exec,
                                      Scalar alpha, InMat A, InOutMat C, Triangle t);

Effects: Computes a matrix

C^{'}

such that

C^{'} = C + α A A^{H}

, where the scalar α is alpha, and assigns each element of

C^{'}

to the corresponding element of C.

🔗

template<in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_k_update(InMat A, InOutMat C, Triangle t);
template<class ExecutionPolicy,
         in-matrix InMat, possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_k_update(ExecutionPolicy&& exec,
                                      InMat A, InOutMat C, Triangle t);

Effects: Computes a matrix

C^{'}

such that

C^{'} = C + A A^{H}

, and assigns each element of

C^{'}

to the corresponding element of C.

29.9.15.5 Rank-2k update of a symmetric or Hermitian matrix [linalg.algs.blas3.rank2k]

[Note 1:

These functions correspond to the BLAS functions xSYR2K and xHER2K[bib].

— end note]

The following elements apply to all functions in [linalg.algs.blas3.rank2k].

Mandates:

(3.1)
If InOutMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
possibly-addable<decltype(A), decltype(B), decltype(C)>() is true; and
(3.3)
compatible-static-extents<decltype(A), decltype(A)>(0, 1) is true.

Preconditions:

(4.1)
addable(A, B, C) is true, and
(4.2)
A.extent(0) equals A.extent(1).

Complexity:

O (A.extent(0) \times A.extent(1) \times C.extent(0))

🔗

template<in-matrix InMat1, in-matrix InMat2,
         possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_2k_update(InMat1 A, InMat2 B, InOutMat C, Triangle t);
template<class ExecutionPolicy, in-matrix InMat1, in-matrix InMat2,
         possibly-packed-inout-matrix InOutMat, class Triangle>
  void symmetric_matrix_rank_2k_update(ExecutionPolicy&& exec,
                                       InMat1 A, InMat2 B, InOutMat C, Triangle t);

Effects: Computes a matrix

C^{'}

such that

C^{'} = C + A B^{T} + B A^{T}

, and assigns each element of

C^{'}

to the corresponding element of C.

🔗

template<in-matrix InMat1, in-matrix InMat2,
         possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_2k_update(InMat1 A, InMat2 B, InOutMat C, Triangle t);
template<class ExecutionPolicy,
         in-matrix InMat1, in-matrix InMat2,
         possibly-packed-inout-matrix InOutMat, class Triangle>
  void hermitian_matrix_rank_2k_update(ExecutionPolicy&& exec,
                                       InMat1 A, InMat2 B, InOutMat C, Triangle t);

Effects: Computes a matrix

C^{'}

such that

C^{'} = C + A B^{H} + B A^{H}

, and assigns each element of

C^{'}

to the corresponding element of C.

29.9.15.6 Solve multiple triangular linear systems [linalg.algs.blas3.trsm]

[Note 1:

These functions correspond to the BLAS function xTRSM[bib].

— end note]

🔗

template<in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat, class BinaryDivideOp>
  void triangular_matrix_matrix_left_solve(InMat1 A, Triangle t, DiagonalStorage d,
                                           InMat2 B, OutMat X, BinaryDivideOp divide);
template<class ExecutionPolicy,
         in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat, class BinaryDivideOp>
  void triangular_matrix_matrix_left_solve(ExecutionPolicy&& exec,
                                           InMat1 A, Triangle t, DiagonalStorage d,
                                           InMat2 B, OutMat X, BinaryDivideOp divide);

These functions perform multiple matrix solves, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

Mandates:

(3.1)
If InMat1 has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
possibly-multipliable<InMat1, OutMat, InMat2>() is true; and
(3.3)
compatible-static-extents<InMat1, InMat1>(0, 1) is true.

Preconditions:

(4.1)
multipliable(A, X, B) is true, and
(4.2)
A.extent(0) == A.extent(1) is true.

Effects: Computes

X^{'}

such that

A X^{'} = B

, and assigns each element of

X^{'}

to the corresponding element of X.

If no such

X^{'}

exists, then the elements of X are valid but unspecified.

Complexity:

O (A.extent(0) \times X.extent(1) \times X.extent(1))

[Note 2:

Since the triangular matrix is on the left, the desired divide implementation in the case of noncommutative multiplication is mathematically equivalent to

y^{- 1} x

, where x is the first argument and y is the second argument, and

y^{- 1}

denotes the multiplicative inverse of y.

— end note]

🔗

template<in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat>
  void triangular_matrix_matrix_left_solve(InMat1 A, Triangle t, DiagonalStorage d,
                                           InMat2 B, OutMat X);

Effects: Equivalent to: triangular_matrix_matrix_left_solve(A, t, d, B, X, divides<void>{});

🔗

template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat>
  void triangular_matrix_matrix_left_solve(ExecutionPolicy&& exec,
                                           InMat1 A, Triangle t, DiagonalStorage d,
                                           InMat2 B, OutMat X);

Effects: Equivalent to: triangular_matrix_matrix_left_solve(std::forward<ExecutionPolicy>(exec), A, t, d, B, X, divides<void>{});

🔗

template<in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat, class BinaryDivideOp>
  void triangular_matrix_matrix_right_solve(InMat1 A, Triangle t, DiagonalStorage d,
                                            InMat2 B, OutMat X, BinaryDivideOp divide);
template<class ExecutionPolicy,
         in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat, class BinaryDivideOp>
  void triangular_matrix_matrix_right_solve(ExecutionPolicy&& exec,
                                            InMat1 A, Triangle t, DiagonalStorage d,
                                            InMat2 B, OutMat X, BinaryDivideOp divide);

These functions perform multiple matrix solves, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

Mandates:

(11.1)
If InMat1 has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(11.2)
possibly-multipliable<OutMat, InMat1, InMat2>() is true; and
(11.3)
compatible-static-extents<InMat1, InMat1>(0,1) is true.

Preconditions:

(12.1)
multipliable(X, A, B) is true, and
(12.2)
A.extent(0) == A.extent(1) is true.

Effects: Computes

X^{'}

such that

X^{'} A = B

, and assigns each element of

X^{'}

to the corresponding element of X.

If no such

X^{'}

exists, then the elements of X are valid but unspecified.

Complexity: O( B.extent(0)

\cdot

B.extent(1)

\cdot

A.extent(1) )

[Note 3:

Since the triangular matrix is on the right, the desired divide implementation in the case of noncommutative multiplication is mathematically equivalent to

x y^{- 1}

, where x is the first argument and y is the second argument, and

y^{- 1}

denotes the multiplicative inverse of y.

— end note]

🔗

template<in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat>
  void triangular_matrix_matrix_right_solve(InMat1 A, Triangle t, DiagonalStorage d,
                                            InMat2 B, OutMat X);

Effects: Equivalent to: triangular_matrix_matrix_right_solve(A, t, d, B, X, divides<void>{});

🔗

template<class ExecutionPolicy, in-matrix InMat1, class Triangle, class DiagonalStorage,
         in-matrix InMat2, out-matrix OutMat>
  void triangular_matrix_matrix_right_solve(ExecutionPolicy&& exec,
                                            InMat1 A, Triangle t, DiagonalStorage d,
                                            InMat2 B, OutMat X);

Effects: Equivalent to: triangular_matrix_matrix_right_solve(std::forward<ExecutionPolicy>(exec), A, t, d, B, X, divides<void>{});

29.9.15.7 Solve multiple triangular linear systems in-place [linalg.algs.blas3.inplacetrsm]

[Note 1:

These functions correspond to the BLAS function xTRSM[bib].

— end note]

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage,
         inout-matrix InOutMat, class BinaryDivideOp>
  void triangular_matrix_matrix_left_solve(InMat A, Triangle t, DiagonalStorage d,
                                           InOutMat B, BinaryDivideOp divide);
template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage,
         inout-matrix InOutMat, class BinaryDivideOp>
  void triangular_matrix_matrix_left_solve(ExecutionPolicy&& exec,
                                           InMat A, Triangle t, DiagonalStorage d,
                                           InOutMat B, BinaryDivideOp divide);

These functions perform multiple in-place matrix solves, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

[Note 2:

This algorithm makes it possible to compute factorizations like Cholesky and LU in place.

Performing triangular solve in place hinders parallelization.

However, other ExecutionPolicy specific optimizations, such as vectorization, are still possible.

— end note]

Mandates:

(3.1)
If InMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(3.2)
possibly-multipliable<InMat, InOutMat, InOutMat>() is true; and
(3.3)
compatible-static-extents<InMat, InMat>(0, 1) is true.

Preconditions:

(4.1)
multipliable(A, B, B) is true, and
(4.2)
A.extent(0) == A.extent(1) is true.

Effects: Computes

X^{'}

such that

A X^{'} = B

, and assigns each element of

X^{'}

to the corresponding element of B.

If so such

X^{'}

exists, then the elements of B are valid but unspecified.

Complexity:

O (A.extent(0) \times A.extent(1) \times B.extent(1))

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat>
  void triangular_matrix_matrix_left_solve(InMat A, Triangle t, DiagonalStorage d,
                                           InOutMat B);

Effects: Equivalent to: triangular_matrix_matrix_left_solve(A, t, d, B, divides<void>{});

🔗

  template<class ExecutionPolicy,
           in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat>
    void triangular_matrix_matrix_left_solve(ExecutionPolicy&& exec,
                                             InMat A, Triangle t, DiagonalStorage d,
                                             InOutMat B);

Effects: Equivalent to: triangular_matrix_matrix_left_solve(std::forward<ExecutionPolicy>(exec), A, t, d, B, divides<void>{});

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage,
         inout-matrix InOutMat, class BinaryDivideOp>
  void triangular_matrix_matrix_right_solve(InMat A, Triangle t, DiagonalStorage d,
                                            InOutMat B, BinaryDivideOp divide);
template<class ExecutionPolicy, in-matrix InMat, class Triangle, class DiagonalStorage,
         inout-matrix InOutMat, class BinaryDivideOp>
  void triangular_matrix_matrix_right_solve(ExecutionPolicy&& exec,
                                            InMat A, Triangle t, DiagonalStorage d,
                                            InOutMat B, BinaryDivideOp divide);

These functions perform multiple in-place matrix solves, taking into account the Triangle and DiagonalStorage parameters that apply to the triangular matrix A ([linalg.general]).

[Note 3:

This algorithm makes it possible to compute factorizations like Cholesky and LU in place.

Performing triangular solve in place hinders parallelization.

However, other ExecutionPolicy specific optimizations, such as vectorization, are still possible.

— end note]

Mandates:

(10.1)
If InMat has layout_blas_packed layout, then the layout's Triangle template argument has the same type as the function's Triangle template argument;
(10.2)
possibly-multipliable<InOutMat, InMat, InOutMat>() is true; and
(10.3)
compatible-static-extents<InMat, InMat>(0, 1) is true.

Preconditions:

(11.1)
multipliable(B, A, B) is true, and
(11.2)
A.extent(0) == A.extent(1) is true.

Effects: Computes

X^{'}

such that

X^{'} A = B

, and assigns each element of

X^{'}

to the corresponding element of B.

If so such

X^{'}

exists, then the elements of B are valid but unspecified.

Complexity:

O (A.extent(0) \times A.extent(1) \times B.extent(1))

🔗

template<in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat>
  void triangular_matrix_matrix_right_solve(InMat A, Triangle t, DiagonalStorage d, InOutMat B);

Effects: Equivalent to: triangular_matrix_matrix_right_solve(A, t, d, B, divides<void>{});

🔗

template<class ExecutionPolicy,
         in-matrix InMat, class Triangle, class DiagonalStorage, inout-matrix InOutMat>
  void triangular_matrix_matrix_right_solve(ExecutionPolicy&& exec,
                                            InMat A, Triangle t, DiagonalStorage d,
                                            InOutMat B);

Effects: Equivalent to: triangular_matrix_matrix_right_solve(std::forward<ExecutionPolicy>(exec), A, t, d, B, divides<void>{});

🔗	$f_{n} (j)$		j
🔗			0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15
🔗	n	2	0	1
🔗		4	0	3	2	1
🔗		8	2	1	4	7	6	5	0	3
🔗		16	0	9	2	13	6	11	4	15	10	7	12	3	14	5	8	1
🔗