Parameter#

class gamspy.Parameter(container: Container | None = None, name: str | None = None, domain: DomainType | None = None, records: ParameterRecordsType | None = None, domain_forwarding: bool | list[bool] = False, description: str = '', uels_on_axes: bool = False, is_miro_input: bool = False, is_miro_output: bool = False, is_miro_table: bool = False)[source]#

Bases: Operable, RecordSymbol

Represents a Parameter symbol in GAMS.

Parameters are used to hold data (scalars, vectors, or multi-dimensional arrays). See https://gamspy.readthedocs.io/en/latest/user/basics/parameter.html

Parameters:

containerContainer: The Container object that this parameter belongs to.
namestr, optional: Name of the parameter. If not provided, a unique name is generated automatically.
domainDomainType, optional: The domain of the parameter. Can be a list of Sets/Aliases, a single Set/Alias, or strings representing set names. Use “*” for the universe set. Default is [] (scalar).
recordsSequence | np.ndarray | int | float | pd.DataFrame | pd.Series, optional: Initial values to populate the parameter. Can be a scalar, a list, a numpy array, or a pandas DataFrame.
domain_forwardingbool | list[bool], optional: If True, adding records to this parameter will implicitly add new elements to the domain sets (if they are dynamic). Default is False.
descriptionstr, optional: A human-readable description of the parameter.
uels_on_axesbool, optional: If True, implies that the Unique Element Labels (UELs) for the domain are contained in the axes (index/columns) of the provided records object (e.g., pandas DataFrame). Default is False.
is_miro_inputbool, optional: If True, flags this parameter as an input symbol for GAMS MIRO. Default is False.
is_miro_outputbool, optional: If True, flags this parameter as an output symbol for GAMS MIRO. Default is False.
is_miro_tablebool, optional: If True, flags this parameter as a table symbol for GAMS MIRO. Default is False.

Attributes:

container: Container of the symbol
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_labels: The column headings for the records DataFrame
domain_names: String version of domain names
domain_type: State of the domain links
is_scalar: Returns True if the len(self.domain) = 0
number_records: Number of records
records: Returns the records (data) of the Parameter as a DataFrame.
shape
summary
synchronize: Synchronization state of the symbol.

Methods

`equals`(other[, check_meta_data, rtol, atol])	Used to compare the symbol to another symbol
`gamsRepr`()	Returns the string representation of this Parameter in the GAMS language.
`generateRecords`([density, func, seed])	Generates records with the Cartesian product of all domain sets.
`getAssignment`()	Returns the latest GAMS assignment statement for this Parameter.
`getDeclaration`()	Returns the GAMS declaration statement for this Parameter.
`getSparsity`()	Calculates the sparsity of the symbol's records.
`pivot`([index, columns, fill_value])	Convenience function to pivot records into a new shape (only symbols with >1D can be pivoted).
`product`(*indices)	Equivalent to Product(indices, obj[obj.domain]).
`sand`(*indices)	Equivalent to Sand(indices, obj[obj.domain]).
`setRecords`(records[, uels_on_axes])	Sets the records (data) of the Parameter.
`smax`(*indices)	Equivalent to Smax(indices, obj[obj.domain]).
`smin`(*indices)	Equivalent to Smin(indices, obj[obj.domain]).
`sor`(*indices)	Equivalent to Sor(indices, obj[obj.domain]).
`sum`(*indices)	Equivalent to Sum(indices, obj[obj.domain]).
`toDense`()	Convert symbol records to a dense numpy.array format
`toDict`([orient])	Converts the records of a non-scalar Parameter to a Python dictionary.
`toList`()	Converts the records of the Parameter to a Python list.
`toSparseCoo`()	Converts the parameter records to a SciPy sparse COOrdinate format (coo_matrix).
`toValue`()	Returns the numerical value of a scalar Parameter.

countEps
countNA
countNegInf
countPosInf
countUndef
findEps
findNA
findNegInf
findPosInf
findSpecialValues
findUndef
getMaxAbsValue
getMaxValue
getMeanValue
getMinValue
whereMax
whereMaxAbs
whereMin

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1', 'i2'])
>>> a = gp.Parameter(m, "a", domain=[i], records=[['i1', 1], ['i2', 2]], description="Input data")

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

countNA(columns: str | list[str] | None = None) → int#

countNegInf(columns: str | list[str] | None = None) → int#

countPosInf(columns: str | list[str] | None = None) → int#

countUndef(columns: str | list[str] | None = None) → int#

equals(other: Parameter, check_meta_data: bool = True, rtol: int | float | None = None, atol: int | float | None = None) → bool[source]#

Used to compare the symbol to another symbol

Parameters:

otherParameter: Other Symbol to compare with
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

Returns:

bool: True if symbols are equal, False otherwise

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> p1 = gp.Parameter(m, name="p1", records=10.0001)
>>> p2 = gp.Parameter(m, name="p2", records=10.0002)
>>> p1.equals(p2, check_meta_data=False, atol=1e-3)
True

findEps(column: str | None = None) → pd.DataFrame | None#

findNA(column: str | None = None) → pd.DataFrame | None#

findNegInf(column: str | None = None) → pd.DataFrame | None#

findPosInf(column: str | None = None) → pd.DataFrame | None#

findSpecialValues(values: float | list[float], column: str | None = None) → pd.DataFrame | None#

findUndef(column: str | None = None) → pd.DataFrame | None#

gamsRepr() → str[source]#

Returns the string representation of this Parameter in the GAMS language.

The representation includes the parameter name and its domain (e.g., ‘p(i, j)’).

Returns:

str: The GAMS string representation.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i", records=['i1','i2'])
>>> d = gp.Parameter(m, "d", domain=i)
>>> d.gamsRepr()
'd(i)'

Generates 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 which 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

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["A", "B"])
>>> p = gp.Parameter(m, name="p", domain=[i])
>>> p.generateRecords(seed=42)

getAssignment() → str[source]#

Returns the latest GAMS assignment statement for this Parameter.

This string represents the last assignment operation performed on the parameter (e.g., ‘p(i) = 5;’).

Returns:

str: The GAMS assignment statement.

Raises:

ValidationError: If the parameter has not been assigned yet.

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]])
>>> a[i] = a[i] * 5
>>> a.getAssignment()
'a(i) = a(i) * 5;'

getDeclaration() → str[source]#

Returns the GAMS declaration statement for this Parameter.

This string is used internally to declare the parameter in the GAMS execution environment.

Returns:

str: The GAMS declaration statement (e.g., ‘Parameter p(i);’).

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]])
>>> a.getDeclaration()
'Parameter a(i);'

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

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

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

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

getSparsity() → float#

Calculates the sparsity of the symbol’s records.

Sparsity is defined as 1 - (number_of_records / maximum_possible_records), where the maximum possible records is the product of the number of records in each of the symbol’s domain sets. A sparsity of 1.0 means the symbol has no records (completely empty), while 0.0 means the symbol is fully dense.

Returns:

float: The sparsity of the symbol (between 0.0 and 1.0). Returns float(“nan”) if the symbol is a scalar, has a relaxed domain (e.g., [“*”]), or if any of its domain sets have no records.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["A", "B"])
>>> j = gp.Set(m, name="j", records=["X", "Y", "Z"])
>>> p = gp.Parameter(m, name="p", domain=[i, j], records=[("A", "X", 10)])
>>> p.getSparsity()
0.8333333333333334

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
fill_valueint | float | str, optional: Missing values in the pivot will take the value provided by fill_value, by default None

Returns:

pd.DataFrame: The pivoted DataFrame representing the parameter records.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["A", "B"])
>>> j = gp.Set(m, name="j", records=["X", "Y"])
>>> p = gp.Parameter(m, name="p", domain=[i, j], records=[("A", "X", 10), ("B", "Y", 20)])
>>> df = p.pivot()

product(*indices: Set | Alias) → Product#

Equivalent to Product(indices, obj[obj.domain]). For example:

v = Variable(m, domain=[i, j, k]) v.product() is equivalent to Product((i,j), v[i, j, k]) v.product(i) is equivalent to Product(i, v[i, j, k]) v.product(i, j) is equivalent to Product((i, j), v[i, j, k])

Returns:

Product: Generated Product operation.

Raises:

ValidationError: In case the symbol is scalar.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
>>> j = gp.Set(m, "j")
>>> x = gp.Parameter(m, "x", domain=[i, j])
>>> y = gp.Parameter(m, "y")
>>> x.product().gamsRepr()
'prod((i,j),x(i,j))'
>>> gp.Product((i, j), x[i, j]).gamsRepr()
'prod((i,j),x(i,j))'

sand(*indices: Set | Alias) → Sand#

Equivalent to Sand(indices, obj[obj.domain]). For example:

v = Variable(m, domain=[i, j, k]) v.sand() is equivalent to Sand((i,j), v[i, j, k]) v.sand(i) is equivalent to Sand(i, v[i, j, k]) v.sand(i, j) is equivalent to Sand((i, j), v[i, j, k])

Returns:

Sand: Generated Sand operation.

Raises:

ValidationError: In case the symbol is scalar.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
>>> j = gp.Set(m, "j")
>>> x = gp.Parameter(m, "x", domain=[i, j])
>>> y = gp.Parameter(m, "y")
>>> x.sand().gamsRepr()
'sand((i,j),x(i,j))'
>>> gp.Sand((i, j), x[i, j]).gamsRepr()
'sand((i,j),x(i,j))'

setRecords(records: ParameterRecordsType | None, uels_on_axes: bool = False) → None[source]#

Sets the records (data) of the Parameter.

This is a convenience method to load data into the parameter. It handles various input formats like scalars, lists, numpy arrays, and pandas DataFrames. If uels_on_axes=True, it assumes that all domain information is contained in the axes (index/columns) of the pandas object, and the data will be flattened if necessary.

Parameters:

The data to load. Common formats:

Scalar: 10.5
List of tuples/lists: [[‘i1’, 1], [‘i2’, 2]]
numpy array: np.array([1, 2])
pandas DataFrame

uels_on_axesbool, optional

If True, assumes domain elements are in the axes of the DataFrame. Default is False.

Examples

>>> import gamspy as gp
>>> import numpy as np
>>> m = gp.Container()
>>> i = gp.Set(m, name="i")
>>> i.setRecords(["seattle", "san-diego"])
>>> i.toList()
['seattle', 'san-diego']

smax(*indices: Set | Alias) → Smax#

Equivalent to Smax(indices, obj[obj.domain]). For example:

v = Variable(m, domain=[i, j, k]) v.smax() is equivalent to Smax((i,j), v[i, j, k]) v.smax(i) is equivalent to Smax(i, v[i, j, k]) v.smax(i, j) is equivalent to Smax((i, j), v[i, j, k])

Returns:

Smax: Generated Smax operation.

Raises:

ValidationError: In case the symbol is scalar.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
>>> j = gp.Set(m, "j")
>>> x = gp.Parameter(m, "x", domain=[i, j])
>>> y = gp.Parameter(m, "y")
>>> x.smax().gamsRepr()
'smax((i,j),x(i,j))'
>>> gp.Smax((i, j), x[i, j]).gamsRepr()
'smax((i,j),x(i,j))'

smin(*indices: Set | Alias) → Smin#

Equivalent to Smin(indices, obj[obj.domain]). For example:

v = Variable(m, domain=[i, j, k]) v.smin() is equivalent to Smin((i,j), v[i, j, k]) v.smin(i) is equivalent to Smin(i, v[i, j, k]) v.smin(i, j) is equivalent to Smin((i, j), v[i, j, k])

Returns:

Smin: Generated Smin operation.

Raises:

ValidationError: In case the symbol is scalar.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
>>> j = gp.Set(m, "j")
>>> x = gp.Parameter(m, "x", domain=[i, j])
>>> y = gp.Parameter(m, "y")
>>> x.smin().gamsRepr()
'smin((i,j),x(i,j))'
>>> gp.Smin((i, j), x[i, j]).gamsRepr()
'smin((i,j),x(i,j))'

sor(*indices: Set | Alias) → Sor#

Equivalent to Sor(indices, obj[obj.domain]). For example:

v = Variable(m, domain=[i, j, k]) v.sor() is equivalent to Sor((i,j), v[i, j, k]) v.sor(i) is equivalent to Sor(i, v[i, j, k]) v.sor(i, j) is equivalent to Sor((i, j), v[i, j, k])

Returns:

Sor: Generated Sor operation.

Raises:

ValidationError: In case the symbol is scalar.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
>>> j = gp.Set(m, "j")
>>> x = gp.Parameter(m, "x", domain=[i, j])
>>> y = gp.Parameter(m, "y")
>>> x.sor().gamsRepr()
'sor((i,j),x(i,j))'
>>> gp.Sor((i, j), x[i, j]).gamsRepr()
'sor((i,j),x(i,j))'

sum(*indices: Set | Alias) → Sum#

Equivalent to Sum(indices, obj[obj.domain]). For example:

v = Variable(m, domain=[i, j, k]) v.sum() is equivalent to Sum((i,j), v[i, j, k]) v.sum(i) is equivalent to Sum(i, v[i, j, k]) v.sum(i, j) is equivalent to Sum((i, j), v[i, j, k])

Returns:

Sum: Generated Sum operation.

Raises:

ValidationError: In case the symbol is scalar.

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> i = gp.Set(m, "i")
>>> j = gp.Set(m, "j")
>>> x = gp.Parameter(m, "x", domain=[i, j])
>>> y = gp.Parameter(m, "y")
>>> x.sum().gamsRepr()
'sum((i,j),x(i,j))'
>>> gp.Sum((i, j), x[i, j]).gamsRepr()
'sum((i,j),x(i,j))'

