Merge branch 'develop' into feature/20250625-IntegrationWithJuMP

Author: gkantsidis

Project.toml

@@ -1,7 +1,7 @@
 name = "AOCoptimizer"
 uuid = "ba4aa9bd-6938-48c2-966f-258481ba1c4a"
 authors = ["Kirill Kalinin <kkalinin@microsoft.com>", "Christos Gkantsidis <chrisgk@microsoft.com>"]
-version = "0.1.0"
+version = "0.2.1"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

docs/src/manual/installation.md

@@ -1,6 +1,90 @@
 # Installation
 
-TODO: Provide installation instructions for the package.
-    In addition, add steps to test that installation has been successful
-    both when CUDA is and is not used, document installation problems and
-    differences between platforms.
+## Prerequisites
+
+In case you don't have Julia installed, please refer to the
+[Julia installation guide](https://julialang.org/install/).
+(Although the easiest way is to use the Julia installer directly,
+it's better to follow the instructions from the installation guide.)
+
+If you have not used Julia before, you may want to create a new
+project from which you will use the `AOCoptimizer` package.
+Start Julia in your working directory with `julia`and run the following commands
+(they will create a new directory called `MyProject`, and initialize
+the project in it):
+
+```julia
+using Pkg
+Pkg.generate("MyProject")
+```
+
+(A better way to create a new project is by using the
+[PkgSkeleton.jl](https://github.com/tpapp/PkgSkeleton.jl) package.
+
+If you want to use CUDA, you will also need to make sure that
+the drivers for your GPU are installed and that the CUDA Toolkit
+is available on your system. You can find the installation instructions
+on the [NVIDIA CUDA Toolkit page](https://developer.nvidia.com/cuda-downloads).
+
+## Adding `AOCoptimizer.jl` to your project
+
+(If you have just created a new project, with the instructions above,
+make sure to `cd` into the `MyProject` directory first and then start Julia
+with `julia --project`, or alternatively activate the new project from
+inside Julia with `Pkg.activate("MyProject")`.)
+
+Add the `AOCoptimizer` package to your project by running the following command
+(make sure you have used `using Pkg` first):
+
+```julia
+Pkg.add(url="https://github.com/microsoft/AOCoptimizer.jl")
+```
+
+If the above does not work with the error
+`ERROR: invalid git HEAD (reference 'refs/head/master' not found)`
+please try the following:
+
+```julia
+Pkg.dev(url="https://github.com/microsoft/AOCoptimizer.jl#main")
+```
+
+If you also want to use `CUDA` or `JuMP`,
+you should also install the corresponding packages.
+For the case of `CUDA`, run:
+
+```julia
+Pkg.add("CUDA")
+```
+
+For `JuMP`, run:
+
+```julia
+Pkg.add("JuMP")
+Pkg.add("MathOptInterface")
+```
+
+Verify that the `AOCoptimizer` package is installed correctly by running:
+
+```julia
+Pkg.test("AOCoptimizer")
+```
+
+## Adding `AOCoptimizer.jl` as a dependency to your project
+
+The approach described in the previous section works for projects
+that either add the `Manifest.toml` file to the repository (in general not recommended),
+or for projects that don't use version control at all. The reason is that
+the `URL` of the `AOCoptimizer` package doesn't appear in the `Project.toml` file,
+hence, creating problems for other developers who want to use the project
+that depends on `AOCoptimizer`.
+
+Instead, for such projects manually modify your `Project.toml` file to contain
+the following statements:
+
+```toml
+[deps]
+AOCoptimizer = "ba4aa9bd-6938-48c2-966f-258481ba1c4a"
+
+[sources]
+AOCoptimizer = {url = "https://github.com/microsoft/AOCoptimizer.jl"}
+```

docs/src/reference/reference.md

@@ -174,15 +174,15 @@ Solver.@make_sampler
 ```
 
 ```@docs
-Solver.sample!
+Solver.sample_mixed_ising!
 ```
 
 ```@docs
 Solver.sample_qumo!
 ```
 
 ```@docs
-Solver.sample_binary!
+Solver.sample_positive_qumo!
 ```
 
 ```@docs
@@ -194,7 +194,11 @@ Solver.SamplerTracer.SamplerWithPlan
 ```
 
 ```@docs
-Solver.sample_with_tracer!
+Solver.sample_qumo_with_tracer!
+```
+
+```@docs
+Solver.sample_mixed_ising_with_tracer!
 ```
 
 ### Exploration
@@ -204,15 +208,15 @@ Solver.@make_exploration
 ```
 
 ```@docs
-Solver.explore
+Solver.explore_mixed_ising
 ```
 
 ```@docs
 Solver.explore_qumo
 ```
 
 ```@docs
-Solver.explore_binary
+Solver.explore_positive_qumo
 ```
 
 ```@docs
@@ -284,15 +288,15 @@ Solver.@make_solver
 ```
 
 ```@docs
-Solver.solve
+Solver.solve_mixed_ising
 ```
 
 ```@docs
 Solver.solve_qumo
 ```
 
 ```@docs
-Solver.solve_binary
+Solver.solve_positive_qumo
 ```
 
 ```@docs

docs/src/tutorials/example.md

@@ -24,7 +24,8 @@ using Dates
 using JSON
 using AOCoptimizer
 using AOCoptimizer: graph_cut_from_hamiltonian
-using AOCoptimizer.Solver: solve, find_best, get_solver_results_summary
+using AOCoptimizer.Solver: solve_mixed_ising, find_best
+using AOCoptimizer.Solver: get_solver_results_summary
 
 # Necessary to explicitly initialize the AOCoptimizer package
 AOCoptimizer.init()
@@ -38,7 +39,7 @@ graph = Float32.([
 ])
 
 # observe that we optimize the negative of the adjacency matrix of the graph
-sol = solve(Float32, -graph, Second(10))
+sol = solve_mixed_ising(Float32, -graph, Second(10))
 best = find_best(sol)
 cut = graph_cut_from_hamiltonian(graph, best.Objective)
 println("Energy: ", best.Objective, "; Cut: ", cut)
@@ -74,7 +75,7 @@ while the last four variables are continuous (in the range ``[-1, 1]``).
 ```@example MixedIsing
 using Dates
 using AOCoptimizer
-using AOCoptimizer.Solver: solve, find_best
+using AOCoptimizer.Solver: solve_mixed_ising, find_best
 
 AOCoptimizer.init()
 
@@ -100,7 +101,7 @@ q = Float32.([
         145
 ])
 
-sol = solve(Float32, Q, q, number_of_binaries, Second(10))
+sol = solve_mixed_ising(Float32, Q, q, number_of_binaries, Second(10))
 best = find_best(sol)
 ```
 
@@ -118,6 +119,16 @@ println("Continuous: ", best.Vars[number_of_binaries+1:end])
 
 ## Solving a simple `QUMO` problem
 
+Let's solve now a simple optimization problem that combines
+both binary and continuous variables (`QUMO`). In the example
+below, we have 3 binary variables and 4 continuous variables.
+Using the default interface, it is expected that the first
+variables are binary; e.g., in the example below, the
+variable `number_of_binaries` signifies that the first 3 variables
+are binary, and this parameter is passed to the `solve_qumo` function.
+Moreover, it is expected that the first `number_of_binaries` diagonal
+elements of the matrix `Q` are zero.
+
 ```@example QUMO
 using Dates
 using AOCoptimizer

notebooks/benchmark-clamping.jl

@@ -162,7 +162,7 @@ cpu_y = rand(T, matrix_size, experiments);
 @benchmark AOCoptimizer.Solver.enforce_inelastic_wall_ising!(cpu_x)
 
 # The binary shortcut to the walls
-@benchmark AOCoptimizer.Solver.enforce_inelastic_wall_binary!(cpu_x)
+@benchmark AOCoptimizer.Solver.enforce_inelastic_wall_positive!(cpu_x)
 
 # ### Two arrays: the inelastic wall implementation with clamp
 @benchmark combine_clamp!(cpu_x, cpu_y)
@@ -182,7 +182,7 @@ cpu_y = rand(T, matrix_size, experiments);
 @benchmark AOCoptimizer.Solver.enforce_inelastic_wall_ising!(cpu_x, cpu_y)
 
 # The binary shortcut to the walls
-@benchmark AOCoptimizer.Solver.enforce_inelastic_wall_binary!(cpu_x, cpu_y)
+@benchmark AOCoptimizer.Solver.enforce_inelastic_wall_positive!(cpu_x, cpu_y)
 
 # ## GPU based implementations
 
@@ -364,7 +364,7 @@ end
 
 # The binary shortcut to the walls
 CUDA.@bprofile begin
-    AOCoptimizer.Solver.enforce_inelastic_wall_binary!(gpu_x)
+    AOCoptimizer.Solver.enforce_inelastic_wall_positive!(gpu_x)
     CUDA.synchronize()
 end
 
@@ -401,7 +401,7 @@ end
 
 # The binary shortcut to the walls
 CUDA.@bprofile begin
-    AOCoptimizer.Solver.enforce_inelastic_wall_binary!(gpu_x, gpu_y)
+    AOCoptimizer.Solver.enforce_inelastic_wall_positive!(gpu_x, gpu_y)
     CUDA.synchronize()
 end
 

notebooks/benchmark-exploration.jl

@@ -45,7 +45,7 @@ setup = AOCoptimizer.Solver.make_setup(annealing, gradient, momentum, dt, 16);
 # ## Run in the CPU
 
 @benchmark begin
-    result = AOCoptimizer.Solver.explore(
+    result = AOCoptimizer.Solver.explore_mixed_ising(
         problem,
         setup,
         batch_size,
@@ -67,7 +67,7 @@ CUDA.synchronize();
 # Benchmark the exploration function in the GPU
 # (here we avoid the use `CUDA.@bprofile`, which seems to not work correctly).
 
-g_result = AOCoptimizer.Solver.explore(
+g_result = AOCoptimizer.Solver.explore_mixed_ising(
     g_problem,
     g_setup,
     batch_size,
@@ -79,7 +79,7 @@ g_result = AOCoptimizer.Solver.explore(
 CUDA.synchronize();
 
 CUDA.@time begin
-    g_result = AOCoptimizer.Solver.explore(
+    g_result = AOCoptimizer.Solver.explore_mixed_ising(
         g_problem,
         g_setup,
         batch_size,

notebooks/benchmark-sampler.jl

@@ -53,10 +53,10 @@ delta = annealing / iterations;
 dt = T(0.1);
 
 # Default sampler
-@benchmark Solver._sample_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
+@benchmark Solver._sample_mixed_ising_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
 
 # Binary sampler
-@benchmark Solver._sample_binary_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
+@benchmark Solver._sample_positive_qumo_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
 
 # QUMO sampler
 @benchmark Solver._sample_qumo_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
@@ -91,13 +91,13 @@ dt = T(0.1);
 
 # Default sampler
 CUDA.@bprofile begin
-    Solver._sample_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
+    Solver._sample_mixed_ising_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
     CUDA.synchronize()
 end
 
 # Binary sampler
 CUDA.@bprofile begin
-    Solver._sample_binary_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
+    Solver._sample_positive_qumo_internal!(interactions, nothing, binaries, gradient, momentum, x, y, fields, spins, annealing, delta, dt, iterations)
     CUDA.synchronize()
 end
 

notebooks/benchmark-solver.jl

@@ -33,15 +33,15 @@ graph = create_random_graph(T, n);
 engine_cpu = AOCoptimizer.Solver.EngineLocalCpu();
 engine_gpu = AOCoptimizer.Solver.EngineCuda(0);
 
-# sol = AOCoptimizer.Solver.solve(Float32, graph, Second(60));
+# sol = AOCoptimizer.Solver.solve_mixed_ising(Float32, graph, Second(60));
 
 # ## Benchmark in the CPU
 
-sol = AOCoptimizer.Solver.solve(Float32, graph, Second(60); engine=engine_cpu);
+sol = AOCoptimizer.Solver.solve_mixed_ising(Float32, graph, Second(60); engine=engine_cpu);
 println(JSON.json(AOCoptimizer.Solver.extract_runtime_information(sol), 4))
 
 # ## Benchmark in the GPU
-sol = AOCoptimizer.Solver.solve(Float32, graph, Second(60); engine=engine_gpu);
+sol = AOCoptimizer.Solver.solve_mixed_ising(Float32, graph, Second(60); engine=engine_gpu);
 println(JSON.json(AOCoptimizer.Solver.extract_runtime_information(sol), 4))
 
 # ## System information

notebooks/evaluate-max_cut.jl

@@ -91,7 +91,7 @@ for filename in filenames
 
     timeout = estimate_processing_time(size(graph, 1))
 
-    sol = AOCoptimizer.Solver.solve(T, -graph, timeout; engine=engine)
+    sol = AOCoptimizer.Solver.solve_mixed_ising(T, -graph, timeout; engine=engine)
     perf = AOCoptimizer.Solver.get_solver_results_summary(sol)
     max_cut = AOCoptimizer.graph_cut_from_hamiltonian(graph, perf.obj_best_found)
 

src/FileFormats/qio.jl

@@ -269,6 +269,8 @@ read_ising(filename::AbstractString)::Ising{Float64} = read_ising(Float64, filen
 Read a QIO problem from a file with name `filename` or from an IO stream `io`.
 Optional type parameter `T` specifies the elementary type used in the the problem (e.g., Float64 or Float32).
 """
+function read_qio end
+
 function read_qio(::Type{T}, filename::AbstractString)::QIOProblem  where {T<:Real}
     problem = _read_json_file(filename)
     problem_type = problem["type"]