Equation#

class gamspy.Equation(container: Container, name: str | None = None, type: str | EquationType = 'regular', domain: list[Set | Alias | str] | Set | Alias | str | None = None, definition: Variable | Operation | Expression | None = None, records: Any | None = None, domain_forwarding: bool = False, description: str = '', uels_on_axes: bool = False, is_miro_output: bool = False, definition_domain: list | None = None)[source]#

Bases: Equation, Operable, Symbol

Represents an Equation symbol in GAMS. https://www.gams.com/latest/docs/UG_Equations.html

Parameters:
containerContainer

Container of the variable.

namestr, optional

Name of the equation. Name is autogenerated by default.

typestr

Type of the equation. “regular” by default.

domainlist[Set | Alias | str] | Set | Alias | str, optional

Domain of the variable.

definition: Expression, optional

Definition of the equation.

recordsAny, optional

Records of the equation.

domain_forwardingbool, optional

Whether the equation forwards the domain. See: https://gams.com/latest/docs/UG_SetDefinition.html#UG_SetDefinition_ImplicitSetDefinition

descriptionstr, optional

Description of the equation.

uels_on_axes: bool

Assume that symbol domain information is contained in the axes of the given records.

definition_domain: list, optional

Definiton domain of the equation.

is_miro_outputbool

Whether the symbol is a GAMS MIRO output symbol. See: https://gams.com/miro/tutorial.html

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1','i2'])
>>> a = gp.Parameter(m, "a", [i], records=[['i1',1],['i2',2]])
>>> v = gp.Variable(m, "v", domain=[i])
>>> e = gp.Equation(m, "e", domain=[i])
>>> e[i] = a[i] <= v[i]
Attributes:
container

Container of the symbol

default_records

Default records of an equation

description

Description of the symbol

dimension

The dimension of symbol

domain

List of domains given either as string (* for universe set) or as reference to the Set/Alias object

domain_forwarding

A boolean indicating whether domain forwarding is enabled

domain_labels

The column headings for the records DataFrame

domain_names

String version of domain names

domain_type

State of the domain links

infeas

Infeasability

is_scalar

Returns True if the len(self.domain) = 0

l

Level

lo

Lower bound

m

Marginal

modified

Flag that identifies if the symbol has been modified

name

Name of symbol

number_records

Number of records

range

Range

records

Records of the Equation

scale

Scale

shape

Returns a tuple describing the array dimensions if records were converted with .toDense()

slack

Slack

slacklo

Slack lower bound

slackup

Slack upper bound

stage

Stage

summary

Summary of the symbol

type

The type of equation; 3.

up

Upper bound

Methods

compute_infeasibilities()

Computes infeasabilities of the equation

countEps([columns])

Counts total number of SpecialValues.EPS across columns

countNA([columns])

Counts total number of SpecialValues.NA across columns

countNegInf([columns])

Counts total number of SpecialValues.NegInf across columns

countPosInf([columns])

Counts total number of SpecialValues.PosInf across columns

countUndef([columns])

Counts total number of SpecialValues.Undef across columns

dropDefaults()

Drop records that are set to GAMS default records (check .default_records property for values)

dropEps()

Drop records from the symbol that are GAMS EPS (zero 0.0 records will be retained)

dropMissing()

Drop records from the symbol that are NaN (includes both NA and Undef special values)

dropNA()

Drop records from the symbol that are GAMS NA

dropUndef()

Drop records from the symbol that are GAMS Undef

equals(other[, columns, check_uels, ...])

Used to compare the symbol to another symbol

findEps([column])

Find positions of SpecialValues.EPS in value column

findNA([column])

Find positions of SpecialValues.NA in value column

findNegInf([column])

Find positions of SpecialValues.NegInf in value column

findPosInf([column])

Find positions of SpecialValues.PosInf in value column

findSpecialValues(values[, column])

Find positions of specified values in records columns

findUndef([column])

Find positions of SpecialValues.Undef in value column

gamsRepr()

Representation of this Equation in GAMS language.

generateRecords([density, func, seed])

Convenience method to set standard pandas.DataFrame formatted records given domain set information.

getDeclaration()

Declaration of the Equation in GAMS

getDefinition()

Definition of the Equation in GAMS

getMaxAbsValue([columns])

Get the maximum absolute value across chosen columns

getMaxValue([columns])

Get the maximum value across chosen columns

getMeanValue([columns])

Get the mean value across chosen columns

