Entity

class Entity

An AMPL entity such as a parameter or a variable.

An entity can either represent a single instance of an AMPL algebraic entity or, if the corresponding declaration has an indexing expression, a mapping from keys to instances. In the derived classes, it has methods to access instance-level properties which can be used in case the represented entity is scalar.

To gain access to all the values in an entity (for all instances and all suffixes for that entities), use the function Entity::getValues().

The algebraic entities which currenty have an equivalent class in the API are:

• Variables (see ampl::Variable)

• Constraints (see ampl::Constraint)

• Objectives (see ampl::Objective)

• Sets (see ampl::Set)

• Parameters (see ampl::Parameter)

Public Functions

inline std::string name() const

Get the name of this entity.

inline std::string type() const

Get the type of this entity.

inline std::size_t indexarity() const

Get the indexarity of this entity (sum of the dimensions of the indexing sets).

This value indicates the arity of the Tuple to be passed to the method BasicEntity::get() in order to access an instance of this entity. See the following AMPL examples

var x;               # indexarity = 0
var y {1..2};        # indexarity = 1
var z {1..2,3..4};   # indexarity = 2
var zz {{(1, 2)}};   # indexarity = 2

Returns:

The sum of the dimensions of the indexing sets or 0 if the entity is not indexed

inline bool isScalar() const

Check whether this entity is scalar.

Equivalent to testing whether indexarity() is equal to zero.

Returns:

True if the entity is scalar (not indexed over any set)

inline std::size_t numInstances() const

Get the number of instances in this entity.

inline StringArray getIndexingSets() const

Get the AMPL string representation of the sets on which this entity is indexed.

The obtained vector can be modified without any effect to the entity.

Returns:

The string representation of the indexing sets for this entity or an empty array if the entity is scalar

inline StringArray xref() const

Get the names of all entities which depend on this one.

Returns:

An array with the names of all entities which depend on this one.

inline DataFrame getValues() const

Get the principal values of this entity as a DataFrame. The specific returned value depends on the type of entity (see list below).

For:

• Variables and Objectives it returns the suffix val

• Parameters it returns their values

• Constraints it returns the suffix dual

• Sets it returns all the of the set. Note that it does not

• apply to indexed sets. See SetInstance::getValues

Returns:

A DataFrame containing the values for all instances

inline DataFrame getValues(StringArgs suffixes) const

Get the specified suffixes value for all instances in a DataFrame.

Parameters:

suffixes – Suffixes to get

Returns:

A DataFrame containing the specified values

inline void setSuffixes(DataFrame data)

inline void setValues(DataFrame data)

Set the values of this entiy to the correponding values of a DataFrame indexed over the same sets (or a subset). This function assigns the values in the first data column of the passed dataframe to the entity the function is called from. In particular, the statement:

x.setValues(y.getValues());

is semantically equivalent to the AMPL statement:

let {s in S} x[s] := y[s];

Parameters:

data – The data to set the entity to

inline std::string toString() const

Returns a string representation of this entity (its declaration).

template<class I>
inline Entity(BasicEntity<I> other)

Constructor to allow implicit conversion.

inline Entity &operator=(const Entity &rhs)

Assignment operator.

inline Entity()

Constructor to allow the construction of arrays of entities.

Friends

friend class AMPL

friend class DataFrame

friend class EntityArgs

friend class Instance

BasicEntity

template<class InstanceClass> ampl::BasicEntity : private INHERITANCE Entity

Infrastructure class to enable the inheriting classes type-safe access to instances.

Instance access

Iterator for entities, represented by an iterator pointing to elements of type std::pair<Tuple, InstanceClass>

Methods to access the instances which are part of this Entity

inline InstanceClass get() const

Get the instance corresponding to a scalar entity.

Throws:

• runtime_error – if the entity has been deleted in the underlying AMPL interpreter

• logic_error – if the entity is not scalar

Returns:

The corresponding instance.

inline InstanceClass operator[](Tuple index) const

inline InstanceClass get(Tuple index) const

Get the instance with the specified index.

Parameters:

index – The tuple specifying the index

Throws:

• out_of_range – if an instance with the specified index does not exist

• out_of_range – if the entity has been deleted in the underlying AMPL interpreter

• ampl::UnsupportedOperationException – if the entity is scalar

Returns:

The corresponding instance

inline InstanceClass operator[](Variant v1) const

inline InstanceClass get(Variant v1) const

Get the instance with the specified index.

inline InstanceClass get(Variant v1, Variant v2) const

Get the instance with the specified index.

inline InstanceClass get(Variant v1, Variant v2, Variant v3) const

Get the instance with the specified index.

inline InstanceClass get(Variant v1, Variant v2, Variant v3, Variant v4) const

Get the instance with the specified index.

Parameters:

• v1 – The Variant specifying the first element of the indexing tuple

• v2 – The Variant specifying the second element of the indexing tuple

