# Validate CGE-Core Against the Official GAMS `stdcge` Model

This guide reproduces the official Hosoe–Gasawa–Hashimoto standard CGE model in GAMS and compares it with CGE-Core.

The purpose is **not merely to confirm that CGE-Core runs**. The purpose is to check whether an independent implementation and solver reproduce the same benchmark and counterfactual results:

- **Reference implementation:** official GAMS Model Library `stdcge.gms`
- **Reference solver:** CONOPT
- **CGE-Core implementation:** Pyomo
- **CGE-Core solver:** IPOPT

Using a different modeling system and solver makes this a stronger validation than testing CGE-Core against itself.

---

## 1. What this validation checks

The official GAMS run solves two states:

1. the calibrated benchmark equilibrium;
2. the counterfactual equilibrium after abolishing import tariffs.

The results can be compared with CGE-Core for:

- benchmark utility;
- counterfactual utility;
- household demand;
- factor allocation;
- prices;
- production, imports, and exports;
- taxes and savings;
- percentage changes;
- Hicksian equivalent variation.

This validation is specific to the small standard CGE model from Hosoe, Gasawa, and Hashimoto. It does not by itself validate every possible model or dataset that could be used with CGE-Core.

---

## 2. Prerequisites

You need:

- a local clone of `CGE-core`;
- GAMS installed;
- a GAMS license that can solve the small `stdcge` model;
- CONOPT available in the GAMS installation.

The detailed walkthrough below uses Windows and VS Code. Linux and macOS users
can use an ordinary terminal and the equivalent commands in the next section.
The GAMS demo license is sufficient for this small model.

### Linux and macOS command equivalents

The GAMS commands themselves are platform-neutral:

```bash
gamslib stdcge
gams stdcge.gms nlp=conopt o=stdcge_reference.lst \
  lo=4 lf=stdcge_reference.log
echo $?
cat listA1.csv
```

Record the source checksum with:

```bash
sha256sum stdcge.gms > stdcge_source_sha256.txt  # Linux
shasum -a 256 stdcge.gms > stdcge_source_sha256.txt  # macOS
```

Run these commands from `validation/gams/stdcge`, just as in the Windows
walkthrough. The expected model results and comparison procedure are the same.

---

## 3. Open the repository in VS Code

Open the local repository folder:

```text
C:\Users\<YOUR NAME>\Documents\GitHub\CGE-core
```

Open a VS Code terminal:

```text
Terminal → New Terminal
```

Return to the repository root if necessary:

```bat
cd /d "C:\Users\<YOUR NAME>\Documents\GitHub\CGE-core"
```

Example:

```bat
cd /d "C:\Users\James Matthew\Documents\GitHub\CGE-core"
```

---

## 4. Make GAMS available in the terminal

Check whether Windows can find GAMS:

```bat
where gams
```

A successful result looks like:

```text
C:\GAMS\54\gams.exe
```

### If GAMS is installed but not on `PATH`

Find the directory containing `gams.exe`. For example:

```text
C:\GAMS\54
```

Temporarily add it to the current terminal:

```bat
set "PATH=C:\GAMS\54;%PATH%"
```

Verify:

```bat
where gams
```

This temporary change lasts only until the terminal is closed.

### Permanent option

Add the GAMS directory, such as `C:\GAMS\54`, to the Windows **User Path**:

1. Open the Windows Start menu.
2. Search for **environment variables**.
3. Open **Edit the system environment variables**.
4. Click **Environment Variables**.
5. Under **User variables**, select `Path`.
6. Click **Edit**.
7. Click **New**.
8. Add the GAMS directory.
9. Confirm all dialogs.
10. Restart VS Code.

Do not add the full `gams.exe` filename. Add only its containing directory.

---

## 5. Create a validation workspace

From the repository root, run:

```bat
if not exist validation\gams\stdcge mkdir validation\gams\stdcge
```

Enter the folder:

```bat
cd validation\gams\stdcge
```

The terminal path should now end with:

```text
CGE-core\validation\gams\stdcge>
```

---

## 6. Retrieve the official GAMS model

Copy the official `stdcge` model from the installed GAMS Model Library:

```bat
gamslib stdcge
```

Confirm that the source file appeared:

```bat
dir
```

You should see:

```text
stdcge.gms
```

Do not edit this file before validation. It is the independent reference implementation.

---

## 7. Record the exact source-file fingerprint

Create a SHA-256 checksum:

```bat
certutil -hashfile stdcge.gms SHA256 > stdcge_source_sha256.txt
```

This records exactly which version of `stdcge.gms` was used.

The file created is:

```text
stdcge_source_sha256.txt
```

---

## 8. Run the official model with CONOPT

Run:

```bat
gams stdcge.gms nlp=conopt o=stdcge_reference.lst lo=4 lf=stdcge_reference.log
```

Meaning:

- `gams stdcge.gms` runs the official model;
- `nlp=conopt` explicitly selects CONOPT;
- `o=stdcge_reference.lst` saves the full GAMS listing;
- `lo=4` displays progress and writes a log;
- `lf=stdcge_reference.log` names the log file.

A successful run should contain:

```text
*** Status: Normal completion
```

The model should solve twice:

1. benchmark equilibrium;
2. tariff-abolition counterfactual.

---

## 9. Check the process return code

Immediately after the GAMS command, run:

```bat
echo %ERRORLEVEL%
```

Expected:

```text
0
```

A nonzero value means the GAMS job did not finish normally and the listing and log should be inspected before comparing results.

---

## 10. Check the generated files

Run:

```bat
dir
```

Expected files include:

```text
listA1.csv
stdcge.gms
stdcge_reference.log
stdcge_reference.lst
stdcge_source_sha256.txt
```

The exact file sizes vary by GAMS version.

---

## 11. Inspect the compact GAMS output

Display the CSV written by the official model:

```bat
type listA1.csv
```

A verified GAMS 54.2.1 / CONOPT 4.39.1 run produced:

```text
"This is an example of usage of the Put command."

"dXp(i)"
"BRD",1.96
"MLK",2.51

"dTd",0.05

"F(h,j)"
"","BRD","MLK"
"CAP",20.43,29.57
"LAB",15.33,24.67

"beta(h,j)"
"","BRD","MLK"
"CAP",0.57,0.55
"LAB",0.43,0.45
```

These are rounded values written by the official GAMS model.

---

## 12. Compare with CGE-Core

From the repository root, activate the CGE-Core environment if necessary:

```bat
conda activate cgecore
```

Run the Python implementation:

```bat
python -m cge_core.examples.stdcge
```

The verified CGE-Core/IPOPT run produced:

### Objective values

| State | GAMS/CONOPT | CGE-Core/IPOPT |
|---|---:|---:|
| Benchmark utility | 25.5084900125 | 25.508490012515818 |
| Tariff-abolition utility | 26.0926343813 | 26.092634381199485 |

The differences are approximately \(10^{-10}\) or smaller, which is consistent with normal floating-point and solver-tolerance differences.

### Values written to `listA1.csv`

| Quantity | GAMS | CGE-Core | Comparison |
|---|---:|---:|---|
| `dXp(BRD)` | 1.96% | 1.960958% | same after rounding |
| `dXp(MLK)` | 2.51% | 2.509951% | same after rounding |
| `dTd` | 0.05% | 0.049350% | same after rounding |
| `F(CAP,BRD)` | 20.43 | 20.426005 | same after rounding |
| `F(CAP,MLK)` | 29.57 | 29.573995 | same after rounding |
| `F(LAB,BRD)` | 15.33 | 15.333112 | same after rounding |
| `F(LAB,MLK)` | 24.67 | 24.666888 | same after rounding |

This confirms that the independent Pyomo/IPOPT implementation reproduces the official GAMS/CONOPT solution for these reported results.

---

## 13. Inspect the full listing

Open this file in VS Code:

```text
validation/gams/stdcge/stdcge_reference.lst
```

Useful searches:

```text
MODEL STATUS
```

```text
PARAMETER EV
```

```text
PARAMETER dZ
```

```text
PARAMETER dXp
```

```text
PARAMETER dM
```

```text
PARAMETER dE
```

You can also extract sections from the terminal.

### Equivalent variation