getMinValue([columns])

Get the minimum value across chosen columns

getSparsity()

Get the sparsity of the symbol w.r.t the cardinality

isValid([verbose, force])

Checks if the symbol is in a valid format

pivot([index, columns, value, fill_value])

Convenience function to pivot records into a new shape (only symbols with >1D can be pivoted)

setRecords(records[, uels_on_axes])

Main convenience method to set standard pandas.DataFrame formatted records

toDense([column])

Convert column to a dense numpy.array format

toDict([columns, orient])

Convenience method to return symbol records as a Python dictionary

toList([columns])

Convenience method to return symbol records as a Python list

toSparseCoo([column])

Convert column to a sparse COOrdinate numpy.array format

toValue([column])

Convenience method to return symbol records as a Python float.

whereMax([column])

Find the domain entry of records with a maximum value (return first instance only)

whereMaxAbs([column])

Find the domain entry of records with a maximum absolute value (return first instance only)

whereMin([column])

Find the domain entry of records with a minimum value (return first instance only)

property description#

Description of the symbol

property modified#

Flag that identifies if the symbol has been modified

property l#

Level

Returns:
ImplicitParameter
property m#

Marginal

Returns:
ImplicitParameter
property lo#

Lower bound

Returns:
ImplicitParameter
property up#

Upper bound

Returns:
ImplicitParameter
property scale#

Scale

Returns:
ImplicitParameter
property stage#

Stage

Returns:
ImplicitParameter
property range#

Range

Returns:
ImplicitParameter
property slacklo#

Slack lower bound

Returns:
ImplicitParameter
property slackup#

Slack upper bound

Returns:
ImplicitParameter
property slack#

Slack

Returns:
ImplicitParameter
property infeas#

Infeasability

Returns:
ImplicitParameter
compute_infeasibilities() DataFrame[source]#

Computes infeasabilities of the equation

Returns:
pd.DataFrame
property container#

Container of the symbol

countEps(columns: str | List[str] | None = None) int#

Counts total number of SpecialValues.EPS across columns

Parameters:
columnsstr | List[str], optional

Columns to count special values in, by default None

Returns:
Total number of SpecialValues.EPS across columns
countNA(columns: str | List[str] | None = None) int#

Counts total number of SpecialValues.NA across columns

Parameters:
columnsstr | List[str], optional

Columns to count special values in, by default None

Returns:
Total number of SpecialValues.NA across columns
countNegInf(columns: str | List[str] | None = None) int#

Counts total number of SpecialValues.NegInf across columns

Parameters:
columnsstr | List[str], optional

Columns to count special values in, by default None

Returns:
Total number of SpecialValues.NegInf across columns
countPosInf(columns: str | List[str] | None = None) int#

Counts total number of SpecialValues.PosInf across columns

Parameters:
columnsstr | List[str], optional

Columns to count special values in, by default None

Returns:
Total number of SpecialValues.PosInf across columns
countUndef(columns: str | List[str] | None = None) int#

Counts total number of SpecialValues.Undef across columns

Parameters:
columnsstr | List[str], optional

Columns to count special values in, by default None

Returns:
Total number of SpecialValues.Undef across columns
property default_records#

Default records of an equation

property dimension#

The dimension of symbol

property domain#

List of domains given either as string (* for universe set) or as reference to the Set/Alias object

property domain_forwarding#

A boolean indicating whether domain forwarding is enabled

property domain_labels#

The column headings for the records DataFrame

property domain_names#

String version of domain names

property domain_type#

State of the domain links

dropDefaults() None#

Drop records that are set to GAMS default records (check .default_records property for values)

dropEps() None#

Drop records from the symbol that are GAMS EPS (zero 0.0 records will be retained)

dropMissing() None#

Drop records from the symbol that are NaN (includes both NA and Undef special values)

dropNA() None#

Drop records from the symbol that are GAMS NA

dropUndef() None#

Drop records from the symbol that are GAMS Undef

equals(other: Variable, columns: str = None, check_uels: bool = True, check_meta_data: bool = True, rtol: int | float | None = None, atol: int | float | None = None, verbose: bool = False) bool#

Used to compare the symbol to another symbol

Parameters:
otherVariable

_description_

columnsstr, optional

allows the user to numerically compare only specified variable attributes, by default None; compare all

check_uelsbool, optional

If True, check both used and unused UELs and confirm same order, otherwise only check used UELs in data and do not check UEL order. by default True

