GDX Analyzer

Browse, chart and compare GAMS GDX files in Visual Studio Code.

GDX Analyzer opens .gdx files in a fast, read-only viewer, compares files as gdxdiff does, across scenarios and with their Git history, links GAMS and Python code to the data, exports to Excel and Python, and gives AI agents read-only access to model data and solutions. GDX files are read, compared as gdxdiff does, and written as gdxdump text and CSV by the extension itself, so no GAMS installation is needed, and it also runs in VS Code for the Web (vscode.dev, github.dev). See the changelog for what is new.

GDX Analyzer is an independent project by Muhammet Soyturk. It is not affiliated with or endorsed by GAMS.

Features

Viewer

• Symbol table with entry, name, domain, type (e.g. Positive Variable, Singleton Set), dimension, records and explanatory text. Sort by any column, group by type, and search names or all columns. Entry * lists the unique elements of the file.
• List and table views. The table view arranges dimensions as rows and columns: drag them between the two, or swap them with ⇄. Variables and equations show level, marginal, bounds and scale.
• Aggregation and totals. Drag dimensions of the table view to Aggregated to combine their records with sum, mean, min, max or count, and add a total row and total columns with Totals. Columns without any value are left out of the table view.
• Built for large symbols. Records load while you scroll, so symbols with millions of records stay responsive.
• Filters and search. Filter labels from a checklist (optionally with the selected labels first) and numbers by range and special value. Search with wildcards, exact match or regular expressions, then jump between matches or show only matching rows.
• Heatmap. Color the numbers of the list and table view by value, on the scale of all records or of the filtered ones; each field has its own scale.
• Solution status. For variables and equations, show only the records with a non-zero marginal (binding constraints), a level at its lower or upper bound, a level outside its bounds (infeasible), or a field that is not at its default. Each choice shows how many records it matches.
• Exact numbers. Values are read exactly. Choose the format per symbol (g, f or e, a precision, or full precision); sorting, filters and copies always use the exact values. A third click on the header of a number column sorts by magnitude, largest first.
• Selection and copy. Select cells, rows or columns and press Ctrl+C to paste them into Excel. The status bar shows the sum, average and count of the selection. Ctrl+R fits the columns to their content.
• Files of other file systems, such as Git revisions, open through a temporary copy.
• Remembers your view of every symbol (filters, sorting, layout, format, column widths) and reloads when the file changes, e.g. after a GAMS run. Symbols shown for the first time open in the view and with the fields of variables and equations chosen in the settings.

Solution report

Solution Report (in the viewer, the Explorer and the Command Palette) checks all variables and equations of a solution at once, e.g. to find out why a model is infeasible or which constraints drive the solution:

• the records outside their bounds, farthest outside first, with their level, bounds and infeasibility,
• the binding constraints (equations with a non-zero or EPS marginal), largest |marginal| first,
• per symbol, the number of records outside their bounds, with a non-zero marginal and at their lower and upper bounds, with the largest infeasibility and |marginal|.

Click a record or a count to open the symbol with that solution status filter. The report is read again when the file changes, e.g. after a GAMS run.

Charts

Show the filtered records of a symbol as bars, lines or a heatmap. Pick the category dimension, the series and the field; other dimensions are summed. Colors follow your theme and are colorblind-safe, and a heatmap switches to a diverging scale when values have both signs. Save a chart as PNG or SVG, or copy it.

Comparing files

Two files. Compare two files as gdxdiff does and review each differing symbol record by record: the values of both files, their difference (Δ) and relative difference in percent (Δ%), and records that exist in only one file. Sort a Δ or Δ% column by magnitude to see the largest changes first. Chart the differences, open a text diff of the gdxdump output, or save the difference file. All gdxdiff options (tolerances, fields, symbols to compare or skip, and more) can be set per comparison.

Scenarios. Compare one symbol across any number of GDX files, e.g. the results of several scenario runs: select the files in the Explorer and choose Compare Scenarios… (or Compare GDX Files with more than two). The table view shows the scenarios side by side with the difference (Δ) and relative difference (Δ%) from a base scenario you choose; records missing in a scenario count as 0. Charts show a series per scenario, and filters, the solution status, aggregation and totals work as in the viewer. The comparison is read again when a file changes.

