From 701251aa742a3075af7966c1274e89259035493d Mon Sep 17 00:00:00 2001
From: James Foster <38274066+jd-foster@users.noreply.github.com>
Date: Fri, 22 Nov 2024 06:43:14 +1100
Subject: [PATCH] [docs] add simple example "Low-rank matrix completion"
 (#3888)

---
 docs/src/references.bib                     | 12 +++++++++
 docs/src/tutorials/conic/simple_examples.jl | 27 +++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/docs/src/references.bib b/docs/src/references.bib
index c03f5fff345..fbc566a5769 100644
--- a/docs/src/references.bib
+++ b/docs/src/references.bib
@@ -173,6 +173,18 @@ @article{Peng2007
   doi     = {10.1137/050641983},
 }
 
+@article{RechtFazelParrilo2010,
+	author = {Recht, Benjamin and Fazel, Maryam and Parrilo, Pablo A.},
+	title = {Guaranteed Minimum-Rank Solutions of Linear Matrix Equations via Nuclear Norm Minimization},
+	journal = {SIAM Review},
+	volume = {52},
+	number = {3},
+	pages = {471--501},
+	year = {2010},
+	issn = {0036-1445},
+	url = {https://www.jstor.org/stable/20780168},
+}
+
 @article{Zimmerman2011,
   author = {Zimmerman, Ray Daniel and Murillo-Sánchez, Carlos Edmundo and Thomas, Robert John},
   journal = {IEEE Transactions on Power Systems},
diff --git a/docs/src/tutorials/conic/simple_examples.jl b/docs/src/tutorials/conic/simple_examples.jl
index 9e2b383bcb3..ea06c1da0b3 100644
--- a/docs/src/tutorials/conic/simple_examples.jl
+++ b/docs/src/tutorials/conic/simple_examples.jl
@@ -115,6 +115,33 @@ S, T = solve_max_cut_sdp([0 5 7 6; 5 0 0 1; 7 0 0 1; 6 1 1 0])
 
 S, T = solve_max_cut_sdp([0 1 5 0; 1 0 0 9; 5 0 0 2; 0 9 2 0])
 
+# ## Low-rank matrix completion
+
+# The matrix completion problem seeks to find the missing entries of a matrix 
+# with a given (possibly random) subset of fixed entries, such that the completed
+# matrix has the lowest attainable rank.
+#
+# For more details, see [RechtFazelParrilo2010](@cite). 
+
+function example_matrix_completion(; svdtol = 1e-6)
+    rng = Random.MersenneTwister(1234)
+    n = 20
+    mask = rand(rng, 1:25, n, n) .== 1
+    B = randn(rng, n, n)
+    model = Model(SCS.Optimizer)
+    @variable(model, X[1:n, 1:n])
+    @constraint(model, X[mask] .== B[mask])
+    @variable(model, t)
+    @constraint(model, [t; vec(X)] in MOI.NormNuclearCone(n, n))
+    @objective(model, Min, t)
+    optimize!(model)
+    @assert is_solved_and_feasible(model)
+    ## Return the approximate rank of the completed matrix to a given tolerance:
+    return sum(LinearAlgebra.svdvals(value.(X)) .> svdtol)
+end
+
+example_matrix_completion()
+
 # ## K-means clustering via SDP
 
 # Given a set of points ``a_1, \ldots, a_m``  in ``\mathbb{R}^n``, allocate them to ``k`` clusters.