GAMS numpy is a tool that can rapidly read and write data between Numpy arrays and GAMS objects (GDX files as well as other in-memory objects). GAMS numpy relies on power calls (written in C) to improve performance. Since the GAMS numpy package is primarily meant for internal use in other GAMS Python packages, it is recommended that users consider the use of GAMS transfer or the GamsDatabase class of the Control API first.

Recommended Import

Users can access the GAMS numpy sub-module with either of the following (equivalent) import statements once the GAMS API has been installed:

>>> import gams.numpy as gnp

>>> from gams import numpy as gnp

Gams2Numpy Class

The main object class within GAMS numpy is called Gams2Numpy. The Gams2Numpy class which enables the reading and writing of symbols from/to various GAMS data endpoints (i.e., GDX files, GMD objects, etc.). The object constructor as well as its methods will be detailed in the following sections:

Constructor

Constructor Arguments

Argument	Type	Description	Required	Default
`system_directory`	`str`	Path to GAMS system directory	No	If `system_directory=None`, then Gams2Numpy attempts to find the GAMS installation by creating a `GamsWorkspace` object and loading the `system_directory` attribute.

Creating a Gams2Numpy object is a simple matter of initialization. For example:

import gams.numpy as gnp
 
gams2np = gnp.Gams2Numpy()

Properties

Property	Description	Type	Special Setter Behavior
`system_directory`	Path to GAMS system directory	`str`	-

Methods