check_meta_databool, optional

If True, check that symbol name and description are the same, otherwise skip. by default True

rtolint | float, optional

relative tolerance, by default None

atolint | float, optional

absolute tolerance, by default None

verbosebool, optional

If True, will return an exception from the asserter describing the nature of the difference. by default False

Returns:
bool

True if symbols are equal, False otherwise

findEps(column: str | None = None) DataFrame#

Find positions of SpecialValues.EPS in value column

Parameters:
columnstr, optional

Column to find the special values in, by default None

Returns:
pd.DataFrame

Dataframe containing special values

findNA(column: str | None = None) DataFrame#

Find positions of SpecialValues.NA in value column

Parameters:
columnstr, optional

Column to find the special values in, by default None

Returns:
pd.DataFrame

Dataframe containing special values

findNegInf(column: str | None = None) DataFrame#

Find positions of SpecialValues.NegInf in value column

Parameters:
columnstr, optional

Column to find the special values in, by default None

Returns:
pd.DataFrame

Dataframe containing special values

findPosInf(column: str | None = None) DataFrame#

Find positions of SpecialValues.PosInf in value column

Parameters:
columnstr, optional

Column to find the special values in, by default None

Returns:
pd.DataFrame

Dataframe containing special values

findSpecialValues(values: float | List[float], column: str | None = None) DataFrame#

Find positions of specified values in records columns

Parameters:
valuesfloat | List[float]

Values to look for

columnstr, optional

Column to find the special values in, by default None

Returns:
pd.DataFrame

Dataframe containing special values

findUndef(column: str | None = None) DataFrame#

Find positions of SpecialValues.Undef in value column

Parameters:
columnstr, optional

Column to find the special values in, by default None

Returns:
pd.DataFrame

Dataframe containing special values

generateRecords(density: int | float | list | None = None, func: Callable | None = None, seed: int | None = None) None#

Convenience method to set standard pandas.DataFrame formatted records given domain set information. Will generate records with the Cartesian product of all domain sets.

Parameters:
densityint | float | list, optional

Takes any value on the interval [0,1]. If density is <1 then randomly selected records will be removed. density will accept a list of length dimension – allows users to specify a density per symbol dimension, by default None

funcCallable, optional

Functions to generate the records, by default None; numpy.random.uniform(0,1)

seedint, optional

Random number state can be set with seed argument, by default None

getMaxAbsValue(columns: str | List[str] | None = None) float#

Get the maximum absolute value across chosen columns

Parameters:
columnsstr | List[str], optional

Columns to find maximum absolute values in, by default None

Returns:
float

Maximum absolute value

getMaxValue(columns: str | List[str] | None = None) float#

Get the maximum value across chosen columns

Parameters:
columnsstr | List[str], optional

Columns to find maximum values in, by default None

Returns:
float

Maximum value

getMeanValue(columns: str | List[str] | None = None) float#

Get the mean value across chosen columns

Parameters:
columnsstr | List[str], optional

Columns to find mean values in, by default None

Returns:
float

Mean value

getMinValue(columns: str | List[str] | None = None) float#

Get the minimum value across chosen columns

Parameters:
columnsstr | List[str], optional

Columns to find minimum values in, by default None

Returns:
float

Minimum value

getSparsity() float#

Get the sparsity of the symbol w.r.t the cardinality

Returns:
float

Sparsity of the symbol w.r.t the cardinality

isValid(verbose: bool = False, force: bool = False) bool#

Checks if the symbol is in a valid format

Parameters:
verbosebool, optional

Throw exceptions if verbose=True, by default False

forcebool, optional

Recheck a symbol if force=True, by default False

Returns:
bool

True if a symbol is in valid format, False otherwise (throws exceptions if verbose=True)

property is_scalar: bool#

Returns True if the len(self.domain) = 0

Returns:
bool

True if the len(self.domain) = 0

property name#

Name of symbol

property number_records#

Number of records

pivot(index: str | list | None = None, columns: str | list | None = None, value: str | None = None, fill_value: int | float | str | None = None) DataFrame#

Convenience function to pivot records into a new shape (only symbols with >1D can be pivoted)

Parameters:
indexstr | list, optional

If index is None then it is set to dimensions [0..dimension-1], by default None

columnsstr | list, optional

If columns is None then it is set to the last dimension, by default None

valuestr, optional

If value is None then the level values will be pivoted, by default None

fill_valueint | float | str, optional