Git. Compare with Git Revision… (in the Explorer and the viewer) compares a GDX file with its last commit, its staged version or any commit of its history, or two of its revisions with each other. Clicking a changed GDX file in Source Control shows both versions side by side in the viewer.

git diff as text. Set Up Git Diff for GDX Files… lets git diff, git log -p, git show and Git tools built on them show GDX files as text in the format of gdxdump, instead of Binary files differ, with the declaration of the symbol in the header of each change:

@@ -12,7 +12,7 @@ Set j(*) markets /
 Alias (ii, i);

 Parameter a(i) capacity of plant i in cases /
-'seattle' 350,
+'seattle' 360,
 'san-diego' 600 /;

Set it up for one repository (it adds *.gdx diff=gdx to .gitattributes: commit it to share it) or for all your repositories (the global Git attributes file). The conversion itself is part of each Git configuration, so each user runs the command once; it keeps working after the extension is updated, and needs neither GAMS nor GAMSPy. To undo it, run git config --remove-section diff.gdx (with --global for all repositories) and remove the line from the attributes file. The same conversion is available on the command line: node <extension>/out/cli.js dump <file> [<symbol>] [--csv].

GAMS and Python code

Links. GDX file names in .gms and Python files are links (Ctrl+click) that open the file in the viewer: $gdxIn data, execute_unload 'results.gdx', x;, gdx=out.gdx on a $call line, or Container(load_from="data.gdx") in GAMSPy. The symbols read or written by $load, $unLoad, execute_load, execute_unload and similar statements are links to that symbol in the file, and so are, in GAMSPy and GAMS Transfer code, the symbols of read(), write() and loadRecordsFromGdx() (symbol_names=, symbols= or a list after the file) and m["x"] of a container read from a file. Put the cursor on any symbol name and run GDX: Show Symbol in GDX File (also in the editor context menu) to open it in a GDX file the document references. Relative names are looked up next to the document, then in the workspace folders.

Hover previews. Hover a GDX file name to see its symbols by type, or a symbol name to see a preview from the file: its type, records and text, its first records, the minimum, maximum and sum of its values and, for variables and equations, how many records are outside their bounds, binding and at their bounds. This works for the symbols of $load, execute_unload and similar statements, and for any other name in a document that references GDX files (the nearest reference before the name first). In Python, a name also previews the symbol it is bound to, e.g. limit in limit = Equation(m, name="supply"), cap = m.addParameter("a") or price = m["p"]. In a notebook, the GDX files read in other cells count too. Symbols with more than 200,000 records are previewed without them.

Copy as Code. Python code that reads a symbol into a pandas DataFrame with GAMS Transfer or GAMSPy and applies the view: filters, solution status, sorting, shown fields and the table view (as pivot_table, with aggregation and totals). Copy it or open it in a new editor.

Export and import

• Excel: write any symbols to an .xlsx workbook, one sheet each, laid out like their view, with exact values. Optionally apply the filters and choose how special values are written. The same export can be saved as GAMS Connect instructions.
• GDX: save any symbols as a new GDX file, all their records or only those passing the filters of their views, with their fields, texts, domains and exact values. An alias brings its set along; a regular domain whose set is not saved, or whose set's saved records leave out some records, is written as a relaxed domain.
• CSV of one symbol, and the gdxdump output of a file or symbol as a text document.
• From CSV and Excel: Create GDX from CSV/Excel… (also in the Explorer) makes a GDX file of a table, like csv2gdx: choose the columns with labels; one other column gives a parameter, several give a parameter with an extra dimension named after them, and a set takes its element texts from another column. Numbers may use a decimal comma in semicolon separated files, and EPS, NA, INF, -INF and UNDF are read as special values.

AI agents (MCP)

A built-in MCP server gives AI agents read-only access to GDX files. It is available to agent mode in VS Code automatically. For Claude Code, Cursor and other agents, run GDX: Copy MCP Server Configuration for AI Agents… and paste the result into their configuration.

VS Code for the Web

GDX Analyzer also runs in VS Code for the Web: open a repository on github.dev (press . on its GitHub page) or a folder on vscode.dev, and its GDX files open in the viewer, with nothing installed. The viewer, the solution report, comparisons of files and scenarios, charts, the exports (Excel, CSV, Save as GDX, gdxdump text), Create GDX from CSV/Excel, and the links and hover previews in GAMS and Python source work as on the desktop; a diff of two versions of a GDX file (e.g. of a change in Source Control) shows both versions in the viewer. Copy as Code and GAMS Connect instructions name the files relative to the workspace folder.

Not available in the browser: the MCP server for AI agents, gdxdump and gdxdiff (gdxAnalyzer.useGamsTools), Compare with Git Revision…, Set Up Git Diff for GDX Files… and the command line. A file is read whole into memory there (see Performance).

Getting started

1. Install GDX Analyzer from the Visual Studio Marketplace.
2. Open a .gdx file: it opens in the viewer.
3. To compare two files, select both in the Explorer, right-click and choose Compare GDX Files (gdxdiff). You can also use Select for GDX Compare and Compare with Selected GDX, or Compare… in the viewer.
4. To compare scenarios, select two or more files and choose Compare Scenarios….

Commands

All commands are in the Command Palette under GDX; the most common ones are also in the Explorer context menu and the viewer.

Settings

Requirements

• Visual Studio Code 1.101 or later.
• Any platform: GDX files are read, compared and dumped by the extension itself, so neither GAMS nor GAMSPy is needed. gdxdump and gdxdiff of a GAMS installation or of GAMSPy are only used with gdxAnalyzer.useGamsTools, and for GDX files the extension cannot read itself.
• Also VS Code for the Web (vscode.dev, github.dev), with the features listed in VS Code for the Web.

Performance

GDX files are read natively, in chunks, straight into compact columns, and the viewer only renders the rows on screen. Measured on an Intel Core i7-1260P with a 135 MB GDX file (Load with gdxdump in brackets):

Comparing two files with 2 million differing records takes about 1.9 seconds (4 seconds with gdxdiff). Comparing 5 scenarios of a symbol with 1 million records each (5 million rows) takes 1.5 s and 310 MB for a parameter, and 1.9 s and 580 MB for a variable; the table view, a sort by Δ and a chart then take 0.1–1.6 s.

In VS Code for the Web, a file is read whole into memory, and compressed files are decompressed in JavaScript: in a measurement in Chromium, the 10 million records of a 3-dimensional parameter took 0.7 s from a 102 MB uncompressed file (0.45 s on the desktop) and 2 s from an 80 MB compressed one (0.8 s on the desktop), after 0.2–0.3 s to read the file.

Limitations

• On the desktop, GDX files are read from a regular file system: files of other file systems (such as Git revisions) are viewed through a temporary copy; comparisons, GAMS Connect instructions and Copy as Code need files on disk. In VS Code for the Web, files of any file system are read, whole into memory (see VS Code for the Web for what is not available there).
• The native reader reads GDX file formats 5 to 7, compressed or not, written with little-endian byte order (all current platforms); other files are read and compared with gdxdump and gdxdiff, if available.
• Sums of relative differences (Δ%) and of the bounds and scale of variables and equations are left empty in aggregated cells and totals; mean, min, max and count are shown.
• With the gamspy backend, file names must end in lower-case .gdx.
• The text of git diff is made by Git on your machine: the web pages of GitHub and GitLab still show GDX files as binary. GDX files in Git LFS show the changes of their LFS pointers. The conversion runs node if it is on the PATH when the setup is run, else VS Code itself.
• Excel files are read as their cells hold values: dates are their serial numbers, and formulas give their last calculated results.
• Copying is limited to 5 million cells, and the Excel export to Excel's sheet size (1,048,576 rows, 16,384 columns). Filter larger symbols first.

Contributing

See CONTRIBUTING.md for building, testing and packaging the extension, and THIRD_PARTY_NOTICES.md for the license of the GDX library, whose file format and tools the extension follows.