Skip to content

Commit 8d0a439

Browse files
committed
Add documentation for matrix cones
1 parent 67d22e0 commit 8d0a439

File tree

2 files changed

+76
-14
lines changed

2 files changed

+76
-14
lines changed

README.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,7 @@ Here is a summary of the functions defined by MathOptFormat.
171171
| ---- | ----------- | ------- |
172172
| `"SingleVariable"` | The scalar variable `variable`. | {"head": "SingleVariable", "variable": "x"} |
173173
| `"ScalarAffineFunction"` | The function `a'x + b`, where `a` is a sparse vector specified by a list of `ScalarAffineTerm`s in `terms` and `b` is the scalar in `constant`. Duplicate variables in `terms` are accepted, and the corresponding coefficients are summed together. | {"head": "ScalarAffineFunction", "constant": 1.0, "terms": [{"coefficient": 2.5, "variable": "x"}]} |
174-
| `"ScalarQuadraticFunction"` | The function `0.5x'Qx + a'x + b`, where `a` is a sparse vector of `ScalarAffineTerm`s in `affine_terms`, `b` is the scalar `constant`, and `Q` is a symmetric matrix specified by a list of `ScalarQuadraticTerm`s in `quadratic_terms`. Duplicate indices in `affine_terms` and `quadratic` are accepted, and the corresponding coefficients are summed together. Mirrored indices in `quadratic_terms` (i.e., `(i,j)` and `(j, i)`) are considered duplicates; only one need to be specified. | {"head": "ScalarAffineFunction", "constant": 1.0, "affine_terms": [{"coefficient": 2.5, "variable": "x"}], "quadratic_terms": [{"coefficient": 2.0, "variable_1": "x", "variable_2": "y"}]} |
174+
| `"ScalarQuadraticFunction"` | The function `0.5x'Qx + a'x + b`, where `a` is a sparse vector of `ScalarAffineTerm`s in `affine_terms`, `b` is the scalar `constant`, and `Q` is a symmetric matrix specified by a list of `ScalarQuadraticTerm`s in `quadratic_terms`. Duplicate indices in `affine_terms` and `quadratic` are accepted, and the corresponding coefficients are summed together. Mirrored indices in `quadratic_terms` (i.e., `(i,j)` and `(j, i)`) are considered duplicates; only one need to be specified. | {"head": "ScalarQuadraticFunction", "constant": 1.0, "affine_terms": [{"coefficient": 2.5, "variable": "x"}], "quadratic_terms": [{"coefficient": 2.0, "variable_1": "x", "variable_2": "y"}]} |
175175
| `"ScalarNonlinearFunction"` | An expression graph representing a scalar nonlinear function. | |
176176

177177

@@ -223,12 +223,12 @@ Here is a summary of the sets defined by MathOptFormat.
223223
| `"Reals"` | R^{dimension} | {"head": "Reals", "dimension": 3} |
224224
| `"Nonpositives"` | R₋^{dimension} | {"head": "Nonpositives", "dimension": 3} |
225225
| `"Nonnegatives"` | R₊^{dimension} | {"head": "Nonnegatives", "dimension": 3} |
226-
| `"RootDetConeTriangle"` | | |
227-
| `"RootDetConeSquare"` | | |
228-
| `"LogDetConeTriangle"` | | |
229-
| `"LogDetConeSquare"` | | |
230-
| `"PositiveSemidefiniteConeTriangle"` | | |
231-
| `"PositiveSemidefiniteConeSquare"` | | |
226+
| `"RootDetConeTriangle"` | {[t, X] ∈ R^{1 + d(d+1)/2} : t ≤ det(X)^{1/d}}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeTriangle`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns. | {"head": "RootDetConeTriangle", "side_dimension": 2} |
227+
| `"RootDetConeSquare"` | {[t, X] ∈ R^{1 + d^2} : t ≤ det(X)^{1/d}, X symmetric}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeSquare`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns. | {"head": "RootDetConeSquare", "side_dimension": 2} |
228+
| `"LogDetConeTriangle"` | {[t, u, X] ∈ R^{2 + d(d+1)/2} : t ≤ u log(det(X/u)), u > 0}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeTriangle`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns. | {"head": "LogDetConeTriangle", "side_dimension": 2} |
229+
| `"LogDetConeSquare"` | {[t, u, X] ∈ R^{2 + d^2} : t ≤ u log(det(X/u)), X symmetric, u > 0}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeSquare`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns. | {"head": "LogDetConeSquare", "side_dimension": 2} |
230+
| `"PositiveSemidefiniteConeTriangle"` | The (vectorized) cone of symmetric positive semidefinite matrices, with `side_dimension` rows and columns. The entries of the upper-right triangular part of the matrix are given column by column (or equivalently, the entries of the lower-left triangular part are given row by row). | {"head": "PositiveSemidefiniteConeTriangle", "side_dimension": 2} |
231+
| `"PositiveSemidefiniteConeSquare"` | The cone of symmetric positive semidefinite matrices, with side length `side_dimension`. The entries of the matrix are given column by column (or equivalently, row by row). The matrix is both constrained to be symmetric and to be positive semidefinite. That is, if the functions in entries `(i, j)` and `(j, i)` are different, then a constraint will be added to make sure that the entries are equal. | {"head": "PositiveSemidefiniteConeSquare", "side_dimension": 2} |
232232
| `"PowerCone"` | [x, y, z] ∈ {R³: x^{exponent} y^{1-exponent} ≥ \|z\|; x, y ≥ 0} | {"head": "PowerCone", "exponent": 2.0} |
233233
| `"DualPowerCone"` | [u, v, w] ∈ {R³: (u / exponent)^{exponent} (v / (1-exponent))^{1-exponent} ≥ \|w\|; u, v ≥ 0} | {"head": "DualPowerCone", "exponent": 2.0} |
234234

