data_source_release.py

"""
This module includes the `get_sc_dict` function, which returns a dictionary containing paths of various scenarios, including their domain name, usage, and cutoff time. The scenarios are related to SAT and planning problems, and the features are stored in text files located in the specified `distnet_data_dir`.

This registry is the single source of truth for which scenarios exist: iterating
its keys is how ``globals.DISTNET_SCENARIOS`` (and therefore the ``--scenario``
CLI choices) is built. The mapping exists because the short names used in the
paper and on the command line differ from the directory names shipped in the
DistNet data archive.
"""


def get_sc_dict(distnet_data_dir):
    """Return the scenario registry for the released DistNet benchmark data.

    Each scenario pairs one randomised target algorithm with one instance
    distribution, and is stored on disk as a directory of runtime measurements
    plus a features file.

    Args:
        distnet_data_dir: Root of the extracted DistNet data (normally
            ``paths.DISTNET_DATA_DIR``). Only used to build absolute paths to
            the per-scenario ``features.txt`` files.

    Returns:
        dict: Keyed by the short scenario name used everywhere else in the
        project. Each value has the fields:

        - ``"scen"``: sub-directory of ``distnet_data_dir`` holding the runtime
          measurement CSVs for this scenario.
        - ``"features"``: absolute path to the instance-feature file, a CSV whose
          first column is the instance identifier and whose remaining columns are
          numeric features.
        - ``"domain"``: problem family the instances come from (``"sat"`` or
          ``"planning"``); informational only.
        - ``"use"``: which solver outcomes to retain. Every scenario here keeps
          only satisfiable instances (``("SAT",)``), so
          :func:`~tabpfn_project.helper.load_data.get_data` discards instances
          reported as ``UNSAT``.
        - ``"cutoff"``: the captime in seconds used when the runtime data was
          generated. Measurements are clipped to it on read, and instances that
          hit it (censored observations) are dropped, so every retained runtime
          is an uncensored measurement strictly below the cutoff.
    """
    sc_dict = {
        "clasp_factoring": {
            "scen": "clasp-3.0.4-p8_rand_factoring",
            "features": "%s/clasp-3.0.4-p8_rand_factoring/features.txt"
            % distnet_data_dir,
            "domain": "sat",
            "use": ("SAT",),
            "cutoff": 5000,
        },
        "saps-CVVAR": {
            "scen": "CP06_CV-VAR",
            "features": "%s/CP06_CV-VAR/features.txt" % distnet_data_dir,
            "domain": "sat",
            "use": ("SAT",),
            "cutoff": 60,
        },
        "spear_qcp": {
            "scen": "spear_qcp-hard",
            "features": "%s/spear_qcp-hard/features.txt" % distnet_data_dir,
            "domain": "sat",
            "use": ("SAT",),
            "cutoff": 5000,
        },
        "yalsat_qcp": {
            "scen": "yalsat_qcp-hard",
            "features": "%s/yalsat_qcp-hard/features.txt" % distnet_data_dir,
            "domain": "sat",
            "use": ("SAT",),
            "cutoff": 5000,
        },
        "spear_swgcp": {
            "scen": "spear_smallworlds",
            "features": "%s/spear_smallworlds/features.txt" % distnet_data_dir,
            "domain": "sat",
            "use": ("SAT",),
            "cutoff": 5000,
        },
        "yalsat_swgcp": {
            "scen": "yalsat_smallworlds",
            "features": "%s/yalsat_smallworlds/features.txt" % distnet_data_dir,
            "domain": "sat",
            "use": ("SAT",),
            "cutoff": 5000,
        },
        "lpg-zeno": {
            "scen": "lpg-zenotravel",
            "features": "%s/lpg-zenotravel/features.txt" % distnet_data_dir,
            "domain": "planning",
            "use": ("SAT",),
            "cutoff": 300,
        },
    }
    return sc_dict