Assortment Optimization Under History-Dependent Effects

---

Description of Software and Data

The goal of this repository is to replicate the numerical experiments and case study in the paper "Assortment Optimization Under History-Dependent Effects" by Taotao He, Yating Zhang, and Huan Zheng. This repository is also available via GitHub at https://github.com/ORJournal/2024.1273.

What Is Reproduced

This replication package reproduces the numerical studies and the menu-optimization case study reported in the paper. Numerical-study scripts reproduce Tables 1, 3–6, and EC.2–EC.4. Case-study scripts reproduce Table 2 and the figures in Section 5.

What Is NOT Reproduced Directly

• Raw company case-study data: The raw data cannot be released because of company data restrictions. The repository provides simulated data constructed from a randomly selected month of real assortments and product features, with consumer choice behavior simulated using the estimated utility functions from the paper.
• External solver software and licenses: Gurobi, MOSEK, and optional custom SCIP installations must be installed and licensed by the user. These solvers are not redistributed in the repository.
• Full-scale numerical runs by default: Because some experiments are computationally expensive, the default numerical replication uses a representative subset of instances. Full tables can be reproduced by using the --mode full option.

---

Repository Contents

The README identifies the main project folders and files as follows:

Location	Description
src/	Optimization models and algorithms developed in the paper.
scripts/	Numerical-study, estimation, optimization, and plotting scripts.
data/	Data used for numerical studies and simulated input data for the case study.
results/	Generated XLSX files, summaries, logs, estimation results, and figures.
results_map.txt	Mapping between scripts, output folders, and paper tables.
expected_time.txt	Expected running times for the default representative-subset replication.
Project.toml / Manifest.toml	Julia package environment files.
requirements.txt	Python package requirements for the case-study scripts.

---

System Requirements & Dependencies

Julia

• Julia 1.10.10 is recommended for the archived replication environment.
• Julia is required for all numerical studies and for the case-study optimization step.

Python

• Python 3.12.3 is recommended for the case-study estimation and plotting scripts.
• Python is not required to reproduce the numerical studies only.

Solvers

Solver	Version / Requirement	Notes
Gurobi	11.0.0	Requires a valid commercial or academic license. Set GRB_LICENSE_FILE if the license is not in the default location.
MOSEK	10.2	Recommended for reproducibility because newer versions may produce numerical stability issues for MIECP problems on some architectures.
SCIP	Julia artifact, or optional SCIP 9.0.0 custom installation	SCIP.jl typically downloads a precompiled binary automatically. If using a custom installation, configure SCIPOPTDIR.

---

Quick Start

Working-directory rule: Run all commands from the repository root so relative paths correctly resolve imports from the src/ and data/ folders.

1. Install Julia dependencies

   julia --project=. -e "import Pkg; Pkg.instantiate()"

2. If using a different Julia version

   julia --project=. -e "import Pkg; Pkg.resolve(); Pkg.instantiate()"

   Before running this command, delete Manifest.toml. Julia will resolve dependencies from Project.toml, but package versions, running times, and numerical results may differ slightly from the archived environment.

3. Create and activate the Python environment for the case study

   python -m venv venv
   source venv/bin/activate
   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt

   On Windows, activate the environment with .\venv\scripts\activate.

---

Replication Workflow (Step-by-Step)

1. Replicate Numerical Studies Only

The numerical-study replication uses Julia only. Generated XLSX files, summaries, and logs are written to script-specific subfolders under results/.

Default representative-subset mode:

julia --project=. reproduce_numerical.jl

Full-table mode:

julia --project=. reproduce_numerical.jl --mode full

The default mode reproduces a representative subset because individual instances may take several hours. Use --mode full to reproduce all instances used for the full numerical-study tables.

2. Replicate the Case Study

The case study uses a Python + Julia pipeline: estimation in Python, optimization in Julia, and plotting in Python. Estimation results and figures are written to results/case_study/.

python reproduce_case_study.py

Note: The bootstrap step in estimation and the menu-optimization step both take hours to run.

---

Script-to-Output Mapping

The table below summarizes the individual commands provided for reproducing specific paper outputs.

Paper Output	Command
Table 1, Section 4.3	julia --project=. scripts/Table1_Sec4_3.jl
Tables 3 and 4, Section 6.1	julia --project=. scripts/Table3_4_Sec6_1_CompareModel.jl
Table 5, Section 6.2	julia --project=. scripts/Table5_Sec6_2_Heuristic.jl
Table 6, Section 6.3	julia --project=. scripts/Table6_Sec6_3_Cyclic.jl
Table EC2, Section EC.6.1	julia --project=. scripts/TableEC2_ec6_1_Constraints.jl
Table EC3, Section EC.6.2	julia --project=. scripts/TableEC3_ec_6_2_LargeM.jl
Table EC4, Section EC.6.3	julia --project=. scripts/TableEC4_ec_6_3_CyclicRevenue.jl
Table 2, Section 5.1	python scripts/Case_estimation.py
Figures in Section 5	julia --project=. scripts/Case_5_2_optimization.jl, then python scripts/Case_plot.py

For numerical-study commands, append --mode full to reproduce the entire table where applicable.

---

Case Study Data Note

The raw company data used in the case study cannot be released. The repository instead provides simulated data generated by:

1. Randomly selecting one month of real data and retaining only the daily assortments and product features from that period.
2. Simulating daily consumer choice behavior using the paper's estimated utility functions in a multinomial logit model.

The simulated data uses the utility function with memory length M = 3, which the authors identify as having the best predictive performance.

---

Hardware and Runtime Notes

• The paper results were computed on a virtual machine with a 32-core Intel Xeon Skylake, IBRS, 2.39 GHz processor and 128 GB RAM.
• For successful replication, the authors recommend running numerical experiments sequentially, with no other memory-intensive programs running and at least 7.5 GB RAM available.
• Running scripts directly from the command line is preferred over interactive environments.
• The default mode uses a subset of instances; expected times are listed in expected_time.txt.
• The scripts automatically disable sleep mode during execution to avoid incorrect logging of running time or solved instances. The authors also recommend manually ensuring that the screen stays on and the system does not enter sleep mode.

---

Notes on Cross-Machine Reproducibility

Optimization results and running times may vary depending on hardware specifications, solver configuration, and package versions. The repository includes additional README files under the corresponding results/ folders to explain possible discrepancies between replicated outputs and the paper tables.

For closer reproducibility, use the recommended Julia, Python, solver, and package versions; run from the repository root; run experiments sequentially; and avoid memory-intensive background processes.

---

Support

For support using this software, open an issue in the GitHub repository: https://github.com/ORJournal/2024.1273/issues.

---

Cite

To cite the contents of this repository, please cite both the paper and this software-and-data repository, using their respective DOIs.

• Article: https://doi.org/10.1287/opre.2024.1273
• Software and Data Repository: https://doi.org/10.1287/opre.2024.1273.cd

Below is the BibTeX for citing this snapshot of the repository.

@misc{he2026hap,
  author =        {He, Taotao and Zhang, Yating and Zheng, Huan},
  publisher =     {Operations Research},
  title =         {{Assortment Optimization Under History-Dependent Effects}},
  year =          {2026},
  doi =           {10.1287/opre.2024.1273.cd},
  url =           {https://github.com/ORJournal/2024.1273},
}

---