# Sources Package

This folder contains the replication package for "Network Relaxations for Discrete Bilevel Optimization under Linear Interactions," submitted for consideration at INFORMS Operations Research.

The folder is organized around four main components:

- `code/`: Java source code for the network-based bilevel solver.
- `scripts/`: Python utilities for format conversion and feasibility checking.
- `results_tables_plots/`: results tables and a notebook for analysis and plotting. It also includes CSV files with results and instances considered, as described in the paper.
- `data_examples/`: small example instances in `.mps.gz` and `.aux` format. Full data is available at the BOBILib website, https://bobilib.org/

## Directory Tree

```text
sources/
|-- README.md
|-- code/
|   |-- BilevelDDOR_DISCRETE/
|   `-- BilevelDDOR_MIXED/
|-- data_examples/
|-- results_tables_plots/
|   |-- analysis.ipynb
|   |-- benchmark_info.csv
|   |-- collection-benchmark.csv
|   |-- results_Oct19_2025_cont.csv
|   `-- results_solvers_plus_dd_Mar24_2026_mibs_bc_augmented.csv
`-- scripts/
    |-- feasibility_checker/
    |   `-- feasibility_checker_website/
    |-- mps_aux_to_dd/
    |   `-- mps_aux_to_dd.py
    `-- mps_aux_to_legacy_aux/
        `-- mps_aux_to_legacy_aux.py
```

## Folder Overview

### `code/`

This folder contains the Java implementation of the network-based method in two variants. Both subfolders are provided as Eclipse-style Java projects and can be imported directly if that is the IDE of choice. They contain source code under `src/` and project metadata under `.project`, `.classpath`, and `.settings/`.


- `BilevelDDOR_DISCRETE/`: 
Solver for instances where the data are integer-valued and all variables are binary. 

- `BilevelDDOR_MIXED/`: 
Solver for general instances.

* Details on the difference between DISCRETE and MIXED: 
During revision rounds, we have also included BOBILib problems where both the leader and the follower could include general variable types (bounded continuous or general integers). To streamline implementation, we have created a separate MIXED version where internal data structures accommodated these special types (e.g., int64 to float64 variable types when designing network arc lengths). Both methods have exactly the same parameterizations (Section 6). Although MIXED works for all problem types, we recommend using DISCRETE for better performance on binary problems and when the data is integer.

#### How To Run the DD Solver

The shared `code/` directory contains source code only. The Java projects must be compiled first in an environment with the required IBM CPLEX/Concert dependencies (downloadable at the IBM website). The version considered in the paper is CPLEX 22.1.2. 

If creating `.jar` files, the main entry points are:

- `BilevelBOBILIB_DISCRETE.Main`
- `BilevelBOBILIB_MIXED.Main`

After compilation to "dd_solver_discrete.jar" or "dd_solver_mixed.jar," respectively, the command-line interface is:

```bash
java dd_solver_discrete.jar <fileName> <timeLimit> <numCores> <outputFolder> <algSwitch> <setWidth> <logicalCuts>
```

or

```bash
java dd_solver_mixed.jar <fileName> <timeLimit> <numCores> <outputFolder> <algSwitch> <setWidth> <logicalCuts>
```

Arguments:

1. `fileName`: path to the special input `.dd` instance. (Script to generate .dd files is included below)
2. `timeLimit`: time limit in seconds.
3. `numCores`: number of solver threads.
4. `outputFolder`: directory where the JSON solution file will be written.
5. `algSwitch`: solver mode (see below).
6. `setWidth`: network budget B. Use `0` to let the code select a default width heuristically.
7. `logicalCuts`: if cuts from Section 5.5 should be added (`true` or `false`).

Current solver modes used by the code:

- `0`: exact approach.
- `1`: root-only network; produces the root reformulation (see Section 6). If discrete, also exports it in MPS/AUX format.
- `2`: high-point relaxation only.
- `3`: high-point relaxation only, but augmented with cuts from Section 5.5.

Example shape of a run:

```bash
java dd_solver_discrete.jar path/to/instance.dd 3600 1 output 0 0 false
```

or

```bash
java dd_solver_mixed.jar path/to/instance.dd 3600 1 output 0 0 true
```

### `scripts/`

This folder contains helper scripts used to convert instances and validate solutions.

#### `mps_aux_to_dd/`

Contains:

- `mps_aux_to_dd.py`: converts one bilevel instance given as `.mps` or `.mps.gz` plus `.aux` into the custom `.dd` format used by the Java solver.

Usage:

```bash
python3 scripts/mps_aux_to_dd/mps_aux_to_dd.py \
  --mps_file path/to/instance.mps.gz \
  --aux_file path/to/instance.aux \
  --output_dir path/to/output_dir
```

Output:

- one `.dd` file written to the specified output directory.

#### `mps_aux_to_legacy_aux/`

Contains:

- `mps_aux_to_legacy_aux.py`: converts one bilevel instance given as `.mps` or `.mps.gz` plus `.aux` into the legacy `.laux` format.

Usage:

```bash
python3 scripts/mps_aux_to_legacy_aux/mps_aux_to_legacy_aux.py \
  --mps_file path/to/instance.mps.gz \
  --aux_file path/to/instance.aux \
  --output_dir path/to/output_dir
```

Output:

- one `.laux` file written to the specified output directory.

#### `feasibility_checker/`

Contains a bilevel feasibility-checking utility adapted to solution files in the website/JSON format used in this package.

Main contents:

- `feasibility_checker_website/feasibility_checker.py`: core feasibility-checking logic.
- `feasibility_checker_website/run_feasibility_checker_website.py`: small example driver.
- `feasibility_checker_website/readme_feasibility_checker_website.md`: additional setup notes.
- `feasibility_checker_website/test_instances/`: small test instance for the checker.
- `feasibility_checker_website/test_solutions/`: matching sample solution file.

The feasibility checker is provided by BOBILib and included for reference. It requires additional setup, in particular the MIPLIB 2017 solution checker. Please see:

- `scripts/feasibility_checker/feasibility_checker_website/readme_feasibility_checker_website.md`

Example run:

```bash
cd scripts/feasibility_checker/feasibility_checker_website
python3 run_feasibility_checker_website.py
```

### `data_examples/`

This folder contains representative example instances in `.mps.gz` and `.aux` format. These files can be used:

- as inputs to the conversion scripts,
- as small examples for testing the workflow, and
- as reference instances for reviewer inspection.

### `results_tables_plots/`

This folder contains supporting material for the computational results shown in Section 6, including generation of tables and plots:

- `analysis.ipynb`: notebook for analysis and plotting.
- `benchmark_info.csv`: open BOBILib problems tested in the paper (see Section 6)
- `collection-benchmark.csv`: data with statistics and information about BOBILib instances
- `results_Oct19_2025_cont.csv`: results table for Section 6.
- `results_solvers_plus_dd_Mar24_2026_mibs_bc_augmented.csv`: additional results table for Appendix B concerning integration of code.

## Typical Workflow

A typical use of the material in this folder is:

1. Start from an `.mps.gz` and `.aux` instance.
2. Convert it to `.dd` with `scripts/mps_aux_to_dd/mps_aux_to_dd.py`.
3. Compile the appropriate Java project in `code/`.
4. Run either the discrete or mixed DD solver on the generated `.dd` file.
5. Optionally use the feasibility checker to validate a produced solution.

## Notes

- The Java solver implementations depend on IBM CPLEX/Concert.
- The Python conversion scripts use Gurobi to read `.mps` and `.mps.gz` files.
- The feasibility checker uses Gurobi and the external MIPLIB 2017 solution checker.
