From aa4c8a37037ba3288a3c2e4e797eee7fea6eb892 Mon Sep 17 00:00:00 2001
From: farhadrclass <31899325+farhadrclass@users.noreply.github.com>
Date: Fri, 4 Oct 2024 09:23:59 -0400
Subject: [PATCH] added the example

---
 src/utilities.jl | 41 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/src/utilities.jl b/src/utilities.jl
index 8cc190f..07aeff5 100644
--- a/src/utilities.jl
+++ b/src/utilities.jl
@@ -156,7 +156,7 @@ Solve linear system (B + σI) x = b, where B is a forward L-BFGS operator and σ
 ### Parameters
 
 - `x::AbstractVector{T}`: preallocated vector of length n that is used to store the solution x.
-- `B::LBFGSOperator`: forward L-BFGS operatorthat models a matrix of size n x n.
+- `B::LBFGSOperator`: forward L-BFGS operator that models a matrix of size n x n.
 - `b::AbstractVector{T}`: right-hand side vector of length n.
 - `σ::T`: nonnegative shift.
 
@@ -168,6 +168,38 @@ Solve linear system (B + σI) x = b, where B is a forward L-BFGS operator and σ
 
 The method uses a two-loop recursion-like approach with modifications to handle the shift `σ`.
 
+### Example
+
+```julia
+using Random
+
+# Problem setup
+n = 100  # size of the problem
+mem = 10   # L-BFGS memory size
+scaling = true  # enable scaling
+
+# Create an L-BFGS operator
+B = LBFGSOperator(n, mem = mem, scaling = scaling)
+
+# Add random {s, y} pairs to the L-BFGS operator
+for _ = 1:10
+    s = rand(n)   
+    y = rand(n)   
+    push!(B, s, y)  # Add the {s, y} pair to B
+end
+
+# Prepare vectors for the system
+x_sol = zeros(n)   # Preallocated solution vector
+b = rand(n)        # Right-hand side vector
+σ = 0.1            # Small shift value
+
+# Solve the shifted system
+result = solve_shifted_system!(x_sol, B, b, σ)
+
+# Check that the solution is close enough (residual test)
+@assert norm(B * x_sol + σ * x_sol - b) / norm(b) < 1e-8
+```
+
 ### References
 
 Erway, J. B., Jain, V., & Marcia, R. F. Shifted L-BFGS Systems. Optimization Methods and Software, 29(5), pp. 992-1004, 2014.
@@ -223,10 +255,9 @@ Solves the linear system Bx = b.
 
 ### Arguments:
 
-- `x::AbstractVector{T}`: The solution vector, which will be modified in-place.
-- `B::LBFGSOperator{T, I, F1, F2, F3}`: The L-BFGS operator that defines the linear system.
-- `b::AbstractVector{T}`: The right-hand side vector of the linear system.
-
+- `x::AbstractVector{T}`: preallocated vector of length n that is used to store the solution x.
+- `B::LBFGSOperator`: forward L-BFGS operator that models a matrix of size n x n.
+- `b::AbstractVector{T}`: right-hand side vector of length n.
 ### Returns:
 
 - `x::AbstractVector{T}`: The modified solution vector containing the solution to the linear system.