Entity¶

class ampl::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 AMPL::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

std::string name() const¶: Get the name of this entity.

int 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 Entity::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

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

bool isScalar() const¶

Check whether this entity is scalar.

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

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

std::size_t numInstances() const¶: Get the number of instances in this entity.

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.

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

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 members of the set. Note that it does not
apply to indexed sets. See SetInstance::getValues

Return: A DataFrame containing the values for all instances

DataFrame getValues(StringArgs suffixes) const¶

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

Return

A DataFrame containing the specified values

Parameters

suffixes -
Suffixes to get

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

std::string toString() const¶: Returns a string representation of this entity (its declaration)

template <class I>
Entity(BasicEntity<I> other)¶: Constructor to allow implicit conversion.

Friends

friend ampl::Entity::AMPL

friend ampl::Entity::DataFrame

friend ampl::Entity::EntityArgs

friend ampl::Entity::Instance

template <class InstanceClass>

class ampl::BasicEntity¶

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

Instance access

Methods to access the instances which are part of this Entity

InstanceClass get() const¶

Get the instance corresponding to a scalar entity.

Return

The corresponding instance.

Exceptions

runtime_error -
if the entity has been deleted in the underlying AMPL interpreter
logic_error -
if the entity is not scalar

InstanceClass operator[](TupleRef index) const¶

InstanceClass get(TupleRef index) const¶

Get the instance with the specified index.

Return

The corresponding instance

Parameters

index -
The tuple specifying the index

Exceptions

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
logic_error -
if the entity is scalar

InstanceClass operator[](VariantRef v1) const¶

InstanceClass get(VariantRef v1) const¶

InstanceClass get(VariantRef v1, VariantRef v2) const¶

InstanceClass get(VariantRef v1, VariantRef v2, VariantRef v3) const¶

InstanceClass get(VariantRef v1, VariantRef v2, VariantRef v3, VariantRef v4) const¶

Get the instance with the specified index.

Return

The corresponding instance

Parameters

v1 -
The VariantRef specifying the first element of the indexing tuple
v2 -
The VariantRef specifying the second element of the indexing tuple
v3 -
The VariantRef specifying the third element of the indexing tuple
v4 -
The VariantRef specifying the fourth element of the indexing tuple

Exceptions

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
logic_error -
if the entity is scalar

Public Types

typedef internal::CountedIterator<internal::EntityWrapper<InstanceClass>> iterator¶: Iterator for entities, represented by an iterator pointing to elements of type std::pair<TupleRef, InstanceClass>

Public Functions

iterator begin() const¶: Get an iterator pointing to the first instance in this entity.

iterator end() const¶: Get an iterator pointing after the last instance in this entity.

iterator find(TupleRef t) const¶

Searches the current entity for an instance with the specified index.

Return: an iterator to the wanted entity if found, otherwise an iterator to BasicEntity::end.

BasicEntity(internal::EntityBase *entity)¶: Constructor allowing cross conversions.

Private Functions

std::string name() const¶: Get the name of this entity.

int 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 Entity::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

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

bool isScalar() const¶

Check whether this entity is scalar.

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

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

std::size_t numInstances() const¶: Get the number of instances in this entity.

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.

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

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 members of the set. Note that it does not
apply to indexed sets. See SetInstance::getValues

Return: A DataFrame containing the values for all instances

DataFrame getValues(StringArgs suffixes) const¶

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

Return

A DataFrame containing the specified values

Parameters

suffixes -
Suffixes to get

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

std::string toString() const¶: Returns a string representation of this entity (its declaration)

class ampl::EntityArgs¶

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

Public Functions

EntityArgs(Entity arg0)¶

EntityArgs(Entity arg0, Entity arg1)¶

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

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

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

Constructor from an array of entities.

Parameters

args -
An array of entities
size -
Size of the array

const internal::EntityBase **getArgs() const¶: Get access to the represented entities.

std::size_t size() const¶: Number of represented entities.

Previous topic

Next topic

This Page

Entity¶