Skip to content

Commit da4197d

Browse files
odowodow
committed
Add tables to documentation with a golang builder
1 parent 87b34e4 commit da4197d

File tree

4 files changed

+264
-19
lines changed

4 files changed

+264
-19
lines changed

‎README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,71 @@ The list of functions supported by MathOptFormat are contained in the
3838
the schema. Scalar functions are functions for which `Mj=1`, while vector
3939
functions are functions for which `Mj≥1`.
4040

41+
Here is a summary of the functions defined by MathOptFormat.
42+
43+
#### Scalar Functions
44+
45+
| Name | Description | Example |
46+
| ---- | ----------- | ------- |
47+
| `"SingleVariable"` | The scalar variable `variable`. | {"head": "SingleVariable", "variable": "x"} |
48+
| `"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"}]} |
49+
| `"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"}]} |
50+
| `"Nonlinear"` | An expression graph representing a scalar function. | |
51+
52+
#### Vector Functions
53+
54+
| Name | Description | Example |
55+
| ---- | ----------- | ------- |
56+
| `"VectorOfVariables"` | An ordered list of variables. | {"head": "VectorOfVariables", "variables": ["x", "y"]} |
57+
| `"VectorAffineFunction"` | The function `Ax + b`, where `A` is a sparse matrix specified by a list of `VectorAffineTerm`s in `terms` and `b` is a dense vector specified by `constants`. | {"head": "VectorAffineFunction", "constants": [1.0], "terms": [{"output_index": 1, "scalar_term": {"coefficient": 2.5, "variable": "x"}}]} |
58+
| `"VectorQuadraticFunction"` | The vector-valued quadratic function `q(x) + Ax + b`, where `q(x)` is specified by a list of `VectorQuadraticTerm`s in `quadratic_terms`, `A` is a sparse matrix specified by a list of `VectorAffineTerm`s in `affine_terms` and `b` is a dense vector specified by `constants`. | |
59+
4160
### List of supported sets
4261

4362
The list of sets supported by MathOptFormat are contained in the
4463
`#/definitions/scalar_sets` and `#/definitions/vector_sets` fields of the
4564
schema. Scalar sets are sets for which `Mj=1`, while vector sets are sets for
4665
which `Mj≥1`.
4766

