sigma  1.0.0
Loading...
Searching...
No Matches
sigma::Monomial Class Reference

Represents a sparse multi-index exponent. More...

#include <monomial.hpp>

Public Types

using size_type = std::size_t
 Type used for indexing, offsets, and total degree.
using variable_t = size_type
 Opaque type used to identify an expansion variable.
using exponent_t = size_type
 Type used to store the exponent of a single variable.
using exponents_t = std::map<variable_t, exponent_t>
 Type used to map variables to their exponents.

Public Member Functions

 Monomial ()=default
 Constructs the constant monomial.
 Monomial (variable_t var, exponent_t exp=1)
 Constructs a single-variable monomial.
 Monomial (exponents_t exponents)
 Constructs a monomial from a full map of exponents.
 Monomial (const Monomial &other)=default
 Makes a deep copy of other.
 Monomial (Monomial &&other) noexcept=default
 Constructs a monomial by moving other.
Monomial & operator= (const Monomial &other)=default
 Assigns the value of other to this monomial.
Monomial & operator= (Monomial &&other) noexcept=default
 Moves the value of other to this monomial.
const exponents_t & exponents () const noexcept
 Returns the exponents of the monomial.
exponent_t exponent (variable_t var) const
 Returns the exponent of a single variable.
size_type degree () const noexcept
 Returns the total degree of the monomial.
bool empty () const noexcept
 Checks if *this is the constant monomial.
Monomial & operator*= (const Monomial &other)
 Overwrites *this with the product of *this and other.
Monomial operator* (const Monomial &other) const
 Returns the product of *this and other.
bool operator== (const Monomial &other) const
 Checks if *this and other represent the same monomial.
bool operator!= (const Monomial &other) const
 Checks if *this and other represent different monomials.
bool operator< (const Monomial &other) const
 Defines a strict weak ordering over monomials.
std::string print () const
 Creates a string representation of *this.

Static Public Member Functions

static variable_t make_variable ()

(Note that these are not member symbols.)

std::ostream & operator<< (std::ostream &os, const Monomial &m)
 Outputs a monomial to an output stream.

Detailed Description

Represents a sparse multi-index exponent.

A multi-index \(\beta = (\beta_1, \ldots, \beta_v)\) assigns a non-negative integer exponent to each of \(v\) expansion variables, and a Monomial identifies the corresponding monomial \(\delta^{\beta} = \delta_1^{\beta_1} \delta_2^{\beta_2} \cdots \delta_v^{\beta_v}\). This is the exponent type used by the polynomial part of a Taylor model (see docs/taylor.md).

Expansion variables are opaque, process-wide unique identifiers minted by make_variable(), exactly as Affine mints its error term symbols. A Monomial only ever stores entries for variables with a nonzero exponent; a Monomial with no entries is the constant monomial (degree 0, i.e. the multiplicative identity).

N.b. Monomial is not templated on a floating-point type. Its state is exponents (non-negative integers), not the coefficients or radii that Affine and Taylor associate with them.

Constructor & Destructor Documentation

◆ Monomial() [1/3]

sigma::Monomial::Monomial ( )
default

Constructs the constant monomial.

The constant monomial has no variables and represents the multiplicative identity, i.e. \(\delta^{\beta} = 1\).

Exceptions
noneNo throw guarantee

◆ Monomial() [2/3]

sigma::Monomial::Monomial ( variable_t var,
exponent_t exp = 1 )
inlineexplicit

Constructs a single-variable monomial.

The resulting monomial represents \(\delta_{v}^{e}\) for the variable var and exponent exp.

Parameters
[in]varThe variable raised to a power in the resulting monomial.
[in]expThe exponent of var, defaults to 1.
Note
This constructor is envisioned as primarily being used to initialize the first monomial. That really shouldn't result in a zero exponent, so passing a zero is likely a programming error. The default constructor is available if it really is supposed to be the constant monomial.
Exceptions
std::invalid_argumentIf exp is 0. A Monomial only stores variables with nonzero exponent, so a single-variable monomial with exponent 0 is not representable by this ctor; use the default ctor instead. Strong throw guarantee.

◆ Monomial() [3/3]

sigma::Monomial::Monomial ( exponents_t exponents)
inlineexplicit

Constructs a monomial from a full map of exponents.

This constructor allows for the creation of a monomial by specifying the full state of the monomial (the exponent of each variable). Any entries in exponents whose exponent is 0 are dropped, so the invariant that only nonzero exponents are stored holds regardless of what is passed in.

Note
This ctor is envisioned as being used to initialize a monomial after arithmetic operations. It is natural for such operations to produce a map with zero entries, so this ctor will drop the zero terms instead of throwing.
Parameters
[in]exponentsA map of variables to their exponents.
Exceptions
std::bad_allocIf memory allocation for the exponent map fails. Strong throw guarantee.

