GAMS Transfer R

Posted on: 05 Jun, 2024 News GAMS Transfer R
Atharv Bhosekar

GAMS Transfer R was first released with the GAMS major release in August 2022 and has been included in all subsequent GAMS releases. Recently, we made GAMS Transfer R open-source and available on CRAN . In this blog post, I will provide a brief overview of GAMS Transfer R, what it is, who it is aimed to help, and how to use it.

What is gamstransfer and why do I need it?

While GAMS syntax is powerful, it is not a general programming language. A user might prefer relying on their language of preference to perform tasks that don’t necessarily require GAMS, such as data processing and I/O from various data sources. For users working with R as their preferred language, gamstransfer is a package that enables seamless data exchange with GAMS. It offers object-oriented and intuitive syntax for reading and writing GDX files, understanding, analyzing, and modifying GAMS data in R. With internal C++ power calls, gamstransfer is highly performant and enables the transfer of bulk data to GAMS rather than handling records for individual symbols.

How to install gamstransfer?

gamstransfer is available on CRAN and can be installed with a single command from your R console:

install.packages("gamstransfer")

Design philosophy

gamstransfer aligns with the philosophy of other products in the transfer family, such as transfer Python and transfer Matlab . The core idea is to use a Container that encapsulates all data. A Container is state-aware, maintains links between symbols (e.g., domain links) and enables analyses and operations across multiple symbols. Read and write operations take place through Container methods read and write.

Quick start example

Reading a GDX file gams_data.gdx is a matter of just one power call. Here is an example of reading the data for the transport model from the GAMS model library.

library(gamstransfer)
m = Container$new("trnsport.gdx")

To access the parameter containing distances from this data, one can do m[“d”]. To access the records, m[“d”]$records can be used. Currently, symbol records are stored in R data.frame format.

Suppose the data is in R (from any source such as Excel, SQL and so on..), writing it to a GDX file is easy as illustrated with the following example. Here, we use the data for the transport model again. The steps for doing this are as follows:

  1. Create a Container
  2. Add symbols to the Container
  3. Use the $write power call.
library(gamstransfer)
m = Container$new()

# create the sets i, j
i = Set$new(m, "i", records = c("seattle", "san-diego"), description = "supply")
j = Set$new(m, "j", records = c("new-york", "chicago", "topeka"), description = "markets")

# add "d" parameter -- domain linked to set objects i and j
d = Parameter$new(m, "d", c(i, j), description = "distance in thousands of miles")

# create some data as a generic data frame
dist = data.frame(
    from = c("seattle", "seattle", "seattle", 
    "san-diego", "san-diego", "san-diego"),
    to = c("new-york", "chicago", "topeka",
      "new-york", "chicago", "topeka"),
    thousand_miles = c(2.5, 1.7, 1.8, 2.5, 1.8, 1.4)
)

# setRecords will automatically convert the dist data frame into 
# a standard data frame format
d$setRecords(dist)

Note how for the sets, the records are passed as a vector and that for the parameter d, it is passed as a data.frame. Once the data is loaded into a Container, writing it to a GDX file is easy.

m$write("trnsport.gdx")

Under the hood

gamstransfer leverages the object-oriented programming capabilities provided by the R6 package. All symbols and containers are R6 objects, enabling gamstransfer to pass data by reference and maintain reliable links between symbols. Additionally, gamstransfer utilizes the new and open-source C++-based GDX API and the Rcpp package in R, ensuring high performance for read and write operations. We routinely test gamstransfer on datasets that have hundreds of millions of records.

Transition from GDXRRW

So far, R users have relied on the GDXRRW tool. With the advent of gamstransfer, GDXRRW is now deprecated and will no longer be shipped with GAMS.

Providing Feedback and Reporting Issues

For feedback, feature requests, or bug reports, please contact support@gams.com or create an issue in the gamstransfer GitHub repository .