GDXInterface.jl

GDXInterface.jl is an unofficial wrapper for gams-dev/gdx, which provides support for reading and writing GDX (GAMS Data Exchange) files.

For more information on the GDX file format, see the blog post GDX source code published on GitHub.

Affiliation

This package is an unofficial Julia wrapper of gams-dev/gdx. It is developed and maintained by the JuMP community. It is not an official product by GAMS.

Getting help

If you need help, please ask a question on the JuMP community forum.

If you have a reproducible example of a bug, please open a GitHub issue.

License

GDXInterface.jl is licensed under the MIT License.

GDXInterface.jl wraps the official GAMS GDX project, which is also licensed under the MIT License. You do not need a GAMS license to use GDXInterface.jl.

Installation

Install GDXInterface.jl as follows:

using Pkg
Pkg.add(; url = "https://github.com/jump-dev/GDXInterface.jl.git")

You do not need a GAMS installation to use GDXInterface.jl.

Quick Start

Reading GDX files

using GDXInterface

gdx = read_gdx("transport.gdx")

# List symbols by type
list_sets(gdx)
list_parameters(gdx)
list_variables(gdx)
list_equations(gdx)

# Access data as Tables.jl-compatible column tables
demand = gdx[:demand]       # bracket syntax
demand = gdx.demand         # property syntax (with tab completion)

# Access the full symbol object (includes name, description, domain)
sym = get_symbol(gdx, :demand)
sym.name         # "demand"
sym.description  # explanatory text from GAMS
sym.domain       # ["j"]
sym.records      # the records table

# Pass DataFrame as a sink to materialize DataFrames while reading
using DataFrames
gdx = read_gdx("transport.gdx", DataFrame)

Writing GDX files

using GDXInterface

# Write Tables.jl-compatible tables as parameters
supply = (; i = ["seattle", "san-diego"], value = [350.0, 600.0])
demand = (; j = ["new-york", "chicago", "topeka"], value = [325.0, 300.0, 275.0])
write_gdx("output.gdx", "supply" => supply, "demand" => demand)

# Round-trip: read a GDX file and write it back (preserves all symbol types)
gdx = read_gdx("model.gdx")
write_gdx("copy.gdx", gdx)

Selective reading

For large GDX files, load only the symbols you need:

gdx = read_gdx("big_model.gdx", only=[:x, :demand])

API Reference

Types

Type	Description
GDXFile	Container for all symbols in a GDX file
GDXSet	GAMS set (elements + explanatory text)
GDXParameter	GAMS parameter (domain elements + values)
GDXVariable	GAMS variable (level, marginal, lower, upper, scale)
GDXEquation	GAMS equation (level, marginal, lower, upper, scale)

Reading

read_gdx(filepath[, sink]; parse_integers=true, only=nothing) -> GDXFile

• sink: callable that materializes a column table, defaulting to Tables.columntable
• parse_integers: convert set elements like "2020" to Int
• only: vector of symbol names to load (e.g. [:x, :demand])

Writing

# Write tables as parameters (convenience)
write_gdx(filepath, "name" => table, ...)

# Write a full GDXFile (sets, parameters, variables, equations)
write_gdx(filepath, gdxfile::GDXFile)

Querying a GDXFile

gdx[:name]               # records table (bracket access)
gdx.name                 # records table (property access)
get_symbol(gdx, :name)   # full GDXSymbol object

list_sets(gdx)            # list set names
list_parameters(gdx)      # list parameter names
list_variables(gdx)       # list variable names
list_equations(gdx)       # list equation names
list_symbols(gdx)         # list all symbol names

haskey(gdx, :name)        # check if symbol exists
length(gdx)              # number of symbols
for (k, v) in gdx ...    # iterate over symbols

Special Values

GAMS special values are mapped to Julia equivalents when reading:

GAMS	Julia	Notes
UNDEF	NaN	Undefined value
NA	NaN	Not available
+INF	Inf	Positive infinity
-INF	-Inf	Negative infinity
EPS	-0.0	"Explicitly zero" in sparse data

When writing, NaN maps to GAMS NA, Inf/-Inf map to +INF/-INF, and -0.0 maps back to GAMS EPS. This preserves EPS semantics through round-trips. Regular 0.0 stays as a normal zero.

Acknowledgments

Derived from GDX file access functionality originally developed for GAMS.jl.