Detailed Description

A MathOpt optimization model and modification trackers.

Holds the elements, the attribute values, and tracks modifications to the model by Diff objects, and keeps them all in sync. See README.md for details.

Definition at line 49 of file elemental.h.

#include <elemental.h>

Classes
struct	AlwaysOk
struct	DiePolicy
class	DiffHandle
struct	StatusPolicy
struct	UBPolicy

Public Member Functions
	Elemental (std::string model_name="", std::string primary_objective_name="")
const std::string &	model_name () const
	The name of this optimization model.
const std::string &	primary_objective_name () const
	The name of the primary objective of this optimization model.
template<ElementType e>
ElementId< e >	AddElement (const absl::string_view name)
	Creates and returns the id of a new element for the element type e.
int64_t	AddElementUntyped (const ElementType e, const absl::string_view name)
	Type-erased version of AddElement. Prefer the latter.
template<ElementType e>
bool	DeleteElement (const ElementId< e > id)
bool	DeleteElementUntyped (ElementType e, int64_t id)
	Type-erased version of DeleteElement. Prefer the latter.
template<ElementType e>
bool	ElementExists (const ElementId< e > id) const
bool	ElementExistsUntyped (const ElementType e, const int64_t id) const
	Type-erased version of ElementExists. Prefer the latter.
template<ElementType e>
absl::StatusOr< absl::string_view >	GetElementName (const ElementId< e > id) const
absl::StatusOr< absl::string_view >	GetElementNameUntyped (const ElementType e, const int64_t id) const
	Type-erased version of GetElementName. Prefer the latter.
template<ElementType e>
ElementIdsVector< e >	AllElements () const
std::vector< int64_t >	AllElementsUntyped (const ElementType e) const
	Type-erased version of AllElements. Prefer the latter.
int64_t	NextElementId (const ElementType e) const
int64_t	NumElements (const ElementType e) const
template<ElementType e>
void	EnsureNextElementIdAtLeast (const ElementId< e > id)
void	EnsureNextElementIdAtLeastUntyped (const ElementType e, int64_t id)
	Type-erased version of EnsureNextElementIdAtLeast. Prefer the latter.
template<typename AttrType>
void	AttrClear (AttrType a)
	Inline and template implementation.
template<typename AttrType>
std::vector< AttrKeyFor< AttrType > >	AttrNonDefaults (const AttrType a) const
	Return the vector of attribute keys where a is non-default.
template<typename AttrType>
int64_t	AttrNumNonDefaults (const AttrType a) const
	Returns the number of keys where a is non-default.
template<typename Policy = DiePolicy, typename AttrType>
Policy::template Wrapped< ValueTypeFor< AttrType > >	GetAttr (AttrType a, AttrKeyFor< AttrType > key) const
template<typename Policy = DiePolicy, typename AttrType>
Policy::template Wrapped< bool >	AttrIsNonDefault (AttrType a, AttrKeyFor< AttrType > key) const
template<typename Policy = DiePolicy, typename AttrType>
Policy::CheckResultT	SetAttr (AttrType a, AttrKeyFor< AttrType > key, ValueTypeFor< AttrType > value)
template<int i, typename Policy = DiePolicy, typename AttrType = void>
Policy::template Wrapped< std::vector< AttrKeyFor< AttrType > > >	Slice (AttrType a, int64_t key_elem) const
template<int i, typename Policy = DiePolicy, typename AttrType = void>
Policy::template Wrapped< int64_t >	GetSliceSize (AttrType a, int64_t key_elem) const
Elemental	Clone (std::optional< absl::string_view > new_model_name=std::nullopt) const
absl::StatusOr< ModelProto >	ExportModel (bool remove_names=false) const
absl::Status	ApplyUpdateProto (const ModelUpdateProto &update_proto)
	Applies the changes to the model in update_proto.
std::optional< DiffHandle >	GetDiffHandle (int64_t id) const
	Returns the DiffHandle for id, if one exists, or nullopt otherwise.
DiffHandle	AddDiff ()
bool	DeleteDiff (DiffHandle diff)
int64_t	NumDiffs () const
	The number of diffs currently tracking this.
bool	Advance (DiffHandle diff)
template<typename AttrType>
std::vector< AttrKeyFor< AttrType > >	ModifiedKeysThatExist (AttrType attr, const Diff &diff) const
absl::StatusOr< std::optional< ModelUpdateProto > >	ExportModelUpdate (DiffHandle diff, bool remove_names=false) const
std::string	DebugString (bool print_diffs=true) const

Static Public Member Functions
static absl::StatusOr< Elemental >	FromModelProto (const ModelProto &proto)
	Creates an equivalent Elemental to proto.

Constructor & Destructor Documentation

◆ Elemental()

operations_research::math_opt::Elemental::Elemental	(	std::string	model_name = "",
		std::string	primary_objective_name = "" )

explicit

NOLINTNEXTLINE(clang-diagnostic-pre-c++20-compat)

Definition at line 38 of file elemental.cc.

Member Function Documentation

◆ AddDiff()

Elemental::DiffHandle operations_research::math_opt::Elemental::AddDiff ( )

Returned handle is valid until passed DeleteDiff or *this is destructed.

Definition at line 60 of file elemental.cc.

◆ AddElement()

template<ElementType e>

ElementId< e > operations_research::math_opt::Elemental::AddElement ( const absl::string_view name )

inline

Creates and returns the id of a new element for the element type e.

Elements

Definition at line 87 of file elemental.h.

◆ AddElementUntyped()

int64_t operations_research::math_opt::Elemental::AddElementUntyped	(	const ElementType	e,
		const absl::string_view	name )

inline

Type-erased version of AddElement. Prefer the latter.

Definition at line 92 of file elemental.h.

◆ Advance()

bool operations_research::math_opt::Elemental::Advance ( DiffHandle diff )

Returns true on success (fails if diff was null, deleted or from the wrong elemental). Warning: diff is modified (owned by this).

Definition at line 74 of file elemental.cc.

◆ AllElements()

template<ElementType e>

ElementIdsVector< e > operations_research::math_opt::Elemental::AllElements ( ) const

inline

Returns the ids of all elements of element type e in the model in an unsorted, non-deterministic order.

Definition at line 136 of file elemental.h.

◆ AllElementsUntyped()

std::vector< int64_t > operations_research::math_opt::Elemental::AllElementsUntyped ( const ElementType e ) const

inline

Type-erased version of AllElements. Prefer the latter.

Definition at line 141 of file elemental.h.

◆ ApplyUpdateProto()

absl::Status operations_research::math_opt::Elemental::ApplyUpdateProto ( const ModelUpdateProto & update_proto )

Applies the changes to the model in update_proto.

Definition at line 474 of file elemental_from_proto.cc.

◆ AttrClear()

template<typename AttrType>

void operations_research::math_opt::Elemental::AttrClear ( AttrType a )

Inline and template implementation.

Restores the attribute a to its default value for all AttrKeys (or for an Attr0, its only value).

Note: this is slightly faster than setting each non-default back to the default value.

Definition at line 406 of file elemental.h.

◆ AttrIsNonDefault()

template<typename Policy, typename AttrType>

Policy::template Wrapped< bool > operations_research::math_opt::Elemental::AttrIsNonDefault	(	AttrType	a,
		AttrKeyFor< AttrType >	key ) const

Returns true if the attr a for key has a value different from its default.

Definition at line 441 of file elemental.h.

◆ AttrNonDefaults()

template<typename AttrType>

std::vector< AttrKeyFor< AttrType > > operations_research::math_opt::Elemental::AttrNonDefaults ( const AttrType a ) const

inline

Return the vector of attribute keys where a is non-default.

Definition at line 215 of file elemental.h.

◆ AttrNumNonDefaults()

template<typename AttrType>

int64_t operations_research::math_opt::Elemental::AttrNumNonDefaults ( const AttrType a ) const

inline

Returns the number of keys where a is non-default.

Definition at line 221 of file elemental.h.

◆ Clone()

Elemental operations_research::math_opt::Elemental::Clone ( std::optional< absl::string_view > new_model_name = std::nullopt ) const

Returns a copy of this, but with no diffs. The name of the model can optionally be replaced by new_model_name.

Definition at line 155 of file elemental.cc.

◆ DebugString()

std::string operations_research::math_opt::Elemental::DebugString ( bool print_diffs = true ) const

Prints out the model by element and attribute. If print_diffs is true, also prints out the deleted elements and modified keys for each attribute for each DiffHandle tracked.

This is a debug format. Do not assume the output is consistent across CLs and do not parse this format.

It intentional that that this function is implemented without access to the private API of elemental. This allows us to change the implementation elemental without breaking the DebugString() code.

Definition at line 155 of file elemental_to_string.cc.

◆ DeleteDiff()

bool operations_research::math_opt::Elemental::DeleteDiff ( DiffHandle diff )

Deletes diff & invalidates it. Returns false if the handle was invalid or from the wrong elemental). On success, invalidates diff.

Definition at line 67 of file elemental.cc.

◆ DeleteElement()

template<ElementType e>

bool operations_research::math_opt::Elemental::DeleteElement ( const ElementId< e > id )

inline

Deletes the element with id for element type e, returning true on success and false if no element was deleted (it was already deleted or the id was not from any existing element).

Definition at line 100 of file elemental.h.

◆ DeleteElementUntyped()

bool operations_research::math_opt::Elemental::DeleteElementUntyped	(	ElementType	e,
		int64_t	id )

Type-erased version of DeleteElement. Prefer the latter.

NOLINTNEXTLINE(clang-diagnostic-pre-c++20-compat)

If a is element-valued, we need to remove all keys that refer to the deleted element.

Definition at line 86 of file elemental.cc.

◆ ElementExists()

template<ElementType e>

bool operations_research::math_opt::Elemental::ElementExists ( const ElementId< e > id ) const

inline

Returns true the element with id for element type e exists (it was created and not yet deleted).

Definition at line 110 of file elemental.h.

◆ ElementExistsUntyped()

bool operations_research::math_opt::Elemental::ElementExistsUntyped	(	const ElementType	e,
		const int64_t	id ) const

inline

Type-erased version of ElementExists. Prefer the latter.

Definition at line 115 of file elemental.h.

◆ EnsureNextElementIdAtLeast()

template<ElementType e>

void operations_research::math_opt::Elemental::EnsureNextElementIdAtLeast ( const ElementId< e > id )

inline

Increases next_element_id(e) to id if it is currently less than id.

Useful for reading a model back from proto, most users should not need to call this directly.

Definition at line 166 of file elemental.h.

◆ EnsureNextElementIdAtLeastUntyped()

void operations_research::math_opt::Elemental::EnsureNextElementIdAtLeastUntyped	(	const ElementType	e,
		int64_t	id )

inline

Type-erased version of EnsureNextElementIdAtLeast. Prefer the latter.

Definition at line 171 of file elemental.h.

◆ ExportModel()

absl::StatusOr< ModelProto > operations_research::math_opt::Elemental::ExportModel ( bool remove_names = false ) const

Working with proto Returns an equivalent protocol buffer. Fails if the model is too big to fit in the in-memory representation of the proto (it has more than 2**31-1 elements of a type or non-defaults for an attribute).

It intentional that that this function is implemented without access to the private API of elemental. This allows us to change the implementation elemental without breaking the proto export code.

Definition at line 525 of file elemental_export_model.cc.

◆ ExportModelUpdate()

absl::StatusOr< std::optional< ModelUpdateProto > > operations_research::math_opt::Elemental::ExportModelUpdate	(	DiffHandle	diff,
		bool	remove_names = false ) const

Returns a proto describing all changes to the model for diff since the most recent call to Advance(diff) (or the creation of diff if Advance() was never called).

Returns std::nullopt the resulting ModelUpdateProto would be the empty message (there have been no changes to the model to report).

Fails if the update is too big to fit in the in-memory representation of the proto (it has more than 2**31-1 elements in a RepeatedField).

It intentional that that this function is implemented without access to the private API of elemental. This allows us to change the implementation elemental without breaking the proto export code.

Definition at line 1065 of file elemental_export_model.cc.

◆ FromModelProto()

absl::StatusOr< Elemental > operations_research::math_opt::Elemental::FromModelProto ( const ModelProto & proto )

static

Creates an equivalent Elemental to proto.

It intentional that that this function is implemented without access to the private API of elemental. This allows us to change the implementation elemental without breaking the proto export code.

Definition at line 467 of file elemental_from_proto.cc.

◆ GetAttr()

template<typename Policy, typename AttrType>

Policy::template Wrapped< ValueTypeFor< AttrType > > operations_research::math_opt::Elemental::GetAttr	(	AttrType	a,
		AttrKeyFor< AttrType >	key ) const

Returns the value of the attr a for key:

get_attr(DoubleAttr1::kVarUb, AttrKey(x)) returns a double value if element id x exists, and crashes otherwise. The returned value is the default value if the attribute has not been set for x.
get_attr<StatusPolicy>(DoubleAttr1::kVarUb, AttrKey(x)) returns a valid StatusOr<double> if element id x exists, and an error otherwise.

Definition at line 434 of file elemental.h.

◆ GetDiffHandle()

std::optional< Elemental::DiffHandle > operations_research::math_opt::Elemental::GetDiffHandle ( int64_t id ) const

Returns the DiffHandle for id, if one exists, or nullopt otherwise.

Diffs

Definition at line 52 of file elemental.cc.

◆ GetElementName()

template<ElementType e>

absl::StatusOr< absl::string_view > operations_research::math_opt::Elemental::GetElementName ( const ElementId< e > id ) const

inline

Returns the name of the element with id for element type e, or an error if this element does not exist.

Definition at line 122 of file elemental.h.