Method	Description	Arguments/Defaults	Returns
`gdxGetUelList`	Retrieves the list of UELs from `gdx`	`gdx` (GDX handle created with `gams.core.gdx.new_gdxHandle_tp` or `str` GDX file name)	`list`
`gdxReadSymbolRaw`	Reads symbol data from GDX into a `numpy.array` using integers for keys	`gdx` (GDX handle created with `gams.core.gdx.new_gdxHandle_tp` or `str` GDX file name) `symName` (`str` name of the symbol to be read)	`numpy.array`
`gdxReadSymbolStr`	Reads symbol data from GDX into a `numpy.array` using `str` for keys. Argument `uelList` accepts the list of UELs to be used for the internal mapping (typically this is retrieved with `gdxGetUelList`). Supplying this parameter can increase performance when reading multiple symbols from the same GDX file since the UEL list creation has to be performed only once.	`gdx` (GDX handle created with `gams.core.gdx.new_gdxHandle_tp` or `str` GDX file name) `symName` (`str` name of the symbol to be read) `uelList=None` (	`numpy.array`
`gdxWriteSymbolRaw`	Creates a GDX symbol and fills it with the data from the provided `numpy.array` (`int` as domains). Symbols are defined with GAMS syntax. Where `symName` is the name of the symbol to be created, `explText` is the symbol explanatory text, `dim` is the dimension of the symbol, `symType` is the type of the symbol, `subType` is the sybType of the symbol, `arr` is the 2D `numpy.array` with the symbol records, `domains` is the list of domains to be used for the symbol (optional), and `relaxedType` will automatically convert the columns of the `numpy.array` into the required data types if possible.	`gdx` (GDX handle created with `gams.core.gdx.new_gdxHandle_tp` or `str` GDX file name) `symName` (`str`) `explText` (`str`) `dim` (`int`) `symType` (`int`) `subType` (`int`) `arr` (`numpy.array`) `domains=None` (`list` of `str`) `relaxedType=False` (`bool`)	`None`
`gdxWriteSymbolStr`	Creates a GDX symbol and fills it with the data from the provided `numpy.array` (`str` as domains). Symbols are defined with GAMS syntax. Where `symName` is the name of the symbol to be created, `explText` is the symbol explanatory text, `dim` is the dimension of the symbol, `symType` is the type of the symbol, `subType` is the sybType of the symbol, `arr` is the 2D `numpy.array` with the symbol records, `domains` is the list of domains to be used for the symbol (optional), and `relaxedType` will automatically convert the columns of the `numpy.array` into the required data types if possible.	`gdx` (GDX handle created with `gams.core.gdx.new_gdxHandle_tp` or `str` GDX file name) `symName` (`str`) `explText` (`str`) `dim` (`int`) `symType` (`int`) `subType` (`int`) `arr` (`numpy.array`) `domains=None` (`list` of `str`)	`None`
`gmdFillSymbolRaw`	Fills an existing GMD symbol with the data from the provided `numpy.array` (`int` as domains). Symbols are defined with GAMS syntax, where `arr` is the two dimensional `numpy.array` containing integers for domains and `relaxedType` will automatically convert the columns of the `numpy.array` into the required data types if possible.	`gmd` (GMD handle created with `gams.core.gmd.new_gmdHandle_tp` or an instance of `GamsDatabase`) `symbolPtr` (GMD symbol pointer or an instance of `GamsParamater`, `GamsSet`, `GamsVariable` or `GamsEquation`) `arr` (`numpy.array`) `relaxedType=False` (`bool`)	`None`
`gmdFillSymbolStr`	Fills an existing GMD symbol with the data from the provided `numpy.array` (`str` as domains). Symbols are defined with GAMS syntax, where `arr` is the two dimensional `numpy.array` containing integers for domains and `relaxedType` will automatically convert the columns of the `numpy.array` into the required data types if possible.	`gmd` (GMD handle created with `gams.core.gmd.new_gmdHandle_tp` or an instance of `GamsDatabase`) `symbolPtr` (GMD symbol pointer or an instance of `GamsParamater`, `GamsSet`, `GamsVariable` or `GamsEquation`) `arr` (`numpy.array`) `relaxedType=False` (`bool`)	`None`
`gmdGetUelList`	Retrieves the list of UELs from `gmd`	`gmd` (GMD handle created with `gams.core.gmd.new_gmdHandle_tp` or an instance of a `GamsDatabase`)	`list`
`gmdReadSymbolRaw`	Reads symbol data from GMD into a `numpy.array` using integers for domains.	`gmd` (GMD handle created with `gams.core.gmd.new_gmdHandle_tp` or instance of `GamsDatabase`) `symName` (`str` name of the symbol to be read)	`numpy.array`
`gmdReadSymbolStr`	Reads symbol data from GMD into a `numpy.array` using `str` for domains. Argument `uelList` accepts the list of UELs to be used for the internal mapping (typically this is retrieved with `gdxGetUelList`). Supplying this parameter can increase performance when reading multiple symbols from the same GMD handle since the UEL list creation has to be performed only once.	`gmd` (GMD handle created with `gams.core.gdx.new_gmdHandle_tp` or instance of a `GamsDatabase`) `symName` (`str` name of the symbol to be read) `uelList=None` (	`numpy.array`

Examples

Create GDX Symbols

Gams2Numpy can be used to create sets (including singleton sets), parameters, variables, and equations by specifying the symbol type (symType) and the symbol sub-type (subType) codes from the following table (aliases are created with calls to gams.core.gdx.gdxAddAlias).

The parenthetical references the GAMS variable name (when accessing the GDX core API sub-module) to be used as the argument input:

>>> from gams.core import gdx

`symType`	`subType`	Resulting GAMS Symbol Type
`gdx.GMS_DT_SET`	`0`	set
`gdx.GMS_DT_PAR`	`0`	parameter
`gdx.GMS_DT_SET`	`1`	singleton_set
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_BINARY`	binary variable
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_INTEGER`	integer variable
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_POSITIVE`	positive variable
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_NEGATIVE`	negative variable
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_FREE`	free variable
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_SOS1`	sos1 variable
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_SOS2`	sos2 variable
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_SEMICONT`	semicont variable
`gdx.GMS_DT_VAR`	`gdx.GMS_VARTYPE_SEMIINT`	semiint variable
`gdx.GMS_DT_EQU`	`gdx.GMS_EQUTYPE_E`	eq equation
`gdx.GMS_DT_EQU`	`gdx.GMS_EQUTYPE_G`	geq equation
`gdx.GMS_DT_EQU`	`gdx.GMS_EQUTYPE_L`	leq equation
`gdx.GMS_DT_EQU`	`gdx.GMS_EQUTYPE_N`	nonbinding equation
`gdx.GMS_DT_EQU`	`gdx.GMS_EQUTYPE_X`	external equation
`gdx.GMS_DT_EQU`	`gdx.GMS_EQUTYPE_C`	cone equation
`gdx.GMS_DT_EQU`	`gdx.GMS_EQUTYPE_B`	boolean equation

import gams.numpy as gnp
from gams import GamsWorkspace
import gams.core.gdx as gdx
import numpy as np
 
ws = GamsWorkspace()
 
i = np.array([(f"i{i}", "") for i in range(10)])
j = np.array([(f"j{i}", "") for i in range(10)])
s = np.array([("i1", "")])
a = np.array([(f"i{i}", float(i)) for i in range(10)], dtype="object")
b = np.array([(f"i{i}", f"j{i}", i) for i in range(10)], dtype="object")
v = np.array(
    [(f"i{i}", i, 0, float("-inf"), float("inf"), 1) for i in range(10)], dtype="object"
)
e = np.array([(f"i{i}", i, 0, 0, float("inf"), 1) for i in range(10)], dtype="object")
 
gdxout = gdx.new_gdxHandle_tp()
gdx.gdxCreateD(gdxout, ws.system_directory, gdx.GMS_SSSIZE)
gdx.gdxOpenWrite(gdxout, "data.gdx", "")
 
 
gams2np = gnp.Gams2Numpy(ws.system_directory)
 
# create sets 'i' and 'j'
gams2np.gdxWriteSymbolStr(gdxout, "i", "description of 'i'", 1, gdx.GMS_DT_SET, 0, i)
gams2np.gdxWriteSymbolStr(gdxout, "j", "description of 'j'", 1, gdx.GMS_DT_SET, 0, j)
 
# create a singleton set 's(i)'
gams2np.gdxWriteSymbolStr(
    gdxout, "s", "description of 's'", 1, gdx.GMS_DT_SET, 1, s, ["i"]
)
 
# add an alias to a set
gams2np.gdxAddAlias(gdxout, "i", "ip")
 
# add an alias to the universe
gdx.gdxAddAlias(gdxout, "*", "u")
 
# create a scalar
gams2np.gdxWriteSymbolStr(
    gdxout,
    "f",
    "description of 'f'",
    0,
    gdx.GMS_DT_PAR,
    0,
    np.array([[90]]),
)
 
 
# create a 1D parameter
gams2np.gdxWriteSymbolStr(
    gdxout, "a", "description of 'a'", 1, gdx.GMS_DT_PAR, 0, a, ["i"]
)
 
# create a 2D parameter
gams2np.gdxWriteSymbolStr(
    gdxout, "b", "description of 'b'", 2, gdx.GMS_DT_PAR, 0, b, ["i", "j"]
)
 
# create a 1D variable
gams2np.gdxWriteSymbolStr(
    gdxout,
    "v",
    "description of 'v'",
    1,
    gdx.GMS_DT_VAR,
    gdx.GMS_VARTYPE_FREE,
    v,
    ["i"],
)
 
# create a 1D equation (=G=)
gams2np.gdxWriteSymbolStr(
    gdxout,
    "e",
    "description of 'e'",
    1,
    gdx.GMS_DT_EQU,
    gdx.GMS_EQUTYPE_G,
    e,
    ["i"],
)
 
gdx.gdxClose(gdxout)
gdx.gdxFree(gdxout)

Table of Contents