toDense() → np.ndarray | None[source]#

Convert symbol records to a dense numpy.array format

Returns:

ndarray | None: A numpy array with symbol records, None if no records were assigned

Examples

>>> import numpy as np
>>> import gamspy as gp
>>> m = gp.Container()
>>> j = gp.Set(m, "j", records=["new-york", "chicago", "topeka"])
>>> s = gp.Parameter(m, "s", [j], records=np.array([3,4,5]))
>>> print(s.toDense())
[3. 4. 5.]

toDict(orient: str | None = None) → dict | None[source]#

Converts the records of a non-scalar Parameter to a Python dictionary.

Parameters:

orientstr | None, optional

The format of the dictionary. Options are: - “natural” (default): Maps domain elements to values (e.g., {‘A’: 10.0}).

For multi-dimensional parameters, keys are tuples (e.g., {(A, X): 10.0}).

“columns”: Returns a dictionary of columns (e.g., {‘i’: {0: ‘A’}, ‘value’: {0: 10.0}}).

Returns:

dict | None: A dictionary containing the parameter’s data, or None if there are no records.

Raises:

TypeError: If the parameter is a scalar.

Examples

>>> import gamspy as gp
>>> import numpy as np
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego"])
>>> p = gp.Parameter(m, name="p", domain=[i], records=np.array([10.0, 20.0]))
>>> p.toDict()
{'seattle': 10.0, 'san-diego': 20.0}

toList() → list[source]#

Converts the records of the Parameter to a Python list.

Returns:

list | None: A list containing the parameter’s data. For scalars, it returns a list with a single numerical value. For multi-dimensional parameters, it returns a list of tuples where the last element of each tuple is the value. Returns an empty list if there are no records.

Examples

>>> import gamspy as gp
>>> import numpy as np
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego"])
>>> d = gp.Parameter(m, name="d", domain=[i], records=np.array([10, 25]))
>>> d.toList()
[('seattle', 10.0), ('san-diego', 25.0)]

toSparseCoo() → coo_matrix | None[source]#

Converts the parameter records to a SciPy sparse COOrdinate format (coo_matrix).

This method is only available for parameters with 2 or fewer dimensions. For scalar parameters (0D), it returns a 1x1 matrix. For 1D parameters, it returns a 1xN matrix. For 2D parameters, it returns an MxN matrix.

Returns:

coo_matrix | None: A SciPy sparse COO matrix containing the parameter values. Returns None if there are no records.

Raises:

ValueError: If the parameter has a dimension greater than 2.

Examples

>>> import gamspy as gp
>>> import numpy as np
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["A", "B"])
>>> j = gp.Set(m, name="j", records=["X", "Y"])
>>> p = gp.Parameter(m, name="p", domain=[i, j])
>>> p.setRecords(np.array([[1, 0], [0, 2]]))
>>> sparse_mat = p.toSparseCoo()  # doctest +SKIP

toValue() → float[source]#

Returns the numerical value of a scalar Parameter.

Returns:

float | None: The floating-point value of the scalar parameter.

Raises:

TypeError: If the parameter is not a scalar (dimension > 0).

Examples

>>> import gamspy as gp
>>> m = gp.Container()
>>> p = gp.Parameter(m, name="p", records=42.5)
>>> p.toValue()
np.float64(42.5)

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

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

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

property container: Container#: Container of the symbol

property description: str#: Description of the symbol

property dimension: int#: The dimension of symbol

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

property domain_labels: list[str]#: The column headings for the records DataFrame

property domain_names: list[str]#: String version of domain names

property domain_type#: State of the domain links

property is_scalar: bool#

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

Returns:

bool: True if the len(self.domain) = 0

property number_records: int#: Number of records

property records: DataFrame | None#

Returns the records (data) of the Parameter as a DataFrame.

Returns:

pd.DataFrame | None: The dataframe containing the parameter’s data.

Examples

>>> import gamspy as gp
>>> import numpy as np
>>> m = gp.Container()
>>> i = gp.Set(m, name="i", records=["seattle", "san-diego"])
>>> d = gp.Parameter(m, name="d", domain=[i])
>>> d.setRecords(np.array([10, 25]))
>>> d.toList()
[('seattle', 10.0), ('san-diego', 25.0)]

property shape: tuple#: !! processed by numpydoc !!

property summary: dict#: !! processed by numpydoc !!

property synchronize: bool#

Synchronization state of the symbol. If True, the symbol data will be communicated with GAMS. Otherwise, GAMS state will not be updated.

Returns:

bool