Member Function Documentation

◆ degree()

size_type sigma::Monomial::degree ( ) const
inlinenoexcept

Returns the total degree of the monomial.

The total degree is \(|\beta| = \beta_1 + \beta_2 + \cdots + \beta_v\), the sum of the exponents over every variable.

Returns
The total degree of *this.
Exceptions
noneNo throw guarantee

◆ empty()

bool sigma::Monomial::empty ( ) const
inlinenoexcept

Checks if *this is the constant monomial.

N.b. unlike Affine::empty(), which denotes the empty set, this denotes the constant monomial (degree 0, no variables) – a perfectly ordinary, non-empty-set value.

Returns
True if *this has no variables (equivalently, degree() == 0), false otherwise.
Exceptions
noneNo throw guarantee

◆ exponent()

exponent_t sigma::Monomial::exponent ( variable_t var) const
inline

Returns the exponent of a single variable.

Parameters
[in]varThe variable whose exponent is requested.
Returns
The exponent of var, or 0 if var does not appear in *this.
Exceptions
noneNo throw guarantee

◆ exponents()

const exponents_t & sigma::Monomial::exponents ( ) const
inlinenoexcept

Returns the exponents of the monomial.

Returns
A map from variable to its (nonzero) exponent.
Exceptions
noneNo throw guarantee

◆ make_variable()

variable_t sigma::Monomial::make_variable ( )
inlinestatic

Returns a process-wide unique integer ID for a new expansion variable.

◆ operator!=()

bool sigma::Monomial::operator!= ( const Monomial & other) const
inline

Checks if *this and other represent different monomials.

Parameters
[in]otherThe monomial to compare with *this.
Returns
True if *this and other represent different monomials, false otherwise.
Exceptions
noneNo throw guarantee

◆ operator*()

Monomial sigma::Monomial::operator* ( const Monomial & other) const
inline

Returns the product of *this and other.

This is a convenience method for calling Monomial(*this) *= other. See the documentation for operator*=(Monomial) for details on how multiplication works.

Parameters
[in]otherThe monomial to multiply *this by.
Returns
The product of *this and other.
Exceptions
std::bad_allocIf memory allocation for the new exponent map fails. Strong throw guarantee.

◆ operator*=()

Monomial & sigma::Monomial::operator*= ( const Monomial & other)
inline

Overwrites *this with the product of *this and other.

The product of two monomials is the monomial whose exponent for each variable is the sum of the two operands' exponents for that variable:

\[ \delta^{\beta_1} \cdot \delta^{\beta_2} = \delta^{\beta_1 + \beta_2} \]

A variable that appears in only one operand is carried over to the result unchanged, as if it had exponent 0 in the operand that lacks it.

Parameters
[in]otherThe monomial to multiply *this by.
Returns
Reference to this monomial after multiplication.
Exceptions
std::bad_allocIf memory allocation for the new exponent map fails. Strong throw guarantee.

◆ operator<()

bool sigma::Monomial::operator< ( const Monomial & other) const
inline

Defines a strict weak ordering over monomials.

This ordering has no particular mathematical significance; it exists so that Monomial can be used as the key type of an ordered associative container (e.g. the coefficient map of a Taylor polynomial). It is implemented as the lexicographic order induced by std::map::operator< on exponents().

Parameters
[in]otherThe monomial to compare with *this.
Returns
True if *this orders before other, false otherwise.
Exceptions
noneNo throw guarantee

◆ operator==()

bool sigma::Monomial::operator== ( const Monomial & other) const
inline

Checks if *this and other represent the same monomial.

Two monomials are equal if they have the same exponent for every variable (equivalently, if their exponents() maps compare equal).

Parameters
[in]otherThe monomial to compare with *this.
Returns
True if *this and other represent the same monomial, false otherwise.
Exceptions
noneNo throw guarantee

◆ print()

std::string sigma::Monomial::print ( ) const
inline

Creates a string representation of *this.

The constant monomial is printed as "1"; otherwise each variable with a nonzero exponent is printed as "v<id>^<exponent>", joined by " * ", in variable order.

Returns
A string representation of *this.
Exceptions
std::bad_allocIf memory allocation for the string fails. Strong throw guarantee.

◆ operator<<()

std::ostream & operator<< ( std::ostream & os,
const Monomial & m )
related

Outputs a monomial to an output stream.

This method defers to Monomial::print() to build the string that is written to os.

Parameters
[in]osThe output stream to write to.
[in]mThe monomial to output.
Returns
The output stream.
Exceptions
noneNo throw guarantee.

The documentation for this class was generated from the following file: