From 2c11fbb24205b594644c577f9c72be77317a510d Mon Sep 17 00:00:00 2001 From: Oscar Dowson Date: Fri, 25 Oct 2024 14:35:18 +1300 Subject: [PATCH] [docs] improvements to the docstrings (#156) --- docs/src/api.md | 2 +- src/MathOptAI.jl | 1 + src/predictors/Affine.jl | 4 ++-- src/predictors/GrayBox.jl | 10 ++++++--- src/predictors/Pipeline.jl | 6 +++--- src/predictors/Quantile.jl | 11 +++++++++- src/predictors/ReLU.jl | 43 ++++++++++++++++++++++++++++---------- src/predictors/Scale.jl | 4 ++-- src/predictors/Sigmoid.jl | 7 +++++-- src/predictors/SoftMax.jl | 7 +++++-- src/predictors/SoftPlus.jl | 7 +++++-- src/predictors/Tanh.jl | 7 +++++-- 12 files changed, 78 insertions(+), 31 deletions(-) diff --git a/docs/src/api.md b/docs/src/api.md index 0419c365..11d97213 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -33,7 +33,7 @@ add_predictor ## `build_predictor` ```@docs -build_predictor +build_predictor(predictor::AbstractPredictor; kwargs...) ``` ## `Affine` diff --git a/src/MathOptAI.jl b/src/MathOptAI.jl index 2df1e53a..4ccfcf8b 100644 --- a/src/MathOptAI.jl +++ b/src/MathOptAI.jl @@ -20,6 +20,7 @@ An abstract type representing different types of prediction models. All subtypes must implement: * [`add_predictor`](@ref) + * [`build_predictor`](@ref) """ abstract type AbstractPredictor end diff --git a/src/predictors/Affine.jl b/src/predictors/Affine.jl index 31aec105..3e0cf542 100644 --- a/src/predictors/Affine.jl +++ b/src/predictors/Affine.jl @@ -10,9 +10,9 @@ b::Vector{T} = zeros(T, size(A, 1)), ) where {T} <: AbstractPredictor -An [`AbstractPredictor`](@ref) that represents the affine relationship: +An [`AbstractPredictor`](@ref) that represents the relationship: ```math -f(x) = A x + b +y = A x + b ``` ## Example diff --git a/src/predictors/GrayBox.jl b/src/predictors/GrayBox.jl index 20f80d2f..c5b489fc 100644 --- a/src/predictors/GrayBox.jl +++ b/src/predictors/GrayBox.jl @@ -11,8 +11,11 @@ has_hessian::Bool = false, ) <: AbstractPredictor -An [`AbstractPredictor`](@ref) that represents the function ``f(x)`` as a -user-defined nonlinear operator. +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = f(x) +``` +as a user-defined nonlinear operator. ## Arguments @@ -56,7 +59,8 @@ GrayBox ├ op_##330(x[1], x[2]) - moai_GrayBox[1] = 0 └ op_##331(x[1], x[2]) - moai_GrayBox[2] = 0 -julia> y, formulation = MathOptAI.add_predictor(model, MathOptAI.ReducedSpace(f), x); +julia> y, formulation = + MathOptAI.add_predictor(model, MathOptAI.ReducedSpace(f), x); julia> y 2-element Vector{NonlinearExpr}: diff --git a/src/predictors/Pipeline.jl b/src/predictors/Pipeline.jl index e00412c9..ef3d1ae6 100644 --- a/src/predictors/Pipeline.jl +++ b/src/predictors/Pipeline.jl @@ -7,11 +7,11 @@ """ Pipeline(layers::Vector{AbstractPredictor}) <: AbstractPredictor -An [`AbstractPredictor`](@ref) that represents a pipeline (composition) of -nested layers: +An [`AbstractPredictor`](@ref) that represents the relationship: ```math -f(x) = (l_1 \\cdots (l_N(x)) +y = (l_1 \\circ \\ldots \\circ l_N)(x) ``` +where \$l_i\$ are a list of other [`AbstractPredictor`](@ref)s. ## Example diff --git a/src/predictors/Quantile.jl b/src/predictors/Quantile.jl index 227e29e2..5c943151 100644 --- a/src/predictors/Quantile.jl +++ b/src/predictors/Quantile.jl @@ -5,7 +5,7 @@ # in the LICENSE.md file. """ - Quantile(distribution, quantiles::Vector{Float64}) + Quantile{D}(distribution::D, quantiles::Vector{Float64}) where {D} An [`AbstractPredictor`](@ref) that represents the `quantiles` of `distribution`. @@ -29,6 +29,15 @@ julia> y 2-element Vector{VariableRef}: moai_quantile[1] moai_quantile[2] + +julia> formulation +Quantile(_, [0.1, 0.9]) +├ variables [2] +│ ├ moai_quantile[1] +│ └ moai_quantile[2] +└ constraints [2] + ├ moai_quantile[1] - op_quantile_0.1(x) = 0 + └ moai_quantile[2] - op_quantile_0.9(x) = 0 ``` """ struct Quantile{D} <: AbstractPredictor diff --git a/src/predictors/ReLU.jl b/src/predictors/ReLU.jl index 3bd0a444..eb080770 100644 --- a/src/predictors/ReLU.jl +++ b/src/predictors/ReLU.jl @@ -7,8 +7,11 @@ """ ReLU() <: AbstractPredictor -An [`AbstractPredictor`](@ref) that implements the ReLU constraint -\$y = \\max\\{0, x\\}\$ as a non-smooth nonlinear constraint. +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = \\max\\{0, x\\} +``` +as a non-smooth nonlinear constraint. ## Example @@ -76,8 +79,20 @@ end """ ReLUBigM(M::Float64) <: AbstractPredictor -An [`AbstractPredictor`](@ref) that implements the ReLU constraint -\$y = \\max\\{0, x\\}\$ via a big-M MIP reformulation. +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = \\max\\{0, x\\} +``` +via the big-M MIP reformulation: +```math +\\begin{aligned} +y \\ge 0 \\\\ +y \\ge x \\\\ +y \\le M z \\\\ +y \\le x + M(1 - z) \\\\ +z \\in\\{0, 1\\} +\\end{aligned} +``` ## Example @@ -154,12 +169,15 @@ end """ ReLUSOS1() <: AbstractPredictor -An [`AbstractPredictor`](@ref) that implements the ReLU constraint -\$y = \\max\\{0, x\\}\$ by the reformulation: +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = \\max\\{0, x\\} +``` +by the reformulation: ```math \\begin{aligned} -x = y - z \\\\ -[y, z] \\in SOS1 \\\\ +x = y - z \\\\ +[y, z] \\in SOS1 \\\\ y, z \\ge 0 \\end{aligned} ``` @@ -228,12 +246,15 @@ end """ ReLUQuadratic() <: AbstractPredictor -An [`AbstractPredictor`](@ref) that implements the ReLU constraint -\$y = \\max\\{0, x\\}\$ by the reformulation: +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = \\max\\{0, x\\} +``` +by the reformulation: ```math \\begin{aligned} x = y - z \\\\ -y \\times z = 0 \\\\ +y \\cdot z = 0 \\\\ y, z \\ge 0 \\end{aligned} ``` diff --git a/src/predictors/Scale.jl b/src/predictors/Scale.jl index 9e1f74f4..6568be4a 100644 --- a/src/predictors/Scale.jl +++ b/src/predictors/Scale.jl @@ -10,9 +10,9 @@ bias::Vector{T}, ) where {T} <: AbstractPredictor -An [`AbstractPredictor`](@ref) that represents the affine relationship: +An [`AbstractPredictor`](@ref) that represents the relationship: ```math -f(x) = Diag(scale)x + bias +y = Diag(scale)x + bias ``` ## Example diff --git a/src/predictors/Sigmoid.jl b/src/predictors/Sigmoid.jl index 5ed6cbef..2e09b3f9 100644 --- a/src/predictors/Sigmoid.jl +++ b/src/predictors/Sigmoid.jl @@ -7,8 +7,11 @@ """ Sigmoid() <: AbstractPredictor -An [`AbstractPredictor`](@ref) that implements the Sigmoid constraint -\$y = \\frac{1}{1 + e^{-x}}\$ as a smooth nonlinear constraint. +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = \\frac{1}{1 + e^{-x}} +``` +as a smooth nonlinear constraint. ## Example diff --git a/src/predictors/SoftMax.jl b/src/predictors/SoftMax.jl index cafa830b..64ff2936 100644 --- a/src/predictors/SoftMax.jl +++ b/src/predictors/SoftMax.jl @@ -7,8 +7,11 @@ """ SoftMax() <: AbstractPredictor -An [`AbstractPredictor`](@ref) that implements the SoftMax constraint -\$y_i = \\frac{e^{x_i}}{\\sum_j e^{x_j}}\$ as a smooth nonlinear constraint. +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = \\frac{e^{x}}{||e^{x}||_1} +``` +as a smooth nonlinear constraint. ## Example diff --git a/src/predictors/SoftPlus.jl b/src/predictors/SoftPlus.jl index b48d99db..18fcdcd9 100644 --- a/src/predictors/SoftPlus.jl +++ b/src/predictors/SoftPlus.jl @@ -7,8 +7,11 @@ """ SoftPlus(; beta = 1.0) <: AbstractPredictor -An [`AbstractPredictor`](@ref) that implements the SoftPlus constraint -\$y = \\frac{1}{\\beta} \\log(1 + e^{\\beta x})\$ as a smooth nonlinear constraint. +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = \\frac{1}{\\beta} \\log(1 + e^{\\beta x}) +``` +as a smooth nonlinear constraint. ## Example diff --git a/src/predictors/Tanh.jl b/src/predictors/Tanh.jl index 6954f21b..66ce64a1 100644 --- a/src/predictors/Tanh.jl +++ b/src/predictors/Tanh.jl @@ -7,8 +7,11 @@ """ Tanh() <: AbstractPredictor -An [`AbstractPredictor`](@ref) that implements the Tanh constraint -\$y = \\tanh(x)\$ as a smooth nonlinear constraint. +An [`AbstractPredictor`](@ref) that represents the relationship: +```math +y = \\tanh(x) +``` +as a smooth nonlinear constraint. ## Example