Skip to content

Commit b94bb63

Browse files
odowodow
committed
Re-org README
1 parent 68d5e66 commit b94bb63

File tree

1 file changed

+88
-86
lines changed

1 file changed

+88
-86
lines changed

‎README.md‎

Lines changed: 88 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -22,87 +22,6 @@ The current list of supported functions and sets is not exhaustive. It is
2222
intended that MathOptFormat will be extended in future versions to support
2323
additional functions and sets.
2424

25-
## The schema
26-
27-
A [JSON schema](http://json-schema.org/) for the `.mof.json` file-format is
28-
provided in the file [`mof.schema.json`](https://github.com/odow/MathOptFormat/blob/master/mof.schema.json).
29-
30-
It is intended for the schema to be self-documenting. Instead of modifying or
31-
adding to this documentation, clarifying edits should be made to the
32-
`description` field of the relevant part of the schema.
33-
34-
### List of supported functions
35-
36-
The list of functions supported by MathOptFormat are contained in the
37-
`#/definitions/scalar_functions` and `#/definitions/vector_functions` fields of
38-
the schema. Scalar functions are functions for which `Mj=1`, while vector
39-
functions are functions for which `Mj≥1`.
40-
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-
60-
### List of supported sets
61-
62-
The list of sets supported by MathOptFormat are contained in the
63-
`#/definitions/scalar_sets` and `#/definitions/vector_sets` fields of the
64-
schema. Scalar sets are sets for which `Mj=1`, while vector sets are sets for
65-
which `Mj≥1`.
66-
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-
10625
## An example
10726

10827
The standard form described above is very general. To give a concrete example,
@@ -176,10 +95,11 @@ required keys at the top level:
17695
- `"function"`
17796

17897
A JSON object that describes the function. There are many different types
179-
of functions that MathOptFormat recognizes, each of which has a different
180-
structure. However, each function has a required key called `"head"` which
181-
is used to describe the type of the function. In this case, the function
182-
is `"ScalarAffineFunction"`.
98+
of functions that MathOptFormat recognizes (see
99+
[List of supported functions](#list-of-supported-functions)), each of
100+
which has a different structure. However, each function has a required key
101+
called `"head"` which is used to describe the type of the function. In
102+
this case, the function is `"ScalarAffineFunction"`.
183103

184104
A `"ScalarAffineFunction"` is the function `f(x) = aᵀx + b`, where `a` is
185105
a constant `N×1` vector, and `b` is a scalar constant. In addition to
@@ -217,13 +137,95 @@ required keys at the top level:
217137

218138
A JSON object that describes the set `Sⱼ` associated with constraint `j`.
219139
In this example, the set `[1, ∞)` is the MathOptFormat set `GreaterThan`
220-
with a lower bound of `1`.
140+
with a lower bound of `1`. See [List of supported sets](#list-of-supported-sets)
141+
for other sets supported by MathOptFormat.
221142

222143
### Other examples
223144

224145
A number of examples of optimization problems encoded using MathOptFormat are
225146
provided in the [`/examples` directory](https://github.com/odow/MathOptFormat/tree/master/examples).
226147

148+
## The schema
149+
150+
A [JSON schema](http://json-schema.org/) for the `.mof.json` file-format is
151+
provided in the file [`mof.schema.json`](https://github.com/odow/MathOptFormat/blob/master/mof.schema.json).
152+
153+
It is intended for the schema to be self-documenting. Instead of modifying or
154+
adding to this documentation, clarifying edits should be made to the
155+
`description` field of the relevant part of the schema.
156+
157+
### List of supported functions
158+
159+
The list of functions supported by MathOptFormat are contained in the
160+
`#/definitions/scalar_functions` and `#/definitions/vector_functions` fields of
161+
the schema. Scalar functions are functions for which `Mj=1`, while vector
162+
functions are functions for which `Mj≥1`.
163+
164+
Here is a summary of the functions defined by MathOptFormat.
165+
166+
#### Scalar Functions
167+
168+
| Name | Description | Example |
169+
| ---- | ----------- | ------- |
170+
| `"SingleVariable"` | The scalar variable `variable`. | {"head": "SingleVariable", "variable": "x"} |
171+
| `"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"}]} |
172+
| `"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"}]} |
173+
| `"Nonlinear"` | An expression graph representing a scalar function. | |
174+
175+
#### Vector Functions
176+
177+
| Name | Description | Example |
178+
| ---- | ----------- | ------- |
179+
| `"VectorOfVariables"` | An ordered list of variables. | {"head": "VectorOfVariables", "variables": ["x", "y"]} |
180+
| `"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"}}]} |
181+
| `"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`. | |
182+
183+
### List of supported sets
184+
185+
The list of sets supported by MathOptFormat are contained in the
186+
`#/definitions/scalar_sets` and `#/definitions/vector_sets` fields of the
187+
schema. Scalar sets are sets for which `Mj=1`, while vector sets are sets for
188+
which `Mj≥1`.
189+
190+
Here is a summary of the sets defined by MathOptFormat.
191+
192+
#### Scalar Sets
193+
194+
| Name | Description | Example |
195+
| ---- | ----------- | ------- |
196+
| `"LessThan"` | (-∞, upper] | {"head": "LessThan", "upper": 2.1} |
197+
| `"GreaterThan"` | [lower, ∞) | {"head": "GreaterThan", "lower": 2.1} |
198+
| `"EqualTo"` | {value} | {"head": "EqualTo", "value": 2.1} |
199+
| `"Interval"` | [lower, upper] | {"head": "Interval", "lower": 2.1, "upper": 3.4} |
200+
| `"Semiinteger"` | {0} ∪ {lower, lower + 1, ..., upper} | {"head": "Semiinteger", "lower": 2, "upper": 4} |
201+
| `"Semicontinuous"` | {0} ∪ [lower, upper] | {"head": "Semicontinuous", "lower": 2.1, "upper": 3.4} |
202+
| `"ZeroOne"` | {0, 1} | {"head": "ZeroOne"} |
203+
| `"Integer"` | ℤ | {"head": "Integer"} |
204+
205+
#### Vector Sets
206+
207+
| Name | Description | Example |
208+
| ---- | ----------- | ------- |
209+
| `"ExponentialCone"` | [x, y, z] ∈ {R³: y * exp(x / y) ≤ z, y ≥ 0} | {"head": "ExponentialCone"} |
210+
| `"DualExponentialCone"` | [u, v, w] ∈ {R³: -u * exp(v / u) ≤ exp(1) * w, u < 0} | {"head": "DualExponentialCone"} |
211+
| `"SOS1"` | A special ordered set of type I. | {"head": "SOS1", "weights": [1, 3, 2]} |
212+
| `"SOS2"` | A special ordered set of type II. | {"head": "SOS2", "weights": [1, 3, 2]} |
213+
| `"GeometricMeanCone"` | [t, x] ∈ {R^{dimension}: t ≤ (Πxᵢ)^{1 / (dimension-1)}} | {"head": "GeometricMeanCone", "dimension": 3} |
214+
| `"SecondOrderCone"` | [t, x] ∈ {R^{dimension} : t ≥ \|\|x\|\|₂ | {"head": "SecondOrderCone", "dimension": 3} |
215+
| `"RotatedSecondOrderCone"` | [t, u, x] ∈ {R^{dimension} : 2tu ≥ (\|\|x\|\|₂)²; t, u ≥ 0} | {"head": "RotatedSecondOrderCone", "dimension": 3} |
216+
| `"Zeros"` | {0}^{dimension} | {"head": "Zeros", "dimension": 3} |
217+
| `"Reals"` | R^{dimension} | {"head": "Reals", "dimension": 3} |
218+
| `"Nonpositives"` | R₋^{dimension} | {"head": "Nonpositives", "dimension": 3} |
219+
| `"Nonnegatives"` | R₊^{dimension} | {"head": "Nonnegatives", "dimension": 3} |
220+
| `"RootDetConeTriangle"` | | |
221+
| `"RootDetConeSquare"` | | |
222+
| `"LogDetConeTriangle"` | | |
223+
| `"LogDetConeSquare"` | | |
224+
| `"PositiveSemidefiniteConeTriangle"` | | |
225+
| `"PositiveSemidefiniteConeSquare"` | | |
226+
| `"PowerCone"` | [x, y, z] ∈ {R³: x^{exponent} y^{1-exponent} ≥ \|z\|; x, y ≥ 0} | {"head": "PowerCone", "exponent": 2.0} |
227+
| `"DualPowerCone"` | [u, v, w] ∈ {R³: (u / exponent)^{exponent} (v / (1-exponent))^{1-exponent} ≥ \|w\|; u, v ≥ 0} | {"head": "DualPowerCone", "exponent": 2.0} |
228+
227229
## Implementations
228230

229231
- Julia

0 commit comments

Comments
 (0)