Basic usage example (#54)

* Basic usage example

* more usage

* address review and export two symbols

* types are exported

* Restructure docs

Changelog.md

@@ -5,7 +5,13 @@ All notable changes to this Julia package will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.4.0] unreleased
+## [0.4.1] unreleased
+
+### Added
+
+* Basic usage example in docs.
+
+## [0.4.0] November 27, 2024
 
 ### Changed
 

Project.toml

@@ -1,7 +1,7 @@
 name = "ManifoldDiff"
 uuid = "af67fdf4-a580-4b9f-bbec-742ef357defd"
 authors = ["Seth Axen <[email protected]>", "Mateusz Baran <[email protected]>", "Ronny Bergmann <[email protected]>"]
-version = "0.4.0"
+version = "0.4.1"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 ChainRules = "082447d4-558c-5d27-93f4-14fc19e9eca2"
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
+DifferentiationInterface = "a0c0ee7d-e4b9-4e03-894e-1c5f64a51d63"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 FiniteDiff = "6a86dc24-6348-571c-b903-95158fe2bd41"
@@ -15,6 +16,7 @@ Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 [compat]
 Documenter = "1"
 DocumenterCitations = "1.2.1"
-ManifoldDiff = "0.3"
+ManifoldDiff = "0.4"
 Manifolds = "0.10"
 ManifoldsBase = "0.15"
+Zygote = "0.6"

docs/make.jl

@@ -40,6 +40,7 @@ makedocs(;
     sitename = "ManifoldDiff.jl",
     pages = [
         "Home" => "index.md",
+        "Usage" => "basic_usage.md",
         "Backends" => "backends.md",
         "Library of functions" => "library.md",
         "Internals" => "internals.md",

docs/src/basic_usage.md

@@ -0,0 +1,29 @@
+# Basic usage
+
+You can calculate Riemannian gradient of a function defined in its embedding in multiple ways.
+[`DifferentiationInterface.jl`](https://github.com/JuliaDiff/DifferentiationInterface.jl) can be used to select the backend.
+
+```@example
+using ManifoldDiff
+using DifferentiationInterface
+using Manifolds, FiniteDifferences, ForwardDiff, Zygote
+
+rb_onb_fd51 = TangentDiffBackend(AutoFiniteDifferences(central_fdm(5, 1)))
+rb_onb_fwdd = TangentDiffBackend(AutoForwardDiff())
+rb_proj_zyg = RiemannianProjectionBackend(AutoZygote())
+
+s2 = Sphere(2)
+
+A = [1.0 2.0 5.0; 2.0 -1.0 4.0; 5.0 4.0 0.0]
+
+f(p) = p' * A * p
+q = [0.0, 1.0, 0.0]
+
+println(ManifoldDiff.gradient(s2, f, q, rb_onb_fd51))
+println(ManifoldDiff.gradient(s2, f, q, rb_onb_fwdd))
+println(ManifoldDiff.gradient(s2, f, q, rb_proj_zyg))
+```
+
+In this example `rb_onb_fd51` corresponds to a finite differencing scheme, `rb_onb_fwdd` calculates gradient using [`ForwardDiff.jl`](https://github.com/JuliaDiff/ForwardDiff.jl) and `rb_proj_zyg` uses [`Zygote.jl`](https://github.com/FluxML/Zygote.jl) for reverse mode automatic differentiation.
+
+[`TangentDiffBackend`](@ref) reduces dimensionality of the problem to the intrinsic dimension of the manifold, while [`RiemannianProjectionBackend`](@ref) relies on converting Euclidean gradient in the embedding to the Riemannian one.

src/ManifoldDiff.jl

@@ -215,4 +215,7 @@ export riemannian_gradient,
     subgrad_distance,
     subgrad_distance!
 export set_default_differential_backend!, default_differential_backend
+
+export TangentDiffBackend, RiemannianProjectionBackend
+
 end # module

test/differentiation.jl

@@ -16,9 +16,7 @@ using ManifoldDiff:
     _jacobian,
     _jacobian!,
     set_default_differential_backend!,
-    AbstractRiemannianDiffBackend,
-    TangentDiffBackend,
-    RiemannianProjectionBackend
+    AbstractRiemannianDiffBackend
 
 using ManifoldDiff: ExplicitEmbeddedBackend