chromium/third_party/eigen3/src/Eigen/src/Core/util/Constants.h

// This file is part of Eigen, a lightweight C++ template library
// for linear algebra.
//
// Copyright (C) 2008-2015 Gael Guennebaud <[email protected]>
// Copyright (C) 2007-2009 Benoit Jacob <[email protected]>
// Copyright (C) 2020, Arm Limited and Contributors
//
// This Source Code Form is subject to the terms of the Mozilla
// Public License v. 2.0. If a copy of the MPL was not distributed
// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

#ifndef EIGEN_CONSTANTS_H
#define EIGEN_CONSTANTS_H

// IWYU pragma: private
#include "../InternalHeaderCheck.h"

namespace Eigen {

/** This value means that a positive quantity (e.g., a size) is not known at compile-time, and that instead the value is
 * stored in some runtime variable.
 *
 * Changing the value of Dynamic breaks the ABI, as Dynamic is often used as a template parameter for Matrix.
 */
const int Dynamic = …;

/** This value means that a signed quantity (e.g., a signed index) is not known at compile-time, and that instead its
 * value has to be specified at runtime.
 */
const int DynamicIndex = …;

/** This value means that the requested value is not defined.
 */
const int Undefined = …;

/** This value means +Infinity; it is currently used only as the p parameter to MatrixBase::lpNorm<int>().
 * The value Infinity there means the L-infinity norm.
 */
const int Infinity = …;

/** This value means that the cost to evaluate an expression coefficient is either very expensive or
 * cannot be known at compile time.
 *
 * This value has to be positive to (1) simplify cost computation, and (2) allow to distinguish between a very expensive
 * and very very expensive expressions. It thus must also be large enough to make sure unrolling won't happen and that
 * sub expressions will be evaluated, but not too large to avoid overflow.
 */
const int HugeCost = …;

/** \defgroup flags Flags
 * \ingroup Core_Module
 *
 * These are the possible bits which can be OR'ed to constitute the flags of a matrix or
 * expression.
 *
 * It is important to note that these flags are a purely compile-time notion. They are a compile-time property of
 * an expression type, implemented as enum's. They are not stored in memory at runtime, and they do not incur any
 * runtime overhead.
 *
 * \sa MatrixBase::Flags
 */

/** \ingroup flags
 *
 * for a matrix, this means that the storage order is row-major.
 * If this bit is not set, the storage order is column-major.
 * For an expression, this determines the storage order of
 * the matrix created by evaluation of that expression.
 * \sa \blank  \ref TopicStorageOrders */
const unsigned int RowMajorBit = …;

/** \ingroup flags
 * means the expression should be evaluated by the calling expression */
const unsigned int EvalBeforeNestingBit = …;

/** \ingroup flags
 * \deprecated
 * means the expression should be evaluated before any assignment */
EIGEN_DEPRECATED const unsigned int EvalBeforeAssigningBit = …;  // FIXME deprecated

/** \ingroup flags
 *
 * Short version: means the expression might be vectorized
 *
 * Long version: means that the coefficients can be handled by packets
 * and start at a memory location whose alignment meets the requirements
 * of the present CPU architecture for optimized packet access. In the fixed-size
 * case, there is the additional condition that it be possible to access all the
 * coefficients by packets (this implies the requirement that the size be a multiple of 16 bytes,
 * and that any nontrivial strides don't break the alignment). In the dynamic-size case,
 * there is no such condition on the total size and strides, so it might not be possible to access
 * all coeffs by packets.
 *
 * \note This bit can be set regardless of whether vectorization is actually enabled.
 *       To check for actual vectorizability, see \a ActualPacketAccessBit.
 */
const unsigned int PacketAccessBit = …;

#ifdef EIGEN_VECTORIZE
/** \ingroup flags
 *
 * If vectorization is enabled (EIGEN_VECTORIZE is defined) this constant
 * is set to the value \a PacketAccessBit.
 *
 * If vectorization is not enabled (EIGEN_VECTORIZE is not defined) this constant
 * is set to the value 0.
 */
const unsigned int ActualPacketAccessBit = …;
#else
const unsigned int ActualPacketAccessBit = 0x0;
#endif

/** \ingroup flags
 *
 * Short version: means the expression can be seen as 1D vector.
 *
 * Long version: means that one can access the coefficients
 * of this expression by coeff(int), and coeffRef(int) in the case of a lvalue expression. These
 * index-based access methods are guaranteed
 * to not have to do any runtime computation of a (row, col)-pair from the index, so that it
 * is guaranteed that whenever it is available, index-based access is at least as fast as
 * (row,col)-based access. Expressions for which that isn't possible don't have the LinearAccessBit.
 *
 * If both PacketAccessBit and LinearAccessBit are set, then the
 * packets of this expression can be accessed by packet(int), and writePacket(int) in the case of a
 * lvalue expression.
 *
 * Typically, all vector expressions have the LinearAccessBit, but there is one exception:
 * Product expressions don't have it, because it would be troublesome for vectorization, even when the
 * Product is a vector expression. Thus, vector Product expressions allow index-based coefficient access but
 * not index-based packet access, so they don't have the LinearAccessBit.
 */
const unsigned int LinearAccessBit = …;

/** \ingroup flags
 *
 * Means the expression has a coeffRef() method, i.e. is writable as its individual coefficients are directly
 * addressable. This rules out read-only expressions.
 *
 * Note that DirectAccessBit and LvalueBit are mutually orthogonal, as there are examples of expression having one but
 * not the other: \li writable expressions that don't have a very simple memory layout as a strided array, have
 * LvalueBit but not DirectAccessBit \li Map-to-const expressions, for example Map<const Matrix>, have DirectAccessBit
 * but not LvalueBit
 *
 * Expressions having LvalueBit also have their coeff() method returning a const reference instead of returning a new
 * value.
 */
const unsigned int LvalueBit = …;

/** \ingroup flags
 *
 * Means that the underlying array of coefficients can be directly accessed as a plain strided array. The memory layout
 * of the array of coefficients must be exactly the natural one suggested by rows(), cols(),
 * outerStride(), innerStride(), and the RowMajorBit. This rules out expressions such as Diagonal, whose coefficients,
 * though referencable, do not have such a regular memory layout.
 *
 * See the comment on LvalueBit for an explanation of how LvalueBit and DirectAccessBit are mutually orthogonal.
 */
const unsigned int DirectAccessBit = …;

/** \deprecated \ingroup flags
 *
 * means the first coefficient packet is guaranteed to be aligned.
 * An expression cannot have the AlignedBit without the PacketAccessBit flag.
 * In other words, this means we are allow to perform an aligned packet access to the first element regardless
 * of the expression kind:
 * \code
 * expression.packet<Aligned>(0);
 * \endcode
 */
EIGEN_DEPRECATED const unsigned int AlignedBit = …;

const unsigned int NestByRefBit = …;

/** \ingroup flags
 *
 * for an expression, this means that the storage order
 * can be either row-major or column-major.
 * The precise choice will be decided at evaluation time or when
 * combined with other expressions.
 * \sa \blank  \ref RowMajorBit, \ref TopicStorageOrders */
const unsigned int NoPreferredStorageOrderBit = …;

/** \ingroup flags
  *
  * Means that the underlying coefficients can be accessed through pointers to the sparse (un)compressed storage format,
  * that is, the expression provides:
  * \code
    inline const Scalar* valuePtr() const;
    inline const Index* innerIndexPtr() const;
    inline const Index* outerIndexPtr() const;
    inline const Index* innerNonZeroPtr() const;
    \endcode
  */
const unsigned int CompressedAccessBit = …;

// list of flags that are inherited by default
const unsigned int HereditaryBits = …;

/** \defgroup enums Enumerations
 * \ingroup Core_Module
 *
 * Various enumerations used in %Eigen. Many of these are used as template parameters.
 */

/** \ingroup enums
 * Enum containing possible values for the \c Mode or \c UpLo parameter of
 * MatrixBase::selfadjointView() and MatrixBase::triangularView(), and selfadjoint solvers. */
enum UpLoType { … };

/** \ingroup enums
 * Enum for indicating whether a buffer is aligned or not. */
enum AlignmentType { … };

/** \ingroup enums
 * Enum containing possible values for the \p Direction parameter of
 * Reverse, PartialReduxExpr and VectorwiseOp. */
enum DirectionType { … };

/** \internal \ingroup enums
 * Enum to specify how to traverse the entries of a matrix. */
enum TraversalType { … };

/** \internal \ingroup enums
 * Enum to specify whether to unroll loops when traversing over the entries of a matrix. */
enum UnrollingType { … };

/** \internal \ingroup enums
 * Enum to specify whether to use the default (built-in) implementation or the specialization. */
enum SpecializedType { … };

/** \ingroup enums
 * Enum containing possible values for the \p Options_ template parameter of
 * Matrix, Array and BandMatrix. */
enum StorageOptions { … };

/** \ingroup enums
 * Enum for specifying whether to apply or solve on the left or right. */
enum SideType { … };

/** \ingroup enums
 * Enum for specifying NaN-propagation behavior, e.g. for coeff-wise min/max. */
enum NaNPropagationOptions { … };

/* the following used to be written as:
 *
 *   struct NoChange_t {};
 *   namespace {
 *     EIGEN_UNUSED NoChange_t NoChange;
 *   }
 *
 * on the ground that it feels dangerous to disambiguate overloaded functions on enum/integer types.
 * However, this leads to "variable declared but never referenced" warnings on Intel Composer XE,
 * and we do not know how to get rid of them (bug 450).
 */

enum NoChange_t { … };
enum Sequential_t { … };
enum Default_t { … };

/** \internal \ingroup enums
 * Used in AmbiVector. */
enum AmbiVectorMode { … };

/** \ingroup enums
 * Used as template parameter in DenseCoeffBase and MapBase to indicate
 * which accessors should be provided. */
enum AccessorLevels { … };

/** \ingroup enums
 * Enum with options to give to various decompositions. */
enum DecompositionOptions { … };

/** \ingroup enums
 * Possible values for the \p QRPreconditioner template parameter of JacobiSVD. */
enum QRPreconditioners { … };

#ifdef Success
#error The preprocessor symbol 'Success' is defined, possibly by the X11 header file X.h
#endif

/** \ingroup enums
 * Enum for reporting the status of a computation. */
enum ComputationInfo { … };

/** \ingroup enums
 * Enum used to specify how a particular transformation is stored in a matrix.
 * \sa Transform, Hyperplane::transform(). */
enum TransformTraits { … };

/** \internal \ingroup enums
 * Enum used to choose between implementation depending on the computer architecture. */
namespace Architecture {
enum Type { … };
}  // namespace Architecture

/** \internal \ingroup enums
 * Enum used as template parameter in Product and product evaluators. */
enum ProductImplType { … };

/** \internal \ingroup enums
 * Enum used in experimental parallel implementation. */
enum Action { … };

/** The type used to identify a dense storage. */
struct Dense { … };

/** The type used to identify a general sparse storage. */
struct Sparse { … };

/** The type used to identify a general solver (factored) storage. */
struct SolverStorage { … };

/** The type used to identify a permutation storage. */
struct PermutationStorage { … };

/** The type used to identify a permutation storage. */
struct TranspositionsStorage { … };

/** The type used to identify a matrix expression */
struct MatrixXpr { … };

/** The type used to identify an array expression */
struct ArrayXpr { … };

// An evaluator must define its shape. By default, it can be one of the following:
struct DenseShape { … };
struct SolverShape { … };
struct HomogeneousShape { … };
struct DiagonalShape { … };
struct SkewSymmetricShape { … };
struct BandShape { … };
struct TriangularShape { … };
struct SelfAdjointShape { … };
struct PermutationShape { … };
struct TranspositionsShape { … };
struct SparseShape { … };

namespace internal {

// random access iterators based on coeff*() accessors.
struct IndexBased { … };

// evaluator based on iterators to access coefficients.
struct IteratorBased { … };

/** \internal
 * Constants for comparison functors
 */
enum ComparisonName : unsigned int { … };
}  // end namespace internal

}  // end namespace Eigen

#endif  // EIGEN_CONSTANTS_H