Merge pull request #509 from sathvikbhagavan/sb/docs

docs: clean up tutorials

Author: ChrisRackauckas

.github/workflows/Documentation.yml

@@ -20,9 +20,9 @@ jobs:
                                       Pkg.develop(PackageSpec(path=pwd()));
                                       Pkg.develop(PackageSpec(path=joinpath(pwd(), "lib", "SurrogatesAbstractGPs")));
                                       Pkg.develop(PackageSpec(path=joinpath(pwd(), "lib", "SurrogatesFlux")));
-                                      Pkg.develop(PackageSpec(path=joinpath(pwd(), "lib", "SurrogatesMOE")));
                                       Pkg.develop(PackageSpec(path=joinpath(pwd(), "lib", "SurrogatesPolyChaos")));
                                       Pkg.develop(PackageSpec(path=joinpath(pwd(), "lib", "SurrogatesRandomForest")));
+                                      Pkg.develop(PackageSpec(path=joinpath(pwd(), "lib", "SurrogatesMOE")));
                                       Pkg.develop(PackageSpec(path=joinpath(pwd(), "lib", "SurrogatesSVM")));
                                       Pkg.instantiate()'
       - name: Build and deploy

docs/Project.toml

@@ -4,6 +4,7 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 QuadGK = "1fd47b50-473d-5c70-9696-f719f8f3bcdc"
+Surrogates = "6fc51010-71bc-11e9-0e15-a3fcc6593c49"
 SurrogatesAbstractGPs = "78aa1720-c2af-471b-b307-964fd38f9b5f"
 SurrogatesFlux = "4f55584b-dac4-4b1c-802a-b7c47b72cb4c"
 SurrogatesMOE = "778709c9-3595-4497-80d4-d1077d5b9fbf"

docs/make.jl

@@ -5,6 +5,7 @@ cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
 
 # Make sure that plots don't throw a bunch of warnings / errors!
 ENV["GKSwstype"] = "100"
+ENV["JULIA_DEBUG"] = "Documenter"
 using Plots
 
 include("pages.jl")

docs/src/BraninFunction.md

@@ -12,7 +12,6 @@ First of all, we will import these two packages: `Surrogates` and `Plots`.
 ```@example BraninFunction
 using Surrogates
 using Plots
-default()
 ```
 
 Now, let's define our objective function:
@@ -40,7 +39,7 @@ n_samples = 80
 lower_bound = [-5, 0]
 upper_bound = [10, 15]
 xys = sample(n_samples, lower_bound, upper_bound, SobolSample())
-zs = branin.(xys);
+zs = branin.(xys)
 x, y = -5.00:10.00, 0.00:15.00
 p1 = surface(x, y, (x1, x2) -> branin((x1, x2)))
 xs = [xy[1] for xy in xys]
@@ -73,11 +72,11 @@ InverseDistance = InverseDistanceSurrogate(xys, zs, lower_bound, upper_bound)
 ```
 
 ```@example BraninFunction
-p1 = surface(x, y, (x, y) -> InverseDistance([x y])) # hide
-scatter!(xs, ys, zs, marker_z = zs) # hide
-p2 = contour(x, y, (x, y) -> InverseDistance([x y])) # hide
-scatter!(xs, ys, marker_z = zs) # hide
-plot(p1, p2, title = "Inverse Distance Surrogate") # hide
+p1 = surface(x, y, (x, y) -> InverseDistance([x y]))
+scatter!(xs, ys, zs, marker_z = zs)
+p2 = contour(x, y, (x, y) -> InverseDistance([x y]))
+scatter!(xs, ys, marker_z = zs)
+plot(p1, p2, title = "Inverse Distance Surrogate")
 ```
 
 Now, let's talk about `Lobachevsky Surrogate`:
@@ -88,9 +87,9 @@ Lobachevsky = LobachevskySurrogate(
 ```
 
 ```@example BraninFunction
-p1 = surface(x, y, (x, y) -> Lobachevsky([x y])) # hide
-scatter!(xs, ys, zs, marker_z = zs) # hide
-p2 = contour(x, y, (x, y) -> Lobachevsky([x y])) # hide
-scatter!(xs, ys, marker_z = zs) # hide
-plot(p1, p2, title = "Lobachevsky Surrogate") # hide
+p1 = surface(x, y, (x, y) -> Lobachevsky([x y]))
+scatter!(xs, ys, zs, marker_z = zs)
+p2 = contour(x, y, (x, y) -> Lobachevsky([x y]))
+scatter!(xs, ys, marker_z = zs)
+plot(p1, p2, title = "Lobachevsky Surrogate")
 ```

docs/src/ImprovedBraninFunction.md

@@ -2,7 +2,7 @@
 
 The Branin Function is commonly used as a test function for metamodelling in computer experiments, especially in the context of optimization.
 
-# Modifications for Improved Branin Function:
+## Modifications for Improved Branin Function:
 
 To enhance the Branin function, changes were made to introduce irregularities, variability, and a dynamic aspect to its landscape. Here's an example:
 
@@ -27,7 +27,7 @@ end
 
 This improved function now incorporates irregularities, variability, and a dynamic aspect. These changes aim to make the optimization landscape more challenging and realistic.
 
-# Using the Improved Branin Function:
+## Using the Improved Branin Function:
 
 After defining the improved Branin function, you can proceed to test different surrogates and visualize their performance using the updated function. Here's an example of using the improved function with the Radial Basis surrogate:
 

docs/src/InverseDistance.md

@@ -1,3 +1,5 @@
+# InverseDistance Surrogate Tutorial
+
 The **Inverse Distance Surrogate** is an interpolating method, and in this method, the unknown points are calculated with a weighted average of the sampling points. This model uses the inverse distance between the unknown and training points to predict the unknown point. We do not need to fit this model because the response of an unknown point x is computed with respect to the distance between x and the training points.
 
 Let's optimize the following function to use Inverse Distance Surrogate:
@@ -9,17 +11,16 @@ First of all, we have to import these two packages: `Surrogates` and `Plots`.
 ```@example Inverse_Distance1D
 using Surrogates
 using Plots
-default()
 ```
 
 ### Sampling
 
-We choose to sample f in 25 points between 0 and 10 using the `sample` function. The sampling points are chosen using a Low Discrepancy, this can be done by passing `HaltonSample()` to the `sample` function.
+We choose to sample f in 1000 points between 0 and 10 using the `sample` function. The sampling points are chosen using a Low Discrepancy, this can be done by passing `HaltonSample()` to the `sample` function.
 
 ```@example Inverse_Distance1D
 f(x) = sin(x) + sin(x)^2 + sin(x)^3
 
-n_samples = 25
+n_samples = 100
 lower_bound = 0.0
 upper_bound = 10.0
 x = sample(n_samples, lower_bound, upper_bound, HaltonSample())
@@ -33,8 +34,6 @@ plot!(f, label = "True function", xlims = (lower_bound, upper_bound), legend = :
 
 ```@example Inverse_Distance1D
 InverseDistance = InverseDistanceSurrogate(x, y, lower_bound, upper_bound)
-add_point!(InverseDistance, 5.0, f(5.0))
-add_point!(InverseDistance, [5.1, 5.2], [f(5.1), f(5.2)])
 prediction = InverseDistance(5.0)
 ```
 
@@ -55,7 +54,7 @@ Having built a surrogate, we can now use it to search for minima in our original
 To optimize using our surrogate we call `surrogate_optimize` method. We choose to use Stochastic RBF as the optimization technique and again Sobol sampling as the sampling technique.
 
 ```@example Inverse_Distance1D