Missing values in the pivot will take the value provided by fill_value, by default None

Returns:
DataFrame

Pivoted records dataframe

property shape: tuple#

Returns a tuple describing the array dimensions if records were converted with .toDense()

Returns:
tuple

A tuple describing the records dimensions

property summary#

Summary of the symbol

toDense(column: str = 'level') ndarray | None#

Convert column to a dense numpy.array format

Parameters:
columnstr, optional

The column to convert, by default “level”

Returns:
np.ndarray, optional

A column to a dense numpy.array format

toDict(columns: str | None = None, orient: str | None = None) dict#

Convenience method to return symbol records as a Python dictionary

Parameters:
columnsstr, optional

Controls which attributes to include in the dict, by default None

orientstr, optional

Orient can take values natural or columns and will control the shape of the dict. Must use orient=”columns” if attempting to set symbol records with setRecords, by default None

Returns:
dict

Records as a Python dictionary

toList(columns: str | None = None) list#

Convenience method to return symbol records as a Python list

Parameters:
columnsstr, optional

Controls which attributes to include in the list, by default None

Returns:
list

Records as a Python list

toSparseCoo(column: str = 'level') coo_matrix | None#

Convert column to a sparse COOrdinate numpy.array format

Parameters:
columnstr, optional

The column to convert, by default “level”

Returns:
coo_matrix, optional

A column in coo_matrix format

toValue(column: str | None = None) float#

Convenience method to return symbol records as a Python float. Only possible with scalar symbols

Parameters:
columnstr, optional

Attribute can be specified with column argument, by default None

Returns:
float

Value of the symbol

whereMax(column: str | None = None) List[str]#

Find the domain entry of records with a maximum value (return first instance only)

Parameters:
columnstr, optional

Columns to find maximum values in, by default None

Returns:
List[str]

List of symbol names where maximum values exist

whereMaxAbs(column: str | None = None) List[str]#

Find the domain entry of records with a maximum absolute value (return first instance only)

Parameters:
columnstr, optional

Columns to find maximum absolute values in, by default None

Returns:
List[str]

List of symbol names where maximum absolute values exist

whereMin(column: str | None = None) List[str]#

Find the domain entry of records with a minimum value (return first instance only)

Parameters:
columnstr, optional

Columns to find minimum values in, by default None

Returns:
List[str]

List of symbol names where minimum values exist

property records#

Records of the Equation

Returns:
DataFrame
setRecords(records: Any, uels_on_axes: bool = False) None[source]#

Main convenience method to set standard pandas.DataFrame formatted records

Parameters:
recordsAny

Records to set for the symbol

uels_on_axesbool, optional

If True, setRecords will assume that all domain information is contained in the axes of the pandas object – data will be flattened (if necessary), by default False

property type#

The type of equation; 3. ‘regular’ – equal, less than or greater than 4. ‘nonbinding’, ‘N’, or ‘=N=’ – nonbinding relationship 5. ‘cone’, ‘C’, or ‘=C=’ – cone equation 6. ‘external’, ‘X’, or ‘=X=’ – external equation 7. ‘boolean’, ‘B’, or ‘=B=’ – boolean equation

Returns:
str

The type of equation

gamsRepr() str[source]#

Representation of this Equation in GAMS language.

Returns:
str
getDeclaration() str[source]#

Declaration of the Equation in GAMS

Returns:
str

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1','i2'])
>>> a = gp.Parameter(m, "a", [i], records=[['i1',1],['i2',2]])
>>> v = gp.Variable(m, "v", domain=[i])
>>> e = gp.Equation(m, "e", domain=[i])
>>> e.getDeclaration()
'Equation e(i);'
getDefinition() str[source]#

Definition of the Equation in GAMS

Returns:
str

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1','i2'])
>>> a = gp.Parameter(m, "a", [i], records=[['i1',1],['i2',2]])
>>> v = gp.Variable(m, "v", domain=[i])
>>> e = gp.Equation(m, "e", domain=[i])
>>> e[i] = a[i] <= v[i]
>>> e.getDefinition()
'e(i) .. a(i) =l= v(i);'
class gamspy.EquationType(value)[source]#

Bases: Enum

An enumeration.

REGULAR = 'REGULAR'#
NONBINDING = 'NONBINDING'#
EXTERNAL = 'EXTERNAL'#
CONE = 'CONE'#
BOOLEAN = 'BOOLEAN'#
classmethod values()[source]#

Convenience function to return all values of enum