67+
Here is a summary of the sets defined by MathOptFormat.
68+
69+
#### Scalar Sets
70+
71+
| Name | Description | Example |
72+
| ---- | ----------- | ------- |
73+
| `"LessThan"` | (-∞, upper] | {"head": "LessThan", "upper": 2.1} |
74+
| `"GreaterThan"` | [lower, ∞) | {"head": "GreaterThan", "lower": 2.1} |
75+
| `"EqualTo"` | {value} | {"head": "EqualTo", "value": 2.1} |
76+
| `"Interval"` | [lower, upper] | {"head": "Interval", "lower": 2.1, "upper": 3.4} |
77+
| `"Semiinteger"` | {0} ∪ {lower, lower + 1, ..., upper} | {"head": "Semiinteger", "lower": 2, "upper": 4} |
78+
| `"Semicontinuous"` | {0} ∪ [lower, upper] | {"head": "Semicontinuous", "lower": 2.1, "upper": 3.4} |
79+
| `"ZeroOne"` | {0, 1} | {"head": "ZeroOne"} |
80+
| `"Integer"` | ℤ | {"head": "Integer"} |
81+
82+
#### Vector Sets
83+
84+
| Name | Description | Example |
85+
| ---- | ----------- | ------- |
86+
| `"ExponentialCone"` | [x, y, z] ∈ {R³: y * exp(x / y) ≤ z, y ≥ 0} | {"head": "ExponentialCone"} |
87+
| `"DualExponentialCone"` | [u, v, w] ∈ {R³: -u * exp(v / u) ≤ exp(1) * w, u < 0} | {"head": "DualExponentialCone"} |
88+
| `"SOS1"` | A special ordered set of type I. | {"head": "SOS1", "weights": [1, 3, 2]} |
89+
| `"SOS2"` | A special ordered set of type II. | {"head": "SOS2", "weights": [1, 3, 2]} |
90+
| `"GeometricMeanCone"` | [t, x] ∈ {R^{dimension}: t ≤ (Πxᵢ)^{1 / (dimension-1)}} | {"head": "GeometricMeanCone", "dimension": 3} |
91+
| `"SecondOrderCone"` | [t, x] ∈ {R^{dimension} : t ≥ \|\|x\|\|₂ | {"head": "SecondOrderCone", "dimension": 3} |
92+
| `"RotatedSecondOrderCone"` | [t, u, x] ∈ {R^{dimension} : 2tu ≥ (\|\|x\|\|₂)²; t, u ≥ 0} | {"head": "RotatedSecondOrderCone", "dimension": 3} |
93+
| `"Zeros"` | {0}^{dimension} | {"head": "Zeros", "dimension": 3} |
94+
| `"Reals"` | R^{dimension} | {"head": "Reals", "dimension": 3} |
95+
| `"Nonpositives"` | R₋^{dimension} | {"head": "Nonpositives", "dimension": 3} |
96+
| `"Nonnegatives"` | R₊^{dimension} | {"head": "Nonnegatives", "dimension": 3} |
97+
| `"RootDetConeTriangle"` | | |
98+
| `"RootDetConeSquare"` | | |
99+
| `"LogDetConeTriangle"` | | |
100+
| `"LogDetConeSquare"` | | |
101+
| `"PositiveSemidefiniteConeTriangle"` | | |
102+
| `"PositiveSemidefiniteConeSquare"` | | |
103+
| `"PowerCone"` | [x, y, z] ∈ {R³: x^{exponent} y^{1-exponent} ≥ \|z\|; x, y ≥ 0} | {"head": "PowerCone", "exponent": 2.0} |
104+
| `"DualPowerCone"` | [u, v, w] ∈ {R³: (u / exponent)^{exponent} (v / (1-exponent))^{1-exponent} ≥ \|w\|; u, v ≥ 0} | {"head": "DualPowerCone", "exponent": 2.0} |
105+
48106
## An example
49107

50108
The standard form described above is very general. To give a concrete example,

‎mof.schema.json‎

Lines changed: 45 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,7 @@
260260
"required": ["head"],
261261
"oneOf": [{
262262
"description": "The scalar variable `variable`.",
263+
"example": "{\"head\": \"SingleVariable\", \"variable\": \"x\"}",
263264
"required": ["variable"],
264265
"properties": {
265266
"head": {
@@ -271,6 +272,7 @@
271272
}
272273
}, {
273274
"description": "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.",
275+
"example": "{\"head\": \"ScalarAffineFunction\", \"constant\": 1.0, \"terms\": [{\"coefficient\": 2.5, \"variable\": \"x\"}]}",
274276
"required": ["constant", "terms"],
275277
"properties": {
276278
"head": {
@@ -288,6 +290,7 @@
288290
}
289291
}, {
290292
"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.",
293+
"example": "{\"head\": \"ScalarAffineFunction\", \"constant\": 1.0, \"affine_terms\": [{\"coefficient\": 2.5, \"variable\": \"x\"}], \"quadratic_terms\": [{\"coefficient\": 2.0, \"variable_1\": \"x\", \"variable_2\": \"y\"}]}",
291294
"required": ["constant", "affine_terms", "quadratic_terms"],
292295
"properties": {
293296
"head": {
@@ -334,6 +337,7 @@
334337
"required": ["head"],
335338
"oneOf": [{
336339
"description": "An ordered list of variables.",
340+
"example": "{\"head\": \"VectorOfVariables\", \"variables\": [\"x\", \"y\"]}",
337341
"required": ["variables"],
338342
"properties": {
339343
"head": {
@@ -348,6 +352,7 @@
348352
}
349353
}, {
350354
"description": "The function `Ax + b`, where `A` is a sparse matrix specified by a list of `VectorAffineTerm`s in `terms` and `b` is a dense vector specified by `constants`.",
355+
"example": "{\"head\": \"VectorAffineFunction\", \"constants\": [1.0], \"terms\": [{\"output_index\": 1, \"scalar_term\": {\"coefficient\": 2.5, \"variable\": \"x\"}}]}",
351356
"required": ["constants", "terms"],
352357
"properties": {
353358
"head": {
@@ -399,7 +404,8 @@
399404
"type": "object",
400405
"required": ["head"],
401406
"oneOf": [{
402-
"description": "The set `(-inf, upper]`.",
407+
"description": "(-∞, upper]",
408+
"example": "{\"head\": \"LessThan\", \"upper\": 2.1}",
403409
"required": ["upper"],
404410
"properties": {
405411
"head": {
@@ -410,7 +416,8 @@
410416
}
411417
}
412418
}, {
413-
"description": "The set `[lower, upper)`.",
419+
"description": "[lower, ∞)",
420+
"example": "{\"head\": \"GreaterThan\", \"lower\": 2.1}",
414421
"required": ["lower"],
415422
"properties": {
416423
"head": {
@@ -421,7 +428,8 @@
421428
}
422429
}
423430
}, {
424-
"description": "The set `{value}`.",
431+
"description": "{value}",
432+
"example": "{\"head\": \"EqualTo\", \"value\": 2.1}",
425433
"required": ["value"],
426434
"properties": {
427435
"head": {
@@ -432,7 +440,8 @@
432440
}
433441
}
434442
}, {
435-
"description": "The set `[lower, upper]`.",
443+
"description": "[lower, upper]",
444+
"example": "{\"head\": \"Interval\", \"lower\": 2.1, \"upper\": 3.4}",
436445
"required": ["lower", "upper"],
437446
"properties": {
438447
"head": {
@@ -446,7 +455,8 @@
446455
}
447456
}
448457
}, {
449-
"description": "The set `{0} ∪ {lower, lower + 1, ..., upper}`.",
458+
"description": "{0} ∪ {lower, lower + 1, ..., upper}",
459+
"example": "{\"head\": \"Semiinteger\", \"lower\": 2, \"upper\": 4}",
450460
"required": ["lower", "upper"],
451461
"properties": {
452462
"head": {
@@ -460,7 +470,8 @@
460470
}
461471
}
462472
}, {
463-
"description": "The set `{0} ∪ [lower, upper]`.",
473+
"description": "{0} ∪ [lower, upper]",
474+
"example": "{\"head\": \"Semicontinuous\", \"lower\": 2.1, \"upper\": 3.4}",
464475
"required": ["lower", "upper"],
465476
"properties": {
466477
"head": {
@@ -474,14 +485,16 @@
474485
}
475486
}
476487
}, {
477-
"description": "The set `{0, 1}`.",
488+
"description": "{0, 1}",
489+
"example": "{\"head\": \"ZeroOne\"}",
478490
"properties": {
479491
"head": {
480492
"const": "ZeroOne"
481493
}
482494
}
483495
}, {
484-
"description": "The set `ℤ`.",
496+
"description": "ℤ",
497+
"example": "{\"head\": \"Integer\"}",
485498
"properties": {
486499
"head": {
487500
"const": "Integer"
@@ -494,21 +507,24 @@
494507
"type": "object",
495508
"required": ["head"],
496509
"oneOf": [{
497-
"description": "The cone `[x, y, z] ∈ {R³: y * exp(x / y) ≤ z, y ≥ 0}`.",
510+
"description": "[x, y, z] ∈ {R³: y * exp(x / y) ≤ z, y ≥ 0}",
511+
"example": "{\"head\": \"ExponentialCone\"}",
498512
"properties": {
499513
"head": {
500514
"const": "ExponentialCone"
501515
}
502516
}
503517
}, {
504-
"description": "The cone `[u, v, w] ∈ {R³: -u * exp(v / u) ≤ exp(1) * w, u < 0}`.",
518+
"description": "[u, v, w] ∈ {R³: -u * exp(v / u) ≤ exp(1) * w, u < 0}",
519+
"example": "{\"head\": \"DualExponentialCone\"}",
505520
"properties": {
506521
"head": {
507522
"const": "DualExponentialCone"
508523
}
509524
}
510525
}, {
511526
"description": "A special ordered set of type I.",
527+
"example": "{\"head\": \"SOS1\", \"weights\": [1, 3, 2]}",
512528
"required": ["weights"],
513529
"properties": {
514530
"head": {
@@ -523,6 +539,7 @@
523539
}
524540
}, {
525541
"description": "A special ordered set of type II.",
542+
"example": "{\"head\": \"SOS2\", \"weights\": [1, 3, 2]}",
526543
"required": ["weights"],
527544
"properties": {
528545
"head": {
@@ -536,7 +553,8 @@
536553
}
537554
}
538555
}, {
539-
"description": "The cone `[t, x] ∈ {R^{dimension}: t ≤ (Πxᵢ)^{1 / (dimension-1)}}`.",
556+
"description": "[t, x] ∈ {R^{dimension}: t ≤ (Πxᵢ)^{1 / (dimension-1)}}",
557+
"example": "{\"head\": \"GeometricMeanCone\", \"dimension\": 3}",
540558
"required": ["dimension"],
541559
"properties": {
542560
"head": {
@@ -548,7 +566,8 @@
548566
}
549567
}
550568
}, {
551-
"description": "The cone `[t, x] ∈ {R^{dimension} : t ≥ ||x||₂.",
569+
"description": "[t, x] ∈ {R^{dimension} : t ≥ ||x||₂",
570+
"example": "{\"head\": \"SecondOrderCone\", \"dimension\": 3}",
552571
"required": ["dimension"],
553572
"properties": {
554573
"head": {
@@ -560,7 +579,8 @@
560579
}
561580
}
562581
}, {
563-
"description": "The cone `[t, u, x] ∈ {R^{dimension} : 2tu ≥ (||x||₂)²; t, u ≥ 0}.",
582+
"description": "[t, u, x] ∈ {R^{dimension} : 2tu ≥ (||x||₂)²; t, u ≥ 0}",
583+
"example": "{\"head\": \"RotatedSecondOrderCone\", \"dimension\": 3}",
564584
"required": ["dimension"],
565585
"properties": {
566586
"head": {
@@ -572,7 +592,8 @@
572592
}
573593
}
574594
}, {
575-
"description": "The set `{0}^{dimension}`.",
595+
"description": "{0}^{dimension}",
596+
"example": "{\"head\": \"Zeros\", \"dimension\": 3}",
576597
"required": ["dimension"],
577598
"properties": {
578599
"head": {
@@ -584,7 +605,8 @@
584605
}
585606
}
586607
}, {
587-
"description": "The set `R^{dimension}`.",
608+
"description": "R^{dimension}",
609+
"example": "{\"head\": \"Reals\", \"dimension\": 3}",
588610
"required": ["dimension"],
589611
"properties": {
590612
"head": {
@@ -596,7 +618,8 @@
596618
}
597619
}
598620
}, {
599-
"description": "The set `R₋^{dimension}`.",
621+
"description": "R₋^{dimension}",
622+
"example": "{\"head\": \"Nonpositives\", \"dimension\": 3}",
600623
"required": ["dimension"],
601624
"properties": {
602625
"head": {
@@ -608,7 +631,8 @@
608631
}
609632
}
610633
}, {
611-
"description": "The set `R₊^{dimension}`.",
634+
"description": "R₊^{dimension}",
635+
"example": "{\"head\": \"Nonnegatives\", \"dimension\": 3}",
612636
"required": ["dimension"],
613637
"properties": {
614638
"head": {
@@ -636,7 +660,8 @@
636660
}
637661
}
638662
}, {
639-
"description": "The cone `[x, y, z] ∈ {R³: x^{exponent} y^{1-exponent} ≥ |z|; x, y ≥ 0}`.",
663+
"description": "[x, y, z] ∈ {R³: x^{exponent} y^{1-exponent} ≥ |z|; x, y ≥ 0}",
664+
"example": "{\"head\": \"PowerCone\", \"exponent\": 2.0}",
640665
"required": ["exponent"],
641666
"properties": {
642667
"head": {
@@ -647,7 +672,8 @@
647672
}
648673
}
649674
}, {
650-
"description": "The cone `[u, v, w] ∈ {R³: (u / exponent)^{exponent} (v / (1-exponent))^{1-exponent} ≥ |w|; u, v ≥ 0}`.",
675+
"description": "[u, v, w] ∈ {R³: (u / exponent)^{exponent} (v / (1-exponent))^{1-exponent} ≥ |w|; u, v ≥ 0}",
676+
"example": "{\"head\": \"DualPowerCone\", \"exponent\": 2.0}",
651677
"required": ["exponent"],
652678
"properties": {
653679
"head": {

‎readme_builder/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*.exe
2+
*.md
3+
*.bat

0 commit comments

Comments
 (0)