mof.schema.json

Lines changed: 69 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -294,7 +294,7 @@
294294
}
295295
}, {
296296
"description": "The function `0.5x'Qx + a'x + b`, where `a` is a sparse vector of `ScalarAffineTerm`s in `affine_terms`, `b` is the scalar `constant`, and `Q` is a symmetric matrix specified by a list of `ScalarQuadraticTerm`s in `quadratic_terms`. Duplicate indices in `affine_terms` and `quadratic` are accepted, and the corresponding coefficients are summed together. Mirrored indices in `quadratic_terms` (i.e., `(i,j)` and `(j, i)`) are considered duplicates; only one need to be specified.",
297-
"examples": ["{\"head\": \"ScalarAffineFunction\", \"constant\": 1.0, \"affine_terms\": [{\"coefficient\": 2.5, \"variable\": \"x\"}], \"quadratic_terms\": [{\"coefficient\": 2.0, \"variable_1\": \"x\", \"variable_2\": \"y\"}]}"],
297+
"examples": ["{\"head\": \"ScalarQuadraticFunction\", \"constant\": 1.0, \"affine_terms\": [{\"coefficient\": 2.5, \"variable\": \"x\"}], \"quadratic_terms\": [{\"coefficient\": 2.0, \"variable_1\": \"x\", \"variable_2\": \"y\"}]}"],
298298
"required": ["constant", "affine_terms", "quadratic_terms"],
299299
"properties": {
300300
"head": {
@@ -648,15 +648,77 @@
648648
}
649649
}
650650
}, {
651+
"description": "{[t, X] ∈ R^{1 + d(d+1)/2} : t ≤ det(X)^{1/d}}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeTriangle`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns.",
652+
"examples": ["{\"head\": \"RootDetConeTriangle\", \"side_dimension\": 2}"],
651653
"required": ["side_dimension"],
652654
"properties": {
653655
"head": {
654-
"enum": [
655-
"RootDetConeTriangle", "RootDetConeSquare",
656-
"LogDetConeTriangle", "LogDetConeSquare",
657-
"PositiveSemidefiniteConeTriangle",
658-
"PositiveSemidefiniteConeSquare"
659-
]
656+
"const": "RootDetConeTriangle"
657+
},
658+
"side_dimension": {
659+
"type": "integer",
660+
"minimum": 1
661+
}
662+
}
663+
}, {
664+
"description": "{[t, X] ∈ R^{1 + d^2} : t ≤ det(X)^{1/d}, X symmetric}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeSquare`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns.",
665+
"examples": ["{\"head\": \"RootDetConeSquare\", \"side_dimension\": 2}"],
666+
"required": ["side_dimension"],
667+
"properties": {
668+
"head": {
669+
"const": "RootDetConeSquare"
670+
},
671+
"side_dimension": {
672+
"type": "integer",
673+
"minimum": 1
674+
}
675+
}
676+
}, {
677+
"description": "{[t, u, X] ∈ R^{2 + d(d+1)/2} : t ≤ u log(det(X/u)), u > 0}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeTriangle`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns.",
678+
"examples": ["{\"head\": \"LogDetConeTriangle\", \"side_dimension\": 2}"],
679+
"required": ["side_dimension"],
680+
"properties": {
681+
"head": {
682+
"const": "LogDetConeTriangle"
683+
},
684+
"side_dimension": {
685+
"type": "integer",
686+
"minimum": 1
687+
}
688+
}
689+
}, {
690+
"description": "{[t, u, X] ∈ R^{2 + d^2} : t ≤ u log(det(X/u)), X symmetric, u > 0}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeSquare`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns.",
691+
"examples": ["{\"head\": \"LogDetConeSquare\", \"side_dimension\": 2}"],
692+
"required": ["side_dimension"],
693+
"properties": {
694+
"head": {
695+
"const": "LogDetConeSquare"
696+
},
697+
"side_dimension": {
698+
"type": "integer",
699+
"minimum": 1
700+
}
701+
}
702+
}, {
703+
"description": "The (vectorized) cone of symmetric positive semidefinite matrices, with `side_dimension` rows and columns. The entries of the upper-right triangular part of the matrix are given column by column (or equivalently, the entries of the lower-left triangular part are given row by row).",
704+
"examples": ["{\"head\": \"PositiveSemidefiniteConeTriangle\", \"side_dimension\": 2}"],
705+
"required": ["side_dimension"],
706+
"properties": {
707+
"head": {
708+
"const": "PositiveSemidefiniteConeTriangle"
709+
},
710+
"side_dimension": {
711+
"type": "integer",
712+
"minimum": 1
713+
}
714+
}
715+
}, {
716+
"description": "The cone of symmetric positive semidefinite matrices, with side length `side_dimension`. The entries of the matrix are given column by column (or equivalently, row by row). The matrix is both constrained to be symmetric and to be positive semidefinite. That is, if the functions in entries `(i, j)` and `(j, i)` are different, then a constraint will be added to make sure that the entries are equal.",
717+
"examples": ["{\"head\": \"PositiveSemidefiniteConeSquare\", \"side_dimension\": 2}"],
718+
"required": ["side_dimension"],
719+
"properties": {
720+
"head": {
721+
"const": "PositiveSemidefiniteConeSquare"
660722
},
661723
"side_dimension": {
662724
"type": "integer",

0 commit comments

Comments
 (0)