-@show surrogate_optimize(
+surrogate_optimize(
     f, SRBF(), lower_bound, upper_bound, InverseDistance, SobolSample())
 scatter(x, y, label = "Sampled points", legend = :top)
 plot!(f, label = "True function", xlims = (lower_bound, upper_bound), legend = :top)
@@ -68,9 +67,9 @@ plot!(InverseDistance, label = "Surrogate function",
 First of all we will define the `Schaffer` function we are going to build a surrogate for. Notice, how its argument is a vector of numbers, one for each coordinate, and its output is a scalar.
 
 ```@example Inverse_DistanceND
-using Plots # hide
-default(c = :matter, legend = false, xlabel = "x", ylabel = "y") # hide
-using Surrogates # hide
+using Plots
+default(c = :matter, legend = false, xlabel = "x", ylabel = "y")
+using Surrogates
 
 function schaffer(x)
     x1 = x[1]
@@ -83,10 +82,10 @@ end
 
 ### Sampling
 
-Let's define our bounds, this time we are working in two dimensions. In particular we want our first dimension `x` to have bounds `-5, 10`, and `0, 15` for the second dimension. We are taking 60 samples of the space using Sobol Sequences. We then evaluate our function on all the sampling points.
+Let's define our bounds, this time we are working in two dimensions. In particular we want our first dimension `x` to have bounds `-5, 10`, and `0, 15` for the second dimension. We are taking 100 samples of the space using Sobol Sequences. We then evaluate our function on all the sampling points.
 
 ```@example Inverse_DistanceND
-n_samples = 60
+n_samples = 100
 lower_bound = [-5.0, 0.0]
 upper_bound = [10.0, 15.0]
 
@@ -95,14 +94,14 @@ zs = schaffer.(xys);
 ```
 
 ```@example Inverse_DistanceND
-x, y = -5:10, 0:15 # hide
-p1 = surface(x, y, (x1, x2) -> schaffer((x1, x2))) # hide
-xs = [xy[1] for xy in xys] # hide
-ys = [xy[2] for xy in xys] # hide
-scatter!(xs, ys, zs) # hide
-p2 = contour(x, y, (x1, x2) -> schaffer((x1, x2))) # hide
-scatter!(xs, ys) # hide
-plot(p1, p2, title = "True function") # hide
+x, y = -5:10, 0:15
+p1 = surface(x, y, (x1, x2) -> schaffer((x1, x2)))
+xs = [xy[1] for xy in xys]
+ys = [xy[2] for xy in xys]
+scatter!(xs, ys, zs)
+p2 = contour(x, y, (x1, x2) -> schaffer((x1, x2)))
+scatter!(xs, ys)
+plot(p1, p2, title = "True function")
 ```
 
 ### Building a surrogate
@@ -114,11 +113,11 @@ InverseDistance = InverseDistanceSurrogate(xys, zs, lower_bound, upper_bound)
 ```
 
 ```@example Inverse_DistanceND
-p1 = surface(x, y, (x, y) -> InverseDistance([x y])) # hide
-scatter!(xs, ys, zs, marker_z = zs) # hide
-p2 = contour(x, y, (x, y) -> InverseDistance([x y])) # hide
-scatter!(xs, ys, marker_z = zs) # hide
-plot(p1, p2, title = "Surrogate") # hide
+p1 = surface(x, y, (x, y) -> InverseDistance([x y]))
+scatter!(xs, ys, zs, marker_z = zs)
+p2 = contour(x, y, (x, y) -> InverseDistance([x y]))
+scatter!(xs, ys, marker_z = zs)
+plot(p1, p2, title = "Surrogate")
 ```
 
 ### Optimizing
@@ -142,12 +141,12 @@ size(xys)
 ```
 
 ```@example Inverse_DistanceND
-p1 = surface(x, y, (x, y) -> InverseDistance([x y])) # hide
-xs = [xy[1] for xy in xys] # hide
-ys = [xy[2] for xy in xys] # hide
-zs = schaffer.(xys) # hide
-scatter!(xs, ys, zs, marker_z = zs) # hide
-p2 = contour(x, y, (x, y) -> InverseDistance([x y])) # hide
-scatter!(xs, ys, marker_z = zs) # hide
-plot(p1, p2) # hide
+p1 = surface(x, y, (x, y) -> InverseDistance([x y]))
+xs = [xy[1] for xy in xys]
+ys = [xy[2] for xy in xys]
+zs = schaffer.(xys)
+scatter!(xs, ys, zs, marker_z = zs)
+p2 = contour(x, y, (x, y) -> InverseDistance([x y]))
+scatter!(xs, ys, marker_z = zs)
+plot(p1, p2)
 ```

docs/src/LinearSurrogate.md

@@ -9,16 +9,15 @@ First of all we have to import these two packages: `Surrogates` and `Plots`.
 ```@example linear_surrogate1D
 using Surrogates
 using Plots
-default()
 ```
 
 ### Sampling
 
-We choose to sample f in 20 points between 0 and 10 using the `sample` function. The sampling points are chosen using a Sobol sequence, this can be done by passing `SobolSample()` to the `sample` function.
+We choose to sample f in 100 points between 0 and 10 using the `sample` function. The sampling points are chosen using a Sobol sequence, this can be done by passing `SobolSample()` to the `sample` function.
 
 ```@example linear_surrogate1D
-f(x) = sin(x) + log(x)
-n_samples = 20
+f(x) = 2 * x + 10.0
+n_samples = 100
 lower_bound = 5.2
 upper_bound = 12.5
 x = sample(n_samples, lower_bound, upper_bound, SobolSample())
@@ -35,8 +34,6 @@ We can simply calculate `linear_surrogate` for any value.
 
 ```@example linear_surrogate1D
 my_linear_surr_1D = LinearSurrogate(x, y, lower_bound, upper_bound)
-add_point!(my_linear_surr_1D, 4.0, 7.2)
-add_point!(my_linear_surr_1D, [5.0, 6.0], [8.3, 9.7])
 val = my_linear_surr_1D(5.0)
 ```
 
@@ -56,7 +53,7 @@ Having built a surrogate, we can now use it to search for minima in our original
 To optimize using our surrogate we call `surrogate_optimize` method. We choose to use Stochastic RBF as the optimization technique and again Sobol sampling as the sampling technique.
 
 ```@example linear_surrogate1D
-@show surrogate_optimize(
+surrogate_optimize(
     f, SRBF(), lower_bound, upper_bound, my_linear_surr_1D, SobolSample())
 scatter(x, y, label = "Sampled points")
 plot!(f, label = "True function", xlims = (lower_bound, upper_bound))
@@ -68,9 +65,9 @@ plot!(my_linear_surr_1D, label = "Surrogate function", xlims = (lower_bound, upp
 First of all we will define the `Egg Holder` function we are going to build a surrogate for. Notice, one how its argument is a vector of numbers, one for each coordinate, and its output is a scalar.
 
 ```@example linear_surrogateND
-using Plots # hide
-default(c = :matter, legend = false, xlabel = "x", ylabel = "y") # hide
-using Surrogates # hide
+using Plots
+default(c = :matter, legend = false, xlabel = "x", ylabel = "y")
+using Surrogates
 
 function egg(x)
     x1 = x[1]
@@ -83,26 +80,26 @@ end
 
 ### Sampling
 
-Let's define our bounds, this time we are working in two dimensions. In particular we want our first dimension `x` to have bounds `-10, 5`, and `0, 15` for the second dimension. We are taking 50 samples of the space using Sobol Sequences. We then evaluate our function on all of the sampling points.
+Let's define our bounds, this time we are working in two dimensions. In particular we want our first dimension `x` to have bounds `-10, 5`, and `0, 15` for the second dimension. We are taking 100 samples of the space using Sobol Sequences. We then evaluate our function on all of the sampling points.
 
 ```@example linear_surrogateND
-n_samples = 50
+n_samples = 100
 lower_bound = [-10.0, 0.0]
 upper_bound = [5.0, 15.0]
 
 xys = sample(n_samples, lower_bound, upper_bound, SobolSample())
-zs = egg.(xys);
+zs = egg.(xys)
 ```
 
 ```@example linear_surrogateND
-x, y = -10:5, 0:15 # hide
-p1 = surface(x, y, (x1, x2) -> egg((x1, x2))) # hide
-xs = [xy[1] for xy in xys] # hide
-ys = [xy[2] for xy in xys] # hide
-scatter!(xs, ys, zs) # hide
-p2 = contour(x, y, (x1, x2) -> egg((x1, x2))) # hide
-scatter!(xs, ys) # hide
-plot(p1, p2, title = "True function") # hide
+x, y = -10:5, 0:15
+p1 = surface(x, y, (x1, x2) -> egg((x1, x2)))
+xs = [xy[1] for xy in xys]
+ys = [xy[2] for xy in xys]
+scatter!(xs, ys, zs)
+p2 = contour(x, y, (x1, x2) -> egg((x1, x2)))
+scatter!(xs, ys)
+plot(p1, p2, title = "True function")
 ```
 
 ### Building a surrogate
@@ -114,11 +111,11 @@ my_linear_ND = LinearSurrogate(xys, zs, lower_bound, upper_bound)
 ```
 
 ```@example linear_surrogateND
-p1 = surface(x, y, (x, y) -> my_linear_ND([x y])) # hide
-scatter!(xs, ys, zs, marker_z = zs) # hide
-p2 = contour(x, y, (x, y) -> my_linear_ND([x y])) # hide
-scatter!(xs, ys, marker_z = zs) # hide
-plot(p1, p2, title = "Surrogate") # hide
+p1 = surface(x, y, (x, y) -> my_linear_ND([x y]))
+scatter!(xs, ys, zs, marker_z = zs)
+p2 = contour(x, y, (x, y) -> my_linear_ND([x y]))
+scatter!(xs, ys, marker_z = zs)
+plot(p1, p2, title = "Surrogate")
 ```
 
 ### Optimizing
@@ -142,12 +139,12 @@ size(xys)
 ```
 
 ```@example linear_surrogateND
-p1 = surface(x, y, (x, y) -> my_linear_ND([x y])) # hide
-xs = [xy[1] for xy in xys] # hide
-ys = [xy[2] for xy in xys] # hide
-zs = egg.(xys) # hide
-scatter!(xs, ys, zs, marker_z = zs) # hide
-p2 = contour(x, y, (x, y) -> my_linear_ND([x y])) # hide
-scatter!(xs, ys, marker_z = zs) # hide
-plot(p1, p2) # hide
+p1 = surface(x, y, (x, y) -> my_linear_ND([x y]))
+xs = [xy[1] for xy in xys]
+ys = [xy[2] for xy in xys]
+zs = egg.(xys)
+scatter!(xs, ys, zs, marker_z = zs)
+p2 = contour(x, y, (x, y) -> my_linear_ND([x y]))
+scatter!(xs, ys, marker_z = zs)
+plot(p1, p2)
 ```

docs/src/Salustowicz.md

@@ -12,7 +12,6 @@ Let's import these two packages  `Surrogates` and `Plots`:
 ```@example salustowicz1D
 using Surrogates
 using Plots
-default()
 ```
 
 Now, let's define our objective function: