Skip to content

Add MOI interface and expand docs, experiments and tests #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Vaibhavdixit02 wants to merge 14 commits into
base: main
Choose a base branch
from
Open

Add MOI interface and expand docs, experiments and tests #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
03e9712
Fix DGCP composition bugs and add paper revision experiments
Vaibhavdixit02 Jan 29, 2026
13ca5b9
Address paper reviewer comments with experiments and documentation
Vaibhavdixit02 Jan 31, 2026
2af76e6
Remove internal meeting notes file
Vaibhavdixit02 Jan 31, 2026
ac61e11
Add MOI/JuMP integration with cone annotations and conic form generation
Vaibhavdixit02 Feb 16, 2026
a9e03b1
Remove VALIDATION_REPORT.md from test/experiments
Vaibhavdixit02 Feb 17, 2026
2581eb0
Fix invalid @test macro syntax in dcp_dgcp_comparison.jl
Vaibhavdixit02 Feb 17, 2026
0f60363
Production conic forms, MOI bridge rewrite, CairoMakie figures, and e…
Vaibhavdixit02 Feb 19, 2026
a6c631a
Remove revision_response.md and revision_v2.tex from tracking
Vaibhavdixit02 Feb 21, 2026
6dc66b0
Add documentation, tutorials, and test/code quality improvements
Vaibhavdixit02 Feb 21, 2026
e616b2f
Add experiments, docs, and code fixes for paper revision
Vaibhavdixit02 Feb 24, 2026
a24c54c
Address PR review feedback on conic and curvature handling
Vaibhavdixit02 Mar 8, 2026
130492d
Run JuliaFormatter across repository
Vaibhavdixit02 Mar 8, 2026
38b01ac
Fix DGCP affine propagation and apply Runic formatting
Vaibhavdixit02 Mar 8, 2026
d569df3
Address newly verified review findings
Vaibhavdixit02 Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,9 @@
Manifest.toml
.DS_Store
.DS_Store
assets/
*.pdf
*.png
*.docx
*.tex
revision_response.md
_MPC_v2__DGCP/
4 changes: 4 additions & 0 deletions Project.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,11 @@ Dictionaries = "85a47980-9c8c-11e8-2b9f-f7ca1fa99fb4"
Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
DomainSets = "5b8099bc-c8ec-5219-889f-1d9e522a28bf"
IfElse = "615f187c-cbe4-4ef1-ba3b-2fcf58d6d173"
JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
LogExpFunctions = "2ab3a3ac-af41-5b50-aa03-7779005ae688"
Manifolds = "1cead3c2-87b3-11e9-0ccd-23c62b72b94e"
MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
PDMats = "90014a1f-27ba-587c-ab20-58faa44d9150"
PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
Expand All @@ -27,9 +29,11 @@ Dictionaries = "0.4"
Distributions = "0.25"
DomainSets = "0.7"
IfElse = "0.1"
JuMP = "1"
LinearAlgebra = "1.10"
LogExpFunctions = "0.3"
Manifolds = "0.9, 0.10"
MathOptInterface = "1"
PDMats = "0.11"
PrecompileTools = "1"
RecursiveArrayTools = "3"
Expand Down
32 changes: 32 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# SymbolicAnalysis.jl Documentation

SymbolicAnalysis.jl is a Julia package for automated verification of convexity properties of symbolic mathematical expressions. It implements both classical Disciplined Convex Programming (DCP) and Disciplined Geodesically Convex Programming (DGCP), extending convexity verification to optimization problems on Riemannian manifolds such as symmetric positive definite matrices and hyperbolic space.

## Quick Start

```julia
using SymbolicAnalysis, Manifolds, Symbolics, LinearAlgebra

@variables X[1:5, 1:5]
M = SymmetricPositiveDefinite(5)
result = analyze(tr(inv(X)) + logdet(X), M)
result.gcurvature # GConvex (geodesically convex, but not Euclidean convex)
```

## Documentation Index

### Tutorials

- **[DGCP Analysis Workflow](tutorials/dgcp_tutorial.md)** -- A step-by-step guide to using the DGCP framework. Covers defining symbolic variables and manifolds, running `analyze`, interpreting results (GConvex, GConcave, GLinear, GUnknownCurvature), composition rules, canonicalization, and troubleshooting. Includes examples for both the SPD and Lorentz manifolds.

- **[Conic Form Generation and MOI Bridge](tutorials/conic_form_tutorial.md)** -- How to transform DCP-verified expressions into standard conic form and solve them with MathOptInterface (MOI) or JuMP solvers. Covers the epigraph reformulation pipeline, supported cone types, and integration with solvers like SCS, COSMO, and Clarabel.

### Reference

- **[Worked Examples](examples.md)** -- Six complete worked examples of optimization problems on the SPD manifold: Karcher mean, Tyler's M-estimator, Brascamp-Lieb bound, maximum likelihood estimation, matrix square root via S-divergence, and regularized distance minimization. Each example includes the mathematical formulation, Julia verification code, and interpretation of results.

- **[Atoms Reference Table](atoms_table.md)** -- Complete reference table of all DCP and DGCP atoms supported by SymbolicAnalysis.jl. Lists every atom with its domain, sign, curvature, monotonicity, cone type, and literature reference. Organized by category: SPD manifold atoms, Lorentz manifold atoms, standard DCP atoms (affine, convex, concave), and power atoms.

### Guides

- **[Porting Guide (Python/Matlab)](porting_guide.md)** -- Practical instructions for reimplementing DGCP in Python (using SymPy) or Matlab (using the Symbolic Math Toolbox). Describes the four-stage analysis pipeline, provides complete code for atom registries, expression tree traversal, composition rule application, and DCP/DGCP curvature propagation in both languages.
192 changes: 192 additions & 0 deletions docs/atoms_table.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
# DGCP Atoms Reference Table

> **Verification Note**: This document was verified against the source code on 2026-02-21.
> All atoms, curvatures, monotonicities, and cone annotations have been confirmed to match the implementations in:
> - `src/atoms.jl` (DCP atom definitions with cone annotations)
> - `src/gdcp/spd.jl` (SPD manifold atoms)
> - `src/gdcp/lorentz.jl` (Lorentz manifold atoms)
> - `src/gdcp/gdcp_rules.jl` (GDCP rule infrastructure)
> - `src/rules.jl` (DCP rule infrastructure)

This document provides a comprehensive table of all DGCP (Disciplined Geodesically Convex Programming) atoms supported by SymbolicAnalysis.jl. These atoms form the building blocks for constructing and verifying geodesically convex expressions.

## SPD Manifold Atoms (Symmetric Positive Definite Matrices)

These atoms are defined on the manifold of symmetric positive definite matrices with the affine-invariant Riemannian metric.

### Scalar-Valued Atoms

| Atom | Domain | Sign | G-Curvature | Monotonicity | Source | Reference |
|------|--------|------|-------------|--------------|--------|-----------|
| `logdet(X)` | SPD | AnySign | GLinear | GIncreasing | Literature | Vishnoi (2018); Bacak (2014) |
| `tr(X)` | SPD | Positive | GConvex | GIncreasing | Literature | Vishnoi (2018) |
| `sum(X)` | SPD | Positive | GConvex | GIncreasing | New | - |
| `sdivergence(X, Y)` | SPD | Positive | GConvex | GIncreasing | Literature | Sra (2015) |
| `distance(M, X, Y)` | SPD | Positive | GConvex | GAnyMono | Literature | Bacak (2014); Bhatia (2007) |
| `quad_form(h, X)` | SPD | Positive | GConvex | GIncreasing | Literature | - |
| `eigmax(X)` | SPD | Positive | GConvex | GIncreasing | Literature | - |
| `log_quad_form(y, X)` | SPD | Positive | GConvex | GIncreasing | Literature | Wiesel (2012) |
| `eigsummax(X, k)` | SPD | Positive | GConvex | GIncreasing | Literature | Sra (2015) |
| `schatten_norm(X, p)` | SPD | Positive | GConvex | GIncreasing | Literature | Sra (2015) |
| `sum_log_eigmax(X, k)` | SPD | Positive | GConvex | GIncreasing | Literature | Sra (2015) |
| `sum_log_eigmax(f, X, k)` | SPD | Positive | GConvex | GIncreasing | Literature | Sra (2015) |

### Matrix-Valued Atoms

| Atom | Domain | Sign | G-Curvature | Monotonicity | Source | Reference |
|------|--------|------|-------------|--------------|--------|-----------|
| `conjugation(X, B)` | SPD | Positive | GConvex | GIncreasing | Literature | Vishnoi (2018) |
| `adjoint(X)` | SPD | Positive | GLinear | GIncreasing | New | - |
| `inv(X)` | SPD | Positive | GConvex | GDecreasing | Literature | Bhatia (2007) |
| `diag(X)` | SPD | Positive | GConvex | GIncreasing | Literature | Vishnoi (2018) |
| `scalar_mat(X, k)` | SPD | Positive | GConvex | GIncreasing | New | - |
| `hadamard_product(X, B)` | SPD | Positive | GConvex | GIncreasing | Literature | Vishnoi (2018) |
| `affine_map(f, X, B, Y)` | SPD | Positive | GConvex | GIncreasing | New | Based on Sra (2015) |

## Lorentz Model Atoms (Hyperbolic Space)

These atoms are defined on the Lorentz model of hyperbolic space, a Cartan-Hadamard manifold of constant negative curvature.

| Atom | Domain | Sign | G-Curvature | Monotonicity | Source | Reference |
|------|--------|------|-------------|--------------|--------|-----------|
| `distance(M, p, q)` | Lorentz | Positive | GConvex | GAnyMono | Literature | Bacak (2014) |
| `lorentz_log_barrier(p)` | Lorentz | AnySign | GConvex | GIncreasing | Literature | Ferreira et al. (2022) |
| `lorentz_homogeneous_quadratic(A, p)` | Lorentz | Positive | GConvex | GAnyMono | Literature | Ferreira et al. (2022) |
| `lorentz_homogeneous_diagonal(a, p)` | Lorentz | Positive | GConvex | GAnyMono | Literature | Ferreira et al. (2022) |
| `lorentz_nonhomogeneous_quadratic(A, b, c, p)` | Lorentz | AnySign | GConvex | AnyMono | Literature | Ferreira et al. (2023) |
| `lorentz_least_squares(X, y, p)` | Lorentz | Positive | GConvex | AnyMono | Literature | Ferreira et al. (2023) |

## Standard DCP Atoms

These atoms follow standard Disciplined Convex Programming rules and are defined on Euclidean domains. They can be composed with DGCP atoms through scalar composition rules.

### Affine Atoms

| Atom | Domain | Sign | Curvature | Monotonicity | Cone Type | Source | Reference |
|------|--------|------|-----------|--------------|-----------|--------|-----------|
| `+` | Real | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `-` | Real | AnySign | Affine | Decreasing | Reals | Literature | Grant & Boyd (2006) |
| `dot(x, y)` | Real arrays | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `sum(x)` | Real arrays | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `tr(X)` | Real matrices | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `diag(X)` | Real matrices | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `diagm(x)` | Real vectors | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `vec(X)` | Real matrices | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `reshape(X)` | Real matrices | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `hcat(...)` | Real vectors | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `vcat(...)` | Real vectors | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `kron(A, B)` | Real matrices | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `triu(X)` | Real matrices | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `cumsum(x)` | Real arrays | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `diff(x)` | Real arrays | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `conv(x, y)` | Real vectors | AnySign | Affine | AnyMono | Reals | Literature | Grant & Boyd (2006) |
| `real(z)` | Complex | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |
| `imag(z)` | Complex | AnySign | Affine | AnyMono | Reals | Literature | Grant & Boyd (2006) |
| `conj(z)` | Complex | AnySign | Affine | AnyMono | Reals | Literature | Grant & Boyd (2006) |
| `adjoint(x)` | Real vectors | AnySign | Affine | Increasing | Reals | Literature | Grant & Boyd (2006) |

### Convex Atoms

