refactor!: rename aliased_with -> alias_of; document universe-alias dispatch

BREAKING (within v3.0.0 — alias support is new in this PR): rename the alias
relationship attribute on GdxSymbol from `aliased_with` to `alias_of`. The
old name was a gdxpds invention; gams.transfer uses `alias_with` (active
voice; not `aliased_with`) and gdxcc has no Python-attribute analog. `alias_of`
reads naturally ("at is `alias_of` t"), matches the active voice of the
gams.transfer naming, and isn't confused with the unrelated "aliased with"
phrasing that suggested help-from a parent. Renames propagated:
`GdxSymbol.alias_of` / `alias_of_name`, `resolve_alias_of()`, the
`alias_of=` constructor kwarg, and the corresponding private attrs.

Also adds a comment in `_gdxcc_engine.GdxccEngine.write_symbol` cross-
referencing the gams.transfer engine's `gt.Alias` / `gt.UniverseAlias`
dispatch: `gdxAddAlias` accepts `"*"` as a parent without any special-case
call, so the gdxcc engine has a single uniform write path for both
named-Set aliases and universe aliases.

Test matrix on this branch: PASS / PASS / PASS / OK across
.venv-gams-{34,49,51} and .venv-no-gams. Ruff and pyright clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: elainethale

CHANGES.txt

@@ -6,7 +6,7 @@ v3.0.0, 05/25/26 -- BREAKING: the default I/O engine is now gams.transfer when i
                     conveyed by row presence. The load_set_text argument is removed: text
                     is always read, and any non-empty text is always written
                     aliases are now fully supported: they read with a populated
-                    GdxSymbol.aliased_with (the parent Set), round-trip through both
+                    GdxSymbol.alias_of (the parent Set), round-trip through both
                     engines, and can be created via to_gdx(aliases={alias: parent}) or
                     gdxpds.gdx.append_alias()
                     BREAKING: GDX UNDEF (Python None) is now preserved on write by both

CLAUDE.md

@@ -97,7 +97,7 @@ Things that aren't obvious from one file:
 - **Symbol kinds drive column shape.** `GamsDataType` ([src/gdxpds/gdx.py](src/gdxpds/gdx.py)) — Set, Parameter, Variable, Equation, Alias. Variables and Equations get five value columns (Level, Marginal, Lower, Upper, Scale); Parameters and Sets get a single `Value` column. Write code in [src/gdxpds/write_gdx.py](src/gdxpds/write_gdx.py) infers the type from DataFrame shape and naming.
 - **Special values.** GAMS encodes NA/EPS/+Inf/-Inf/UNDEF as fixed magic floats (e.g. 1E300, 2E300, 3E300). [src/gdxpds/special.py](src/gdxpds/special.py) converts these to/from numpy equivalents (`np.nan`, `np.inf`, and `None` for UNDEF) on read/write. Parameters get this conversion; Sets/Aliases do not (their value column is text, see below). UNDEF (`None`) is preserved on write by both engines; the gams.transfer write passes `eps_to_zero=False` so EPS survives too.
 - **Set value = element text; membership = row presence.** A Set/Alias has one `Value` column holding the GAMS element text (a string; `""` = a member with no text). Every row is a member — there is no boolean. `_fixup_set_value` ([src/gdxpds/gdx.py](src/gdxpds/gdx.py)) normalizes the column to text on assignment (a `bool`/`c_bool`/missing value → `""`), so a Set can be built from dims alone, from booleans, or from text. The read path always fetches text (`gdxGetElemText()` on gdxcc; the records frame on gams.transfer); there is no `load_set_text` flag.