• v3 – The Variant specifying the third element of the indexing tuple

• v4 – The Variant specifying the fourth element of the indexing tuple

Throws:

• out_of_range – if an instance with the specified index does not exist

• runtime_error – if the entity has been deleted in the underlying AMPL interpreter

• ampl::UnsupportedOperationException – if the entity is scalar

Returns:

The corresponding instance

inline iterator begin() const

inline iterator end() const

inline iterator find(Tuple index) const

template<typename T = InstanceClass>
inline std::enable_if<is_parameter_instance<T>::value, void>::type setInstances() const

template<typename T = InstanceClass>
inline std::enable_if<!is_parameter_instance<T>::value, void>::type setInstances() const

inline double getDoubleSuffix(std::string suffix)

inline std::string getStringSuffix(std::string suffix)

inline void setSuffix(std::string suffix, double value)

inline void setSuffix(std::string suffix, std::string value)

inline explicit BasicEntity(::AMPL *ampl, std::string name)

Constructor allowing cross conversions.

Public Functions

inline StringArray getIndexingSets() const

Get the AMPL string representation of the sets on which this entity is indexed.

The obtained vector can be modified without any effect to the entity.

Returns:

The string representation of the indexing sets for this entity or an empty array if the entity is scalar

inline DataFrame getValues() const

Get the principal values of this entity as a DataFrame. The specific returned value depends on the type of entity (see list below).

For:

• Variables and Objectives it returns the suffix val

• Parameters it returns their values

• Constraints it returns the suffix dual

• Sets it returns all the of the set. Note that it does not

• apply to indexed sets. See SetInstance::getValues

Returns:

A DataFrame containing the values for all instances

inline DataFrame getValues(StringArgs suffixes) const

Get the specified suffixes value for all instances in a DataFrame.

Parameters:

suffixes – Suffixes to get

Returns:

A DataFrame containing the specified values

inline std::size_t indexarity() const

Get the indexarity of this entity (sum of the dimensions of the indexing sets).

This value indicates the arity of the Tuple to be passed to the method BasicEntity::get() in order to access an instance of this entity. See the following AMPL examples

var x;               # indexarity = 0
var y {1..2};        # indexarity = 1
var z {1..2,3..4};   # indexarity = 2
var zz {{(1, 2)}};   # indexarity = 2

Returns:

The sum of the dimensions of the indexing sets or 0 if the entity is not indexed

inline bool isScalar() const

Check whether this entity is scalar.

Equivalent to testing whether indexarity() is equal to zero.

Returns:

True if the entity is scalar (not indexed over any set)

inline std::string name() const

Get the name of this entity.

inline std::size_t numInstances() const

Get the number of instances in this entity.

inline void setValues(DataFrame data)

Set the values of this entiy to the correponding values of a DataFrame indexed over the same sets (or a subset). This function assigns the values in the first data column of the passed dataframe to the entity the function is called from. In particular, the statement:

x.setValues(y.getValues());

is semantically equivalent to the AMPL statement:

let {s in S} x[s] := y[s];

Parameters:

data – The data to set the entity to

inline std::string toString() const

Returns a string representation of this entity (its declaration).

inline StringArray xref() const

Get the names of all entities which depend on this one.

Returns:

An array with the names of all entities which depend on this one.

inline void setSuffixes(DataFrame data)

class iterator

Public Functions

inline iterator()

inline explicit iterator(typename std::map<Tuple, InstanceClass>::iterator it)

inline iterator &operator++()

inline iterator operator++(int)

inline bool operator==(const iterator &other) const

inline bool operator!=(const iterator &other) const

inline Tuple getIndex() const

inline InstanceClass getInstance() const

inline std::pair<const Tuple, InstanceClass> &operator*() const

inline std::pair<const Tuple, InstanceClass> *operator->() const

EntityArgs

class EntityArgs

Represents a list of entities, to be passed as arguments to various API functions.

Public Functions

inline EntityArgs(Entity arg0)

Constructor from entities.

Parameters:

arg0 – First entity

inline EntityArgs(Entity arg0, Entity arg1)

Constructor from entities.

Parameters:

• arg0 – First entity

• arg1 – Second entity

inline EntityArgs(Entity arg0, Entity arg1, Entity arg2)

Constructor from entities.

Parameters:

• arg0 – First entity

• arg1 – Second entity

• arg2 – Third entity

inline EntityArgs(Entity arg0, Entity arg1, Entity arg2, Entity arg3)

Constructor from entities.

Parameters:

• arg0 – First entity

• arg1 – Second entity

• arg2 – Third entity

• arg3 – Fourth entity

inline EntityArgs(Entity args[], std::size_t size)

Constructor from an array of entities.

Parameters:

• args – An array of entities

• size – Size of the array

inline const Entity *getArgs() const

Get access to the represented entities.

inline std::size_t size() const

Number of represented entities.