| Atom | Domain | Sign | Curvature | Monotonicity | Cone Type | Source | Reference |
|------|--------|------|-----------|--------------|-----------|--------|-----------|
| `abs(x)` | Complex | Positive | Convex | increasing_if_positive | NormOneCone | Literature | Grant & Boyd (2006) |
| `exp(x)` | Real | Positive | Convex | Increasing | ExponentialCone | Literature | Grant & Boyd (2006) |
| `huber(x, M)` | Real | Positive | Convex | increasing_if_positive | SecondOrderCone | Literature | Grant & Boyd (2006) |
| `inv(x)` | Positive Real | Positive | Convex | Decreasing | RotatedSecondOrderCone | Literature | Grant & Boyd (2006) |
| `inv(X)` | Semidefinite | AnySign | Convex | Decreasing | PSDConeTriangle | Literature | Grant & Boyd (2006) |
| `xlogx(x)` | Real | AnySign | Convex | AnyMono | RelativeEntropyCone | Literature | Grant & Boyd (2006) |
| `logistic(x)` | Real | Positive | Convex | Increasing | ExponentialCone | Literature | Grant & Boyd (2006) |
| `max(x, y)` | Real | AnySign | Convex | Increasing | Reals (LP) | Literature | Grant & Boyd (2006) |
| `maximum(x)` | Real arrays | AnySign | Convex | Increasing | Reals (LP) | Literature | Grant & Boyd (2006) |
| `norm(x, p)` | Real arrays, p >= 1 | Positive | Convex | increasing_if_positive | Depends on p (unannotated) | Literature | Grant & Boyd (2006) |
| `dotsort(x, y)` | Real vectors | AnySign | Convex | varying | Reals (LP) | New | - |
| `eigmax(X)` | Symmetric | AnySign | Convex | AnyMono | PSDConeTriangle | Literature | Grant & Boyd (2006) |
| `eigsummax(X, k)` | Symmetric | AnySign | Convex | AnyMono | PSDConeTriangle | New | - |
| `logsumexp(X)` | Real arrays | AnySign | Convex | Increasing | ExponentialCone | Literature | Grant & Boyd (2006) |
| `matrix_frac(x, P)` | Real vector, PD | AnySign | Convex | AnyMono | PSDConeTriangle | Literature | Grant & Boyd (2006) |
| `quad_form(x, P)` | Real vector, PSD | Positive | Convex | (increasing_if_positive, Increasing) | PSDConeTriangle | Literature | Grant & Boyd (2006) |
| `quad_over_lin(x, y)` | Real, Positive | Positive | Convex | (increasing_if_positive, Decreasing) | RotatedSecondOrderCone | Literature | Grant & Boyd (2006) |
| `sum_largest(X, k)` | Real matrices | AnySign | Convex | Increasing | Reals (LP) | Literature | Grant & Boyd (2006) |
| `trinv(X)` | Positive definite | Positive | Convex | AnyMono | PSDConeTriangle | Literature | Grant & Boyd (2006) |
| `tv(x)` | Real vectors | Positive | Convex | AnyMono | NormOneCone | Literature | Grant & Boyd (2006) |
| `invprod(x)` | Positive Real | Positive | Convex | Decreasing | RotatedSecondOrderCone | New | - |
| `rel_entr(x, y)` | Positive Real | AnySign | Convex | (AnyMono, Decreasing) | RelativeEntropyCone | Literature | Grant & Boyd (2006) |
| `kldivergence(p, q)` | Positive vectors | Positive | Convex | AnyMono | RelativeEntropyCone | Literature | Grant & Boyd (2006) |
| `xexpx(x)` | Positive | Positive | Convex | Increasing | ExponentialCone | Literature | Grant & Boyd (2006) |
| `perspective(f, x, s)` | varies | varies | varies | AnyMono | -- | Literature | Grant & Boyd (2006) |

### Concave Atoms

| Atom | Domain | Sign | Curvature | Monotonicity | Cone Type | Source | Reference |
|------|--------|------|-----------|--------------|-----------|--------|-----------|
| `log(x)` | Positive Real | AnySign | Concave | Increasing | ExponentialCone | Literature | Grant & Boyd (2006) |
| `log(X)` | Real matrices | Positive | Concave | Increasing | ExponentialCone | Literature | Grant & Boyd (2006) |
| `log1p(x)` | x > -1 | Negative | Concave | Increasing | ExponentialCone | Literature | Grant & Boyd (2006) |
| `sqrt(x)` | Non-negative | Positive | Concave | Increasing | RotatedSecondOrderCone | Literature | Grant & Boyd (2006) |
| `sqrt(X)` | Semidefinite | Positive | Concave | Increasing | PSDConeTriangle | Literature | Grant & Boyd (2006) |
| `logdet(X)` | Semidefinite | AnySign | Concave | AnyMono | LogDetConeTriangle | Literature | Grant & Boyd (2006) |
| `lognormcdf(x)` | Real | Negative | Concave | Increasing | -- | New | - |
| `min(x, y)` | Real | AnySign | Concave | Increasing | Reals (LP) | Literature | Grant & Boyd (2006) |
| `minimum(x)` | Real arrays | AnySign | Concave | Increasing | Reals (LP) | Literature | Grant & Boyd (2006) |
| `eigmin(X)` | Symmetric | AnySign | Concave | AnyMono | PSDConeTriangle | Literature | Grant & Boyd (2006) |
| `eigsummin(X, k)` | Symmetric | AnySign | Concave | AnyMono | PSDConeTriangle | New | - |
| `geomean(x)` | Positive vectors | Positive | Concave | Increasing | GeometricMeanCone | Literature | Grant & Boyd (2006) |
| `harmmean(x)` | Positive vectors | Positive | Concave | Increasing | RotatedSecondOrderCone | Literature | Grant & Boyd (2006) |
| `sum_smallest(X, k)` | Real matrices | AnySign | Concave | Increasing | Reals (LP) | Literature | Grant & Boyd (2006) |

