From 6bde748268c579a635c81ccd8c0afe50d9cce0b5 Mon Sep 17 00:00:00 2001 From: Oscar Dowson Date: Tue, 19 Sep 2023 09:35:26 +1200 Subject: [PATCH] [docs] add links to the various data files in tutorials (#3512) --- .../cutting_stock_column_generation.jl | 2 +- .../getting_started/data/knapsack.json | 10 --- .../data/knapsack_infeasible.json | 10 --- .../design_patterns_for_larger_models.jl | 71 ++++++++++++------- .../getting_started_with_data_and_plotting.jl | 6 +- docs/src/tutorials/linear/factory_schedule.jl | 17 +++-- docs/src/tutorials/linear/multi.jl | 11 ++- .../linear/multi_commodity_network.jl | 9 ++- 8 files changed, 78 insertions(+), 58 deletions(-) delete mode 100644 docs/src/tutorials/getting_started/data/knapsack.json delete mode 100644 docs/src/tutorials/getting_started/data/knapsack_infeasible.json diff --git a/docs/src/tutorials/algorithms/cutting_stock_column_generation.jl b/docs/src/tutorials/algorithms/cutting_stock_column_generation.jl index 3eac6bfef0b..93e2623e2d1 100644 --- a/docs/src/tutorials/algorithms/cutting_stock_column_generation.jl +++ b/docs/src/tutorials/algorithms/cutting_stock_column_generation.jl @@ -237,7 +237,7 @@ set_silent(model) optimize!(model) solution_summary(model) -# This solution requires 421 rolls. This solution is sub-optimmal because the +# This solution requires 421 rolls. This solution is sub-optimal because the # model does not contain the full set of possible patterns. # How do we find a new column that leads to an improved solution? diff --git a/docs/src/tutorials/getting_started/data/knapsack.json b/docs/src/tutorials/getting_started/data/knapsack.json deleted file mode 100644 index f1c7c54fed5..00000000000 --- a/docs/src/tutorials/getting_started/data/knapsack.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "objects": { - "apple": {"profit": 5.0, "weight": 2.0}, - "banana": {"profit": 3.0, "weight": 8.0}, - "cherry": {"profit": 2.0, "weight": 4.0}, - "date": {"profit": 7.0, "weight": 2.0}, - "eggplant": {"profit": 4.0, "weight": 5.0} - }, - "capacity": 10.0 -} diff --git a/docs/src/tutorials/getting_started/data/knapsack_infeasible.json b/docs/src/tutorials/getting_started/data/knapsack_infeasible.json deleted file mode 100644 index 4572fe7813d..00000000000 --- a/docs/src/tutorials/getting_started/data/knapsack_infeasible.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "objects": { - "apple": {"profit": 5.0, "weight": 2.0}, - "banana": {"profit": 3.0, "weight": 8.0}, - "cherry": {"profit": 2.0, "weight": 4.0}, - "date": {"profit": 7.0, "weight": 2.0}, - "eggplant": {"profit": 4.0, "weight": 5.0} - }, - "capacity": -10.0 -} diff --git a/docs/src/tutorials/getting_started/design_patterns_for_larger_models.jl b/docs/src/tutorials/getting_started/design_patterns_for_larger_models.jl index f7948c1c4b0..ea9530beccb 100644 --- a/docs/src/tutorials/getting_started/design_patterns_for_larger_models.jl +++ b/docs/src/tutorials/getting_started/design_patterns_for_larger_models.jl @@ -170,18 +170,23 @@ solve_knapsack_2(data) # to hard-code the data into Julia. A good next step is to separate the data # into an external file format; JSON is a common choice. -# The JuMP repository [has a file](https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/tutorials/getting_started/data/knapsack.json) -# we're going to use for this tutorial. To run this tutorial locally, download -# the file and then update `data_filename` as appropriate. - -# To build this version of the JuMP documentation, we needed to set the -# filename: - -data_filename = joinpath(@__DIR__, "data", "knapsack.json"); - -# `knapsack.json` has the following contents: - -println(read(data_filename, String)) +json_data = """ +{ + "objects": { + "apple": {"profit": 5.0, "weight": 2.0}, + "banana": {"profit": 3.0, "weight": 8.0}, + "cherry": {"profit": 2.0, "weight": 4.0}, + "date": {"profit": 7.0, "weight": 2.0}, + "eggplant": {"profit": 4.0, "weight": 5.0} + }, + "capacity": 10.0 +} +""" +temp_dir = mktempdir() +knapsack_json_filename = joinpath(temp_dir, "knapsack.json") +## Instead of writing a new file here you could replace `knapsack_json_filename` +## with the path to a local file. +write(knapsack_json_filename, json_data); # Now let's write a function that reads this file and builds a `KnapsackData` # object: @@ -199,7 +204,7 @@ function read_data(filename) ) end -data = read_data(data_filename) +data = read_data(knapsack_json_filename) # ## Add options via if-else @@ -394,8 +399,11 @@ function solve_knapsack_6( return solve_knapsack_6(optimizer, read_data(data), config) end -solution = - solve_knapsack_6(HiGHS.Optimizer, data_filename, BinaryKnapsackConfig()) +solution = solve_knapsack_6( + HiGHS.Optimizer, + knapsack_json_filename, + BinaryKnapsackConfig(), +) # ## Create a module @@ -521,7 +529,7 @@ end """ solve_knapsack( optimizer, - data_filename::String, + knapsack_json_filename::String, config::_AbstractConfiguration, ) @@ -531,7 +539,7 @@ Solve the knapsack problem and return the optimal primal solution * `optimizer` : an object that can be passed to `JuMP.Model` to construct a new JuMP model. - * `data_filename` : the filename of a JSON file containing the data for the + * `knapsack_json_filename` : the filename of a JSON file containing the data for the problem. * `config` : an object to control the type of knapsack model constructed. Valid options are: @@ -565,10 +573,11 @@ solution = solve_knapsack( """ function solve_knapsack( optimizer, - data_filename::String, + knapsack_json_filename::String, config::_AbstractConfiguration, ) - return _solve_knapsack(optimizer, _read_data(data_filename), config) + data = _read_data(knapsack_json_filename) + return _solve_knapsack(optimizer, data, config) end end @@ -579,7 +588,7 @@ import .KnapsackModel KnapsackModel.solve_knapsack( HiGHS.Optimizer, - joinpath(@__DIR__, "data", "knapsack.json"), + knapsack_json_filename, KnapsackModel.BinaryKnapsackConfig(), ) @@ -605,7 +614,7 @@ using Test @testset "feasible_binary_knapsack" begin x = KnapsackModel.solve_knapsack( HiGHS.Optimizer, - joinpath(@__DIR__, "data", "knapsack.json"), + knapsack_json_filename, KnapsackModel.BinaryKnapsackConfig(), ) @test isapprox(x["apple"], 1, atol = 1e-5) @@ -617,7 +626,7 @@ using Test @testset "feasible_integer_knapsack" begin x = KnapsackModel.solve_knapsack( HiGHS.Optimizer, - joinpath(@__DIR__, "data", "knapsack.json"), + knapsack_json_filename, KnapsackModel.IntegerKnapsackConfig(), ) @test isapprox(x["apple"], 0, atol = 1e-5) @@ -627,10 +636,24 @@ using Test @test isapprox(x["eggplant"], 0, atol = 1e-5) end @testset "infeasible_binary_knapsack" begin + dir = mktempdir() + infeasible_filename = joinpath(dir, "infeasible.json") + write( + infeasible_filename, + """{ + "objects": { + "apple": {"profit": 5.0, "weight": 2.0}, + "banana": {"profit": 3.0, "weight": 8.0}, + "cherry": {"profit": 2.0, "weight": 4.0}, + "date": {"profit": 7.0, "weight": 2.0}, + "eggplant": {"profit": 4.0, "weight": 5.0} + }, + "capacity": -10.0 + }""", + ) x = KnapsackModel.solve_knapsack( HiGHS.Optimizer, - ## This file contains data that makes the problem infeasible. - joinpath(@__DIR__, "data", "knapsack_infeasible.json"), + infeasible_filename, KnapsackModel.BinaryKnapsackConfig(), ) @test x === nothing diff --git a/docs/src/tutorials/getting_started/getting_started_with_data_and_plotting.jl b/docs/src/tutorials/getting_started/getting_started_with_data_and_plotting.jl index bd0537ad5f2..c977d57c5b9 100644 --- a/docs/src/tutorials/getting_started/getting_started_with_data_and_plotting.jl +++ b/docs/src/tutorials/getting_started/getting_started_with_data_and_plotting.jl @@ -34,7 +34,11 @@ # Before we get started, we need this constant to point to where the data files # are. -const DATA_DIR = joinpath(@__DIR__, "data") +import JuMP +const DATA_DIR = joinpath( + dirname(pathof(JuMP)), + joinpath("..", "docs", "src", "tutorials", "getting_started", "data"), +); # ## Where to get help diff --git a/docs/src/tutorials/linear/factory_schedule.jl b/docs/src/tutorials/linear/factory_schedule.jl index de05c2bf048..f034a93532b 100644 --- a/docs/src/tutorials/linear/factory_schedule.jl +++ b/docs/src/tutorials/linear/factory_schedule.jl @@ -86,14 +86,14 @@ import Test #src # production and cost levels for each month. For the documentation, the file is # located at: -factories_filename = joinpath(@__DIR__, "factory_schedule_factories.txt") +factories_filename = joinpath(@__DIR__, "factory_schedule_factories.txt"); -# and it has the following contents: +# To run locally, download [`factory_schedule_factories.txt`](factory_schedule_factories.txt) +# and update `factories_filename` appropriately. -print(read(factories_filename, String)) +# The file has the following contents: -# You can reproduce this tutorial locally by saving the contents to a new file -# and updating `factories_filename` appropriately. +print(read(factories_filename, String)) # We use the `CSV` and `DataFrames` packages to read it into Julia: @@ -106,11 +106,10 @@ factory_df = CSV.read( # The second file contains the demand data by month: -demand_filename = joinpath(@__DIR__, "factory_schedule_demand.txt") +demand_filename = joinpath(@__DIR__, "factory_schedule_demand.txt"); -print(read(demand_filename, String)) - -#- +# To run locally, download [`factory_schedule_demand.txt`](factory_schedule_demand.txt) +# and update `demand_filename` appropriately. demand_df = CSV.read( demand_filename, diff --git a/docs/src/tutorials/linear/multi.jl b/docs/src/tutorials/linear/multi.jl index 17f2e80d700..91cef976613 100644 --- a/docs/src/tutorials/linear/multi.jl +++ b/docs/src/tutorials/linear/multi.jl @@ -58,9 +58,16 @@ const DBInterface = SQLite.DBInterface # ## Data # For the purpose of this tutorial, the JuMP repository contains an example -# database called `multi.sqlite`: +# database called `multi.sqlite`. -db = SQLite.DB(joinpath(@__DIR__, "multi.sqlite")) +filename = joinpath(@__DIR__, "multi.sqlite"); + +# To run locally, download [`multi.sqlite`](multi.sqlite) and update `filename` +# appropriately. + +# Load the database using `SQLite.DB`: + +db = SQLite.DB(filename) # A quick way to see the schema of the database is via `SQLite.tables`: diff --git a/docs/src/tutorials/linear/multi_commodity_network.jl b/docs/src/tutorials/linear/multi_commodity_network.jl index 5fb84167f4b..3f6f234a76b 100644 --- a/docs/src/tutorials/linear/multi_commodity_network.jl +++ b/docs/src/tutorials/linear/multi_commodity_network.jl @@ -56,7 +56,14 @@ import Test #src # For the purpose of this tutorial, the JuMP repository contains an example # database called `commodity_nz.db`: -db = SQLite.DB(joinpath(@__DIR__, "commodity_nz.db")) +filename = joinpath(@__DIR__, "commodity_nz.db"); + +# To run locally, download [`commodity_nz.db`](commodity_nz.db) and update +# `filename` appropriately. + +# Load the database using `SQLite.DB`: + +db = SQLite.DB(filename) # A quick way to see the schema of the database is via `SQLite.tables`: