From 5eeb583d4525cfc5da65d6f8283f777ae259a7ac Mon Sep 17 00:00:00 2001 From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com> Date: Thu, 4 Dec 2025 12:06:48 +0100 Subject: [PATCH] Rename and improve docs --- LICENSE | 2 +- Project.toml | 2 +- README.md | 41 +++++++++++++++---- ...hmarks.jl => MathOptBenchmarkInstances.jl} | 4 +- test/Project.toml | 5 ++- test/miplib2017.jl | 4 +- test/mittelmann.jl | 2 +- test/netlib.jl | 2 +- test/runtests.jl | 6 +-- 9 files changed, 47 insertions(+), 21 deletions(-) rename src/{MathProgBenchmarks.jl => MathOptBenchmarkInstances.jl} (80%) diff --git a/LICENSE b/LICENSE index 35b9198..0e9c87a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2025 JuliaDecisionFocusedLearning +Copyright (c) 2025 Guillaume Dalle Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/Project.toml b/Project.toml index 564eaa5..f226b09 100644 --- a/Project.toml +++ b/Project.toml @@ -1,4 +1,4 @@ -name = "MathProgBenchmarks" +name = "MathOptBenchmarkInstances" uuid = "f7f8d0a1-fd34-491e-a7ac-a4cf52f91fe5" version = "0.1.0" authors = ["Guillaume Dalle"] diff --git a/README.md b/README.md index dc8847f..a4005d0 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,50 @@ -# MathProgBenchmarks.jl +# MathOptBenchmarkInstances.jl A Julia package for automatic download and parsing of linear, quadratic and integer programming instances. -Supported datasets: +## Datasets + +Please read and abide by the license of the dataset you plan to use. + +### LP - [x] [Netlib](https://www.netlib.org/lp/data/index.html) -- [x] [MIPLIB 2017](https://miplib.zib.de/index.html) - [x] [Mittelmann LP benchmark](https://plato.asu.edu/ftp/lptestset/) +### MILP + +- [x] [MIPLIB 2017](https://miplib.zib.de/index.html) + +### QP + +- [ ] [QPLIB](https://qplib.zib.de/) +- [ ] [Maros-Meszaros](https://www.doc.ic.ac.uk/~im/#DATA) + ## Getting started -1. To see which instances are available, call `list_instances(dataset)` with `dataset in (Netlib, MIPLIB2017, MittelmannLP)`. -2. To read a specific instance, call `read_instance(dataset, name)` where `name isa String`. -3. The returned problem format is `QPSData` from [QPSReader.jl](https://github.com/JuliaSmoothOptimizers/QPSReader.jl). +1. To list the datasets available, call `values(Dataset)`. +2. To list the instances from a `dataset`, call `list_instances(dataset)`. +3. To read a specific instance given its `name`, call `read_instance(dataset, name)`. The return value is a tuple `(problem, path)` where `problem isa QPSData` from [QPSReader.jl](https://github.com/JuliaSmoothOptimizers/QPSReader.jl) and `path` points to the decompressed source file on your computer. -More details are available in the docstrings. +See the docstrings for details. ## Tips The problem source files are downloaded automatically thanks to [DataDeps.jl](https://github.com/oxinabox/DataDeps.jl). Note that each download has to be validated manually from the REPL. -This doesn't work well when the triggering line of code is executed with VSCode's Julia extension, better run it in the REPL directly. +This doesn't work well when the triggering line of code is executed with VSCode's Julia extension, you better run it in the REPL directly. An alternative is to set `ENV["DATADEPS_ALWAYS_ACCEPT"] = true`. The decompressed instances can be rather large (over 80 GB for the complete MIPLIB 2017 collection). -If you need to clean up some space, you can delete unneeded files inside the folder located at `MathProgBenchmarks.MPS_SCRATCH`. +If you need to clean up some space, you can delete unneeded files inside the folder located at `MathOptBenchmarkInstances.MPS_SCRATCH`. + +## Contributing + +To contribute a new dataset: + +1. Add its name to the `Dataset` enum. +2. Register a new `DataDep` inside the `__init__()` function of the package. +3. Implement a reader based on the files downloaded by the `DataDep`. This part might need decompression or file conversion steps, for which you can use the `MPS_SCRATCH` folder. +4. Write documentation and tests. + +You can (and should) draw inspiration from the implementation of existing datasets. diff --git a/src/MathProgBenchmarks.jl b/src/MathOptBenchmarkInstances.jl similarity index 80% rename from src/MathProgBenchmarks.jl rename to src/MathOptBenchmarkInstances.jl index 93495d4..07cb064 100644 --- a/src/MathProgBenchmarks.jl +++ b/src/MathOptBenchmarkInstances.jl @@ -1,4 +1,4 @@ -module MathProgBenchmarks +module MathOptBenchmarkInstances import CodecBzip2 using DataDeps @@ -17,4 +17,4 @@ export Dataset, MIPLIB2017, Netlib, MittelmannLP export read_instance export list_instances -end # module MathProgBenchmarks +end # module MathOptBenchmarkInstances diff --git a/test/Project.toml b/test/Project.toml index bacf46d..df973e6 100644 --- a/test/Project.toml +++ b/test/Project.toml @@ -1,5 +1,8 @@ [deps] Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595" -MathProgBenchmarks = "f7f8d0a1-fd34-491e-a7ac-a4cf52f91fe5" +MathOptBenchmarkInstances = "f7f8d0a1-fd34-491e-a7ac-a4cf52f91fe5" QPSReader = "10f199a5-22af-520b-b891-7ce84a7b1bd0" Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + +[sources] +MathOptBenchmarkInstances = {path = ".."} diff --git a/test/miplib2017.jl b/test/miplib2017.jl index d06fb93..d8880c2 100644 --- a/test/miplib2017.jl +++ b/test/miplib2017.jl @@ -1,11 +1,11 @@ -using MathProgBenchmarks +using MathOptBenchmarkInstances using QPSReader using Test miplib_list = list_instances(MIPLIB2017) @test length(miplib_list) == 1065 -miplib_benchmark_list = MathProgBenchmarks.list_miplib2017_instances(; benchmark_only = true) +miplib_benchmark_list = MathOptBenchmarkInstances.list_miplib2017_instances(; benchmark_only = true) @test length(miplib_benchmark_list) == 240 for name in miplib_benchmark_list[1:10] diff --git a/test/mittelmann.jl b/test/mittelmann.jl index 22f404d..25233ae 100644 --- a/test/mittelmann.jl +++ b/test/mittelmann.jl @@ -1,4 +1,4 @@ -using MathProgBenchmarks +using MathOptBenchmarkInstances using QPSReader using Test diff --git a/test/netlib.jl b/test/netlib.jl index 544e946..6766cf3 100644 --- a/test/netlib.jl +++ b/test/netlib.jl @@ -1,4 +1,4 @@ -using MathProgBenchmarks +using MathOptBenchmarkInstances using QPSReader using Test diff --git a/test/runtests.jl b/test/runtests.jl index 0152658..7b7d92e 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -1,12 +1,12 @@ using Aqua -using MathProgBenchmarks +using MathOptBenchmarkInstances using Test ENV["DATADEPS_ALWAYS_ACCEPT"] = true -@testset verbose = true "MathProgBenchmarks" begin +@testset verbose = true "MathOptBenchmarkInstances" begin @testset "Code quality" begin - Aqua.test_all(MathProgBenchmarks; undocumented_names = true) + Aqua.test_all(MathOptBenchmarkInstances; undocumented_names = true) end @testset "Netlib" begin include("netlib.jl")