### Power Atoms

The power function `x^p` has curvature and cone type that depend on the exponent:

| Condition | Domain | Sign | Curvature | Monotonicity | Cone Type | Source |
|-----------|--------|------|-----------|--------------|-----------|--------|
| `p = 1` | Real | AnySign | Affine | Increasing | Reals | Literature |
| `p = 2` | Real | Positive | Convex | increasing_if_positive | RotatedSecondOrderCone | Literature |
| `p` even integer | Real | Positive | Convex | increasing_if_positive | SecondOrderCone | Literature |
| `p` odd integer | Non-negative | Positive | Convex | Increasing | PowerCone | Literature |
| `p > 1` | Non-negative | Positive | Convex | Increasing | PowerCone(1/p) | Literature |
| `0 < p < 1` | Non-negative | Positive | Concave | Increasing | PowerCone(p) | Literature |
| `p < 0` | Positive | Positive | Convex | Increasing | PowerCone(1/(1-p)) | Literature |

## References

- Bacak, M. (2014). *Convex Analysis and Optimization in Hadamard Spaces*. De Gruyter.
- Bhatia, R. (2007). *Positive Definite Matrices*. Princeton University Press.
- Boyd, S. & Vandenberghe, L. (2004). *Convex Optimization*. Cambridge University Press.
- Ferreira, O.P., Nemeth, S.Z. & Zhu, J. (2022). Convexity of sets and quadratic functions on the hyperbolic space. *Journal of Optimization Theory and Applications*.
- Ferreira, O.P., Nemeth, S.Z. & Zhu, J. (2023). Convexity of non-homogeneous quadratic functions on the hyperbolic space. *Journal of Optimization Theory and Applications*.
- Grant, M. & Boyd, S. (2006). Disciplined Convex Programming. In *Global Optimization: From Theory to Implementation*, Springer.
- Sra, S. (2015). Conic Geometric Optimization on the Manifold of Positive Definite Matrices. *SIAM Journal on Optimization*.
- Vishnoi, N.K. (2018). Geodesic Convex Optimization: Differentiation on Manifolds, Geodesics, and Convexity. *arXiv preprint*.
- Wiesel, A. (2012). Geodesic convexity and covariance estimation. *IEEE Transactions on Signal Processing*.

## Notes

- **Domain abbreviations**: SPD = Symmetric Positive Definite matrices, Lorentz = Lorentz model of hyperbolic space, Real = real numbers, PD = Positive Definite, PSD = Positive Semi-Definite
- **Sign**: Indicates the sign of the function output (Positive, Negative, AnySign)
- **G-Curvature**: GConvex = geodesically convex, GConcave = geodesically concave, GLinear = both g-convex and g-concave
- **Monotonicity**: GIncreasing/GDecreasing = increasing/decreasing with respect to the Lowner order for matrix arguments, GAnyMono = monotonicity unknown or not applicable
- **Cone Type**: The MathOptInterface (MOI) cone used in conic form generation. "Reals" or "Reals (LP)" indicates a linear/LP reformulation. "PSDConeTriangle" is short for `PositiveSemidefiniteConeTriangle`. "--" indicates no cone annotation is registered.
- **Source**: "Literature" indicates the atom's g-convexity was established in prior work; "New" indicates atoms introduced or adapted in SymbolicAnalysis.jl

## Usage

To use these atoms in SymbolicAnalysis.jl:

```julia
using SymbolicAnalysis
using Symbolics
using LinearAlgebra
using Manifolds

# Define symbolic matrix
@variables X[1:3, 1:3]

# Create expression using atoms
expr = logdet(X) + tr(X)

# Analyze geodesic convexity
M = SymmetricPositiveDefinite(3)
result = analyze(expr, M)
println(result.gcurvature) # GConvex
```
Loading
Loading