Stability Labels in Research Software: Why Beta and Experimental Matter

Research software often ships without clear signals about which parts are
stable and which are under active development. Users find out about breaking
changes the hard way: an upgrade breaks their experiment reproduction scripts.
TGraphX uses stability labels at the package level and in module documentation
as a mechanism to communicate this risk. This article examines what those
labels mean and why they matter for anyone building on top of a research
library.

The PyPI Stability Trident

Python packages can declare their development status using PyPI classifiers.
TGraphX's pyproject.toml includes:

Development Status :: 4 - Beta
        

This is a signal, not a guarantee. The full classifier scale is:

Beta means: the library does what it claims to do, but the API may change
between versions as design decisions are refined. Users should expect to read
the changelog when upgrading.

What Beta Means for TGraphX Specifically

For TGraphX v1.4.2:

• Core features (Graph, GraphBatch, TensorMessagePassingLayer) exist and work
• Some features are explicitly versioned within their Beta labels:
• set_seed with deterministic=True: Beta v0.4.1+
• read_graphml / write_graphml: Beta v1.2+
• OGBNodeEvaluator, run_v13_benchmark_suite: Beta v0.5.0+
• The API for these features may change in future versions

When you see "Beta v0.5.0+" next to a feature, it means that feature was
introduced in that version and is subject to the general Beta caveat about
API stability. It is not a production-stable API.

Module-Level Stability Notes

Within a package, different modules often have different stability levels.
A logging utility that has been in use for two years is more stable than an
experimental benchmark runner added last month. Good research software
documents this difference.

For TGraphX, modules with more recent feature additions (benchmarks, io) are
likely less stable than the core graph representation code (Graph, GraphBatch,
layers). Users who rely on run_v13_benchmark_suite should be more cautious
about upgrades than users who only use Graph and basic layers.

Stability Levels Relevant to TGraphX Modules

This table reflects reasonable inference from version labels and scope, not
official documentation.

Why Pinning Versions Matters

If you publish a paper or release code that depends on TGraphX, pin the version:

# requirements.txt
        tgraphx==1.4.2
        

Or in a conda environment file:

dependencies:
          - pip:
            - tgraphx==1.4.2
        

Without version pinning, a collaborator who installs your code three months
later may get a different version of TGraphX with a changed API, breaking your
reproduction scripts. This is a common source of reproducibility failures in
computational research.

The Difference Between "Experimental" and "Beta"

Some libraries distinguish between "Beta" (feature-complete, API may change)
and "Experimental" (may not work correctly, definitely will change). TGraphX
uses "Beta" as the top-level label. Individual modules without specific version
notes should be treated as Beta.

If a module is marked "experimental" in documentation or docstrings, treat
that as a stronger caution: the API and behavior may change significantly,
and the feature may be removed entirely.

Practical Workflow for Beta Research Software

Before adopting a new feature:
1. Check the version note (e.g., "Beta v0.5.0+")
2. Verify the feature exists in your installed version
3. Write a minimal test that exercises the feature with your data

Before upgrading:
1. Read the changelog
2. Run your test suite
3. If no test suite exists, run your experiment skeleton as a smoke test

Before publishing code that uses TGraphX:
1. Pin the version in your requirements file
2. Document the version in your README or experiment config
3. Use write_experiment_config to save the version alongside results:

from tgraphx.performance import env_report
        from tgraphx import write_experiment_config
        
        info = env_report(include_hardware=True)
        write_experiment_config({
            **info,
            "notes": "Using TGraphX Beta v1.4.2 — pin this version for reproduction",
        }, path="./logs/env.json")
        

What Stability Labels Are Not

Stability labels are not quality labels. A Beta package can be well-tested,
well-documented, and functionally correct. "Beta" communicates API evolution
risk, not code quality. Conversely, a package labeled "Production/Stable" can
have bugs — stability just means the interface is unlikely to change.

For TGraphX, the Beta label reflects honest positioning: it is a
research-engineering library in active development, and users should expect
the API to evolve. That is appropriate for its stage.