Gyozas

A pure-Python reinforcement learning library for combinatorial optimization, built on top of PySCIPOpt and Gymnasium.

Gyozas provides a modular RL environment that lets you train agents to make decisions inside SCIP's branch-and-bound solver -- variable selection (branching) and node selection -- with pluggable rewards, observations, and problem instance generators.

Features

• Gymnasium-style API -- reset() / step() / render() interface
• Branching & node selection dynamics -- control variable branching or node selection decisions
• Bipartite graph observations -- LP-based features following Gasse et al. (NeurIPS 2019)
• Multiple reward functions -- node count, solving time, LP iterations, primal/dual integrals
• Built-in instance generators -- set cover, independent set, combinatorial auction, capacitated facility location
• Branch-and-bound tree visualization

Prerequisites

Gyozas requires the SCIP solver (version 8+). But latest version should be installed when PySCIPOpt is installed automatically with Gyozas dependencies

Installation

pip install gyozas

Or install from source:

pip install .

You can install extra packages for enhanced visualization of branch and bound tree state using

pip install "gyozas[viz]"

Quick Start

import gyozas

# Create an instance generator
instances = gyozas.SetCoverGenerator(n_rows=100, n_cols=200)

# Create the RL environment
env = gyozas.Environment(
    instance_generator=instances,
    observation_function=gyozas.NodeBipartite(),
    reward_function=gyozas.NNodes(),
)

# Run one episode
obs, action_set, reward, done, info = env.reset()
while not done:
    action = action_set[0]  # pick first available action
    obs, action_set, reward, done, info = env.step(action)

env.close()

Coming from Ecole?

Gyozas is a drop-in replacement for Ecole with a near-identical API:

See the full migration guide for detailed API mapping.

Components

Dynamics

• BranchingDynamics -- control variable selection in branching (default)
• NodeSelectionDynamics -- control which node to explore next
• ConfiguringDynamics -- single-step algorithm configuration (set SCIP params, then solve)
• PrimalSearchDynamics -- LP-probing primal heuristic; agent provides partial variable assignments
• ExtraBranchingActions -- sentinel actions (SKIP, CUT_OFF, REDUCE_DOMAIN) for branching

Rewards

• NNodes -- change in number of explored nodes
• SolvingTime -- wall-clock time per step
• LPIterations -- change in LP iterations
• DualIntegral / PrimalIntegral / PrimalDualIntegral -- bound integrals
• Done -- binary completion status
• ArithmeticMixin -- compose rewards with Python operators: -NNodes() * 0.5 + SolvingTime().cumsum()

Observations

• NodeBipartite / NodeBipartiteEcole -- pure-Python bipartite graph with configurable features
• NodeBipartiteSCIP -- thin wrapper around PySCIPOpt's built-in C implementation
• Pseudocosts -- per-variable pseudocost scores accumulated across branching history
• StrongBranchingScores -- full and partial strong-branching scores via LP probing

Instance Generators

• SetCoverGenerator -- random set cover problems
• IndependentSetGenerator -- random independent set problems
• CombinatorialAuctionGenerator -- random combinatorial auction problems
• CapacitatedFacilityLocationGenerator -- random facility location problems
• FileGenerator -- load instances from files on disk

Instance Modifiers

Modifiers wrap any generator and post-process the model before it reaches the environment:

• EmbedObjective -- embed the objective function as a variable + equality constraint
• SetParameters -- apply arbitrary SCIP parameters
• SetNoCuts / SetNoHeuristics / SetNoDisplay / SetDFSNodeSelection / SetBFSNodeSelection -- convenience presets

Gymnasium Wrapper

GymnasiumWrapper exposes any Environment as a standard Gymnasium environment, compatible with Stable-Baselines3, CleanRL, and other RL frameworks.

Tests

uv sync
uv run pytest

Contributors

License

MIT