◆ GetElementNameUntyped()

absl::StatusOr< absl::string_view > operations_research::math_opt::Elemental::GetElementNameUntyped	(	const ElementType	e,
		const int64_t	id ) const

inline

Type-erased version of GetElementName. Prefer the latter.

Definition at line 128 of file elemental.h.

◆ GetSliceSize()

template<int i, typename Policy, typename AttrType>

Policy::template Wrapped< int64_t > operations_research::math_opt::Elemental::GetSliceSize	(	AttrType	a,
		int64_t	key_elem ) const

Returns the size of the given slice: This is equivalent to Slice(a, / key_elem).size(), but O(1).

Definition at line 477 of file elemental.h.

◆ model_name()

const std::string & operations_research::math_opt::Elemental::model_name ( ) const

inline

The name of this optimization model.

Definition at line 72 of file elemental.h.

◆ ModifiedKeysThatExist()

template<typename AttrType>

std::vector< AttrKeyFor< AttrType > > operations_research::math_opt::Elemental::ModifiedKeysThatExist	(	AttrType	attr,
		const Diff &	diff ) const

Internal use only (users of Elemental cannot access Diff directly), but prefer to invoking Diff::modified_keys() directly..

Returns the modified keys in a Diff for an attribute, filtering out the keys referring to an element that has been deleted.

This is needed because in some situations where a variable is deleted we cannot clean up the diff, see README.md.

Can be a slight overestimate.

Definition at line 532 of file elemental.h.

◆ NextElementId()

int64_t operations_research::math_opt::Elemental::NextElementId ( const ElementType e ) const

inline

Returns the id of next element created for element type e.

Equal to one plus the number of elements that were created for element type e. When no elements have been deleted, this equals num_elements(e).

Definition at line 149 of file elemental.h.

◆ NumDiffs()

int64_t operations_research::math_opt::Elemental::NumDiffs ( ) const

inline

The number of diffs currently tracking this.

Definition at line 300 of file elemental.h.

◆ NumElements()

int64_t operations_research::math_opt::Elemental::NumElements ( const ElementType e ) const

inline

Returns the number of elements in the model for element type e.

Equal to the number of elements that were created minus the number deleted for element type e.

Definition at line 157 of file elemental.h.

◆ primary_objective_name()

const std::string & operations_research::math_opt::Elemental::primary_objective_name ( ) const

inline

The name of the primary objective of this optimization model.

Definition at line 75 of file elemental.h.

◆ SetAttr()

template<typename Policy, typename AttrType>

Policy::CheckResultT operations_research::math_opt::Elemental::SetAttr	(	AttrType	a,
		AttrKeyFor< AttrType >	key,
		ValueTypeFor< AttrType >	value )

Sets the value of the attr a for the element key to value, and returns true if the value of the attribute has changed.

Definition at line 448 of file elemental.h.

◆ Slice()

template<int i, typename Policy, typename AttrType>

Policy::template Wrapped< std::vector< AttrKeyFor< AttrType > > > operations_research::math_opt::Elemental::Slice	(	AttrType	a,
		int64_t	key_elem ) const

Returns the set of all keys k such that k[i] == key_elem and k has a non-default value for the attribute a.

Definition at line 470 of file elemental.h.

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

ortools/math_opt/elemental/elemental.h
ortools/math_opt/elemental/elemental.cc
ortools/math_opt/elemental/elemental_export_model.cc
ortools/math_opt/elemental/elemental_from_proto.cc
ortools/math_opt/elemental/elemental_to_string.cc

Detailed Description

Classes

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ Elemental()

Member Function Documentation

◆ AddDiff()

◆ AddElement()

◆ AddElementUntyped()

◆ Advance()

◆ AllElements()

◆ AllElementsUntyped()

◆ ApplyUpdateProto()

◆ AttrClear()

◆ AttrIsNonDefault()

◆ AttrNonDefaults()

◆ AttrNumNonDefaults()

◆ Clone()

◆ DebugString()

◆ DeleteDiff()

◆ DeleteElement()

◆ DeleteElementUntyped()

◆ ElementExists()

◆ ElementExistsUntyped()

◆ EnsureNextElementIdAtLeast()

◆ EnsureNextElementIdAtLeastUntyped()

◆ ExportModel()

◆ ExportModelUpdate()

◆ FromModelProto()

◆ GetAttr()

◆ GetDiffHandle()

◆ GetElementName()

◆ GetElementNameUntyped()

◆ GetSliceSize()

◆ model_name()

◆ ModifiedKeysThatExist()

◆ NextElementId()

◆ NumDiffs()

◆ NumElements()

◆ primary_objective_name()

◆ SetAttr()

◆ Slice()