-- **Aliases.** An Alias reads like the Set it aliases and records the parent in `GdxSymbol.aliased_with` (a parent ref, or `None`). It is written by both engines (`gdxAddAlias` / `gt.Alias`); the parent must precede it (no relaxed fallback — `DomainError` otherwise). `to_gdx(aliases={alias: parent})` and `gdxpds.gdx.append_alias()` build them; ordering follows `reorder_for_strict_domains()`, which now adds the alias→parent edge. The parent is typically a Set, but an Alias is accepted too: GDX supports chained aliases, and the gdxcc engine preserves the chain on disk (`aat -> at -> t`) while gams.transfer flattens it to the root (`aat -> t`). On read both engines produce a same-file `aliased_with` ref. *Universe* aliases (alias of `*`) are a documented edge: they read without error (`aliased_with` resolves to `universal_set`) and round-trip within one engine, but the engines disagree on membership (gdxcc includes the `*` element, gams.transfer doesn't), so `universe_alias_fixture.gdx` is excluded from the cross-engine parity glob and covered by `tests/test_alias.py`.
+- **Aliases.** An Alias reads like the Set it aliases and records the parent in `GdxSymbol.alias_of` (a parent ref, or `None`). It is written by both engines (`gdxAddAlias` / `gt.Alias`); the parent must precede it (no relaxed fallback — `DomainError` otherwise). `to_gdx(aliases={alias: parent})` and `gdxpds.gdx.append_alias()` build them; ordering follows `reorder_for_strict_domains()`, which now adds the alias→parent edge. The parent is typically a Set, but an Alias is accepted too: GDX supports chained aliases, and the gdxcc engine preserves the chain on disk (`aat -> at -> t`) while gams.transfer flattens it to the root (`aat -> t`). On read both engines produce a same-file `alias_of` ref. *Universe* aliases (alias of `*`) are a documented edge: they read without error (`alias_of` resolves to `universal_set`) and round-trip within one engine, but the engines disagree on membership (gdxcc includes the `*` element, gams.transfer doesn't), so `universe_alias_fixture.gdx` is excluded from the cross-engine parity glob and covered by `tests/test_alias.py`.
 - **Lazy + idempotent GAMS bind.** `load_gdxcc()` in [src/gdxpds/tools.py](src/gdxpds/tools.py) binds the GAMS library and populates `gdxpds.special` dicts on the first GDX op (called by the gdxcc engine's `__init__` before it creates a handle, and by `info()` inside try/except for diagnostics). Process state: `tools._bindings_source`, `tools._loaded_gams_dir`.
 - **`gams_dir=` on the first GDX op selects the bound install.** Once loaded, subsequent `gdxCreateD(H, <dir>, ...)` calls are no-ops against the bound library regardless of `<dir>`; `load_gdxcc()` warns when a caller passes a `gams_dir` that differs from `_loaded_gams_dir`. One GAMS library per process — multi-version testing is one-venv-per-GAMS. In-process swap is feasible via `gdxLibraryUnload()` but unimplemented (design notes tracked in a GitHub issue).
 - **GDX handle lifecycle** (SWIG-bound `gdxcc`; gdxcc engine only — the gams.transfer engine holds no handle). The full `new_gdxHandle_tp` → `gdxCreateD` → `gdxFree` → `delete_gdxHandle_tp` sequence lives in one place: the `_GdxHandle` RAII class in [src/gdxpds/tools.py](src/gdxpds/tools.py), used by all three create sites (`load_gdxcc` and `load_specials` via `with`; `GdxccEngine.__init__` keeps the instance). It encodes two SWIG hazards so callers don't have to:

doc/source/overview.md

@@ -293,7 +293,7 @@ If you prefer the simpler API that works with dicts of DataFrames, see [the `dom
 GAMS lets one Set be an *alias* of another — `alias(t, at)` makes `at` another name for set `t`. `gdxpds` surfaces the relationship on `GdxSymbol`:
 
 - `GdxSymbol.data_type` is {py:attr}`gdxpds.gdx.GamsDataType.Alias`, and the symbol reads like the Set it aliases (same elements, same element text).
-- `GdxSymbol.aliased_with` is the parent Set as a `GdxSymbol` reference (or `None` for non-aliases). Unlike a relaxed domain, an alias has no fallback: its parent must exist in the file when it is written, or the write raises {py:class}`gdxpds.DomainError`.
+- `GdxSymbol.alias_of` is the parent Set as a `GdxSymbol` reference (or `None` for non-aliases). Unlike a relaxed domain, an alias has no fallback: its parent must exist in the file when it is written, or the write raises {py:class}`gdxpds.DomainError`.
 
 **Viewing on read:**
 
@@ -303,10 +303,10 @@ with gdxpds.gdx.GdxFile(lazy_load=False) as gdx:
     gdx.read('data.gdx')
     at = gdx['at']
     print(at.data_type)                 # GamsDataType.Alias
-    print(at.aliased_with is gdx['t'])  # True — points at the parent Set
+    print(at.alias_of is gdx['t'])  # True — points at the parent Set
 ```
 
-**Setting on write.** Build the parent Set, then the alias — via {py:func}`gdxpds.gdx.append_alias` or a `GdxSymbol` with `aliased_with`:
+**Setting on write.** Build the parent Set, then the alias — via {py:func}`gdxpds.gdx.append_alias` or a `GdxSymbol` with `alias_of`:
 
 ```python
 import gdxpds.gdx
@@ -327,9 +327,9 @@ print(gdxpds.get_aliases('data.gdx'))   # {'at': 't'}
 ```
 
 :::{note}
-Aliases of a *named Set* (the common case) are fully supported on both engines. A **universe alias** — an alias of the universe set `*` (`aliased_with` resolves to the file's `universal_set`) — reads without error and round-trips within a single engine, but the engines disagree on its membership (`gdxcc` includes the `*` element, `gams.transfer` does not), so it is not cross-engine identical.
+Aliases of a *named Set* (the common case) are fully supported on both engines. A **universe alias** — an alias of the universe set `*` (`alias_of` resolves to the file's `universal_set`) — reads without error and round-trips within a single engine, but the engines disagree on its membership (`gdxcc` includes the `*` element, `gams.transfer` does not), so it is not cross-engine identical.
 
-**Chained aliases (alias of an alias)** are also supported: GDX itself permits a chain (`aat -> at -> t`), and both engines accept it on write and resolve `aliased_with` to a same-file symbol on read. The two engines differ on what reaches disk: the `gdxcc` engine preserves the chain (`aat -> at`), while `gams_transfer` flattens to the root (`aat -> t`). Either form reads back identically through `gdxpds`.
+**Chained aliases (alias of an alias)** are also supported: GDX itself permits a chain (`aat -> at -> t`), and both engines accept it on write and resolve `alias_of` to a same-file symbol on read. The two engines differ on what reaches disk: the `gdxcc` engine preserves the chain (`aat -> at`), while `gams_transfer` flattens to the root (`aat -> t`). Either form reads back identically through `gdxpds`.
 :::
 
 ### Parameter, Variable, and Equation details

src/gdxpds/_gdxcc_engine.py

@@ -114,7 +114,7 @@ def open_read(self, gdx_file: GdxFile, filename: str | os.PathLike[str]) -> None
         # No-op for well-formed files -- each in-line attempt already succeeded.
         for symbol in gdx_file:
             symbol.resolve_domain()
-            symbol.resolve_aliased_with()
+            symbol.resolve_alias_of()
 
     def _make_symbol(self, gdx_file: GdxFile, name: str, data_type, dims, index: int) -> GdxSymbol:
         """Construct a GdxSymbol and populate its extended gdxcc metadata."""
@@ -134,8 +134,8 @@ def _make_symbol(self, gdx_file: GdxFile, name: str, data_type, dims, index: int
             # resolve it to a same-file ref (open_read self-heals forward refs).
             pret, parent_name, _pdims, _pdtype = gdxcc.gdxSymbolInfo(H, userinfo)
             if pret == 1:
-                symbol._aliased_with_name = parent_name
-                symbol.resolve_aliased_with()
+                symbol._alias_of_name = parent_name
+                symbol.resolve_alias_of()
         symbol.description = description
         if index > 0:
             ret, gdx_domain = gdxcc.gdxSymbolGetDomainX(H, index)
@@ -264,10 +264,15 @@ def write_symbol(
         if symbol.data_type == GamsDataType.Alias:
             # An alias carries no records of its own; it is registered against its
             # parent Set, which must already be written (no relaxed fallback).
-            parent = symbol.aliased_with_name
+            # gdxAddAlias accepts the universe set "*" as a parent without any
+            # special-cased call, so a universe alias goes through the same path
+            # as a named-Set alias (cf. the gt.Alias / gt.UniverseAlias dispatch
+            # in the gams.transfer engine, which is needed because that library
+            # has separate types for the two cases).
+            parent = symbol.alias_of_name
             if parent is None:
                 raise DomainError(
-                    f"Cannot write alias {symbol.name!r}: no parent Set (aliased_with) is set."
+                    f"Cannot write alias {symbol.name!r}: no parent Set (alias_of) is set."
                 )
             if not gdxcc.gdxAddAlias(H, parent, symbol.name):
                 raise GdxError(

src/gdxpds/_transfer_engine.py

@@ -209,10 +209,10 @@ def _add_symbol(self, container, symbol: GdxSymbol, name_positions: dict) -> Non
         if data_type == GamsDataType.Alias:
             # An alias carries no records of its own; it points at its parent Set,
             # which must already be in the container (no relaxed fallback).
-            parent = symbol.aliased_with_name
+            parent = symbol.alias_of_name
             if parent is None:
                 raise DomainError(
-                    f"Cannot write alias {symbol.name!r}: no parent Set (aliased_with) is set."
+                    f"Cannot write alias {symbol.name!r}: no parent Set (alias_of) is set."
                 )
             universe = (
                 symbol.file.universal_set.name
@@ -302,7 +302,7 @@ def open_read(self, gdx_file: GdxFile, filename: str | os.PathLike[str]) -> None
         # the dependent symbol).
         for symbol in gdx_file:
             symbol.resolve_domain()
-            symbol.resolve_aliased_with()
+            symbol.resolve_alias_of()
 
     def _make_symbol(self, gdx_file: GdxFile, name: str, gt_sym, index: int) -> GdxSymbol:
         data_type = _data_type_of(gt_sym)
@@ -319,8 +319,8 @@ def _make_symbol(self, gdx_file: GdxFile, name: str, gt_sym, index: int) -> GdxS
             parent = getattr(gt_sym, "alias_with", None)
             parent_name = parent if isinstance(parent, str) else getattr(parent, "name", None)
             if parent_name is not None:
-                symbol._aliased_with_name = parent_name
-                symbol.resolve_aliased_with()
+                symbol._alias_of_name = parent_name
+                symbol.resolve_alias_of()
         # A non-wildcard domain entry (a Set reference) means a strict/regular
         # domain; mark it and resolve names to same-file GdxSymbol refs.
         if any(not isinstance(d, str) for d in gt_sym.domain):
@@ -345,7 +345,7 @@ def load_symbols(
             read_names = {s.name for s in targets}
             universe = gdx_file.universal_set.name if gdx_file.universal_set is not None else "*"
             for s in targets:
-                parent = s.aliased_with_name
+                parent = s.alias_of_name
                 if s.data_type == GamsDataType.Alias and parent and parent != universe:
                     read_names.add(parent)
             container = self._read_records(gdx_file, list(read_names)) if targets else None