```bat
powershell -Command "Select-String -Path 'stdcge_reference.lst' -Pattern 'PARAMETER EV' -Context 0,4"
```

### Selected percentage-change tables

```bat
powershell -Command "Select-String -Path 'stdcge_reference.lst' -Pattern 'PARAMETER dZ|PARAMETER dXp|PARAMETER dM|PARAMETER dE' -Context 0,5"
```

The CGE-Core tariff-abolition example reports Hicksian equivalent variation of approximately:

```text
EV = +1.1450
```

Confirm the corresponding value in the GAMS listing before recording it as a completed comparison.

---

## 14. Interpretation

A successful comparison establishes more than successful execution.

The two systems differ in both implementation and nonlinear solver:

```text
Official reference: GAMS + CONOPT
CGE-Core:          Pyomo + IPOPT
```

Agreement in the benchmark and tariff counterfactual therefore provides strong evidence that:

- the SAM was interpreted correctly;
- calibration formulas were ported correctly;
- the model equations are solving to the same equilibrium;
- the closure and numeraire are consistent with the reference model;
- the tariff shock is applied correctly;
- reported differences and percentages are correct.

It is still possible for untested features or other datasets to contain errors. This validation should therefore be described as **replication of the official Hosoe standard-model benchmark and tariff experiment**, not universal proof of correctness.

---

## 15. Recommended repository layout

This guide should be committed to the repository, preferably as:

```text
docs/GAMS_STDCGE_VALIDATION.md
```

Recommended local validation layout:

```text
validation/
└── gams/
    └── stdcge/
        ├── stdcge.gms
        ├── stdcge_source_sha256.txt
        ├── stdcge_reference.lst
        ├── stdcge_reference.log
        └── listA1.csv
```

### What should be committed

Recommended:

- this Markdown guide;
- a small machine-readable comparison file created by CGE-Core;
- the source SHA-256 checksum;
- a concise expected-results CSV or JSON;
- an automated comparison script or pytest regression test.

### What should normally remain generated locally

Recommended not to commit by default:

- GAMS scratch directories;
- personal GAMS license files;
- full `.lst` and `.log` files unless intentionally retained as release evidence;
- machine-specific paths;
- the copied `stdcge.gms` source unless its redistribution terms have been checked.

The safest reproducible approach is to let each user retrieve `stdcge.gms` from their own installed GAMS Model Library with:

```bat
gamslib stdcge
```

The GAMS documentation explicitly supports copying Model Library examples into a working directory with `gamslib`, but the public documentation reviewed for this guide does not clearly state a separate redistribution license for committing the copied source into an unrelated MIT-licensed repository.

Never commit:

```text
gamslice.txt
```

or any other license/access-code file.

---

## 16. Suggested `.gitignore` entries

Add these only if they match the repository's intended validation workflow:

```text
# GAMS-generated validation outputs
validation/gams/**/225a/
validation/gams/**/*.log
validation/gams/**/*.lst

# GAMS licenses must never be committed
**/gamslice.txt
```

Do not ignore the checksum or compact expected-results files if they are intended to be part of the permanent validation record.

---

## 17. Official references

- GAMS Model Library access:
  https://www.gams.com/latest/docs/UG_ModelLibraries.html
- GAMS Model Libraries overview:
  https://www.gams.com/latest/docs/modlibs.html
- Official `stdcge` model page:
  https://www.gams.com/latest/gamslib_ml/libhtml/gamslib_stdcge.html
- GAMS Windows installation:
  https://www.gams.com/latest/docs/UG_WIN_INSTALL.html
- GAMS license setup:
  https://www.gams.com/latest/docs/UG_License.html

---

## 18. Reproduction record from 2 August 2026

The validation documented here was performed with:

```text
Operating system: Windows x86-64
GAMS:            54.2.1
CONOPT:          4.39.1
Python:          3.11.15
Pyomo:           6.10.1
IPOPT:           3.14.19
CGE-Core:        0.3.0
```

Observed GAMS model dimensions:

```text
49 constraints
49 variables
179 Jacobian elements in the benchmark solve
175 Jacobian elements after the tariff shock
```

Observed completion status:

```text
*** Status: Normal completion
ERRORLEVEL = 0
```