gdx-pandas

gdx-pandas is a python package to translate between gdx (GAMS data) and pandas.

Install | Documentation | Uninstall

Install

Preliminaries

• Python 3.11 or higher (exact compatibility might depend on which GAMS version you are using)

• Install GAMS

• Put the GAMS directory in your PATH and/or assign it to the GAMS_DIR environment variable

• GAMS Python bindings — choose one:

  Recommended. Install the gamsapi that matches your installed GAMS version:

  # xx.y.z corresponds to your GAMS version
  pip install gamsapi[transfer]==xx.y.z

  Installing gamsapi this way also enables the optional, much-faster gams.transfer I/O engine for large files (see Configure below).

  Legacy. Use the standalone gdxcc package from PyPI by installing gdxpds with the legacy extra (see below). gdxcc is older and is not version-matched to your GAMS install, but the SWIG-bound C ABI is stable enough that it generally works.

Get the Latest Package

# Recommended (use with the gamsapi install above):
pip install gdxpds

# Legacy (also installs gdxcc; use if you skipped gamsapi):
pip install gdxpds[legacy]

Versions are listed at pypi and https://github.com/NatLabRockies/gdx-pandas/releases.

Configure

gdxpds needs to know where GAMS is, and optionally which I/O engine to use. Set either once via an environment variable, or per call with the gams_dir= / engine= keywords (also --gams_dir / --engine on the CLIs):

export GAMS_DIR=/path/to/gams        # otherwise auto-discovered
export GDXPDS_ENGINE=gdxcc          # default: gams_transfer when usable (much faster on large files), else gdxcc

See Configuration in the documentation for the full keyword / environment-variable / CLI matrix and the speed trade-offs.

Verify installation

After installing gdxpds and a matching gamsapi, verify your environment end-to-end with:

gdxpds test

For a quick environment check without running the full round-trip, use gdxpds info — it prints Python, bindings, the resolved GAMS_DIR (and which discovery branch produced it), and any import-time load error. Useful for bug reports. gdxpds --version prints just the version.

Expected output for gdxpds info, which is also printed at the top of the gdxpds test output:

gdxpds info
-----------
gdxpds:        <version>
Python:        <python version> (<platform>)
Bindings:
  gams.core.gdx: [gamsapi <version> | not importable]
  gdxcc: [gdxcc <version> | not importable]
  gams.transfer: [gamsapi <version> | not importable]
  selected:    [gams.core.gdx | gdxcc]
  bound dir:   <your GAMS directory>
  gams.transfer usable: [yes | no]
Default engine: [gams_transfer | gdxcc]
GAMS_DIR:      <your GAMS directory>
  source:      [GAMS_DIR env var | GAMSDIR env var | <discovered location> | explicit override | cached]

Example gdxpds test output that follows the info preamble:

Verifying gdxpds installation...
  [OK]   GAMS install found at <your GAMS directory>
  [OK]   GDX bindings loaded: gams.core.gdx
  [OK]   Read embedded sample.gdx (...)
  [OK]   Round-trip write->read preserves all symbols
  [OK]   Special values (+Inf, -Inf, NaN) survive round-trip

PASSED: gdxpds installation verified.

Development tests

To run the development test suite, clone the repo and run:

pytest tests

If the tests fail due to permission IOErrors, apply chmod g+x and chmod a+x to the tests folder.

Uninstall

pip uninstall gdxpds