Add NL docs

Author: odow

README.md

@@ -182,6 +182,110 @@ Here is a summary of the functions defined by MathOptFormat.
 | `"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"}}]} |
 | `"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`. |  |
 
+#### Nonlinear functions
+
+Nonlinear functions are encoded in MathOptFormat by an expression graph. Each
+expression graphs is stored in Polish prefix notation. For example, the
+nonlinear expression `sin²(x)` is expressed as `^(sin(x), 2)`.
+
+The expression graph is stored as an object with three required fields:
+`"head"`, which must be `"Nonlinear"`, as well as `"root"` and `"node_list"`.
+
+`"root"` contains an object defining the root node of the expression graph. All
+other nodes are stored as a flattened list in the `"node\_list"` field. We
+elaborate on permissible nodes and how to store them in the following
+subsections.
+
+##### Leaf nodes
+
+Leaf nodes in the expression graph are data: they can either reference
+optimization variables, or be real or complex valued numeric constants. They are
+described as follows.
+
+| Head | Description | Example |
+| ---- | ----------- | ------- |
+| `"real"` | A real-valued numeric constant | {"head": "real", "value": 1.0} |
+| `"complex"` | A complex-valued numeric constant | {"head": "complex", "real": 1.0, "imag": 2.0} |
+| `"variable"` | A reference to an optimization variable | {"head": "variable", "name": "x"} |
+
+Nodes in the flattened list `"node_list"` can be referenced by an object with
+the `"head"` field `"node"` and a field `"index"` that is the one-based index of
+the node in `"node_list"`.
+
+| Head | Description | Example |
+| ---- | ----------- | ------- |
+| `"node"` | A pointer to a (1-indexed) element in the `node_list` field in a nonlinear function | {"head": "node", "index": 2} |
+
+##### Other nodes
+
+| Name | Arity |
+| `"log"` | Unary |
+| `"log10"` | Unary |
+| `"exp"` | Unary |
+| `"sqrt"` | Unary |
+| `"floor"` | Unary |
+| `"ceil"` | Unary |
+| `"abs"` | Unary |
+| `"cos"` | Unary |
+| `"sin"` | Unary |
+| `"tan"` | Unary |
+| `"acos"` | Unary |
+| `"asin"` | Unary |
+| `"atan"` | Unary |
+| `"cosh"` | Unary |
+| `"sinh"` | Unary |
+| `"tanh"` | Unary |
+| `"acosh"` | Unary |
+| `"asinh"` | Unary |
+| `"atanh"` | Unary |
+| `"/"` | Binary |
+| `"^"` | Binary |
+| `"+"` | N-ary |
+| `"-"` | N-ary |
+| `"*"` | N-ary |
+| `"min"` | N-ary |
+| `"max"` | N-ary |
+
+##### Example
+
+As an example, consider the function `f(x, y) = (1 + 3i) ⋅ x + sin^2(x) + y`.
+In Polish notation, the expression graph is:
+```f(x, y) = +(1 + 3i, ^(sin(x), 2), y)
+```
+In MathOptFormat, this expression graph can be encoded as follows:
+```json
+{
+    "head": "Nonlinear",
+    "root": {
+        "head": "+",
+        "args": [
+            {"head": "node", "index": 1},
+            {"head": "node", "index": 3},
+            {"head": "variable", "name": "y"}
+        ]
+    },
+    "node_list": [
+        {
+            "head": "*", "args": [
+                {"head": "complex", "real": 1, "imag": 3},
+                {"head": "variable", "name": "x"}
+            ]
+        }, {
+            "head": "sin",
+            "args": [
+                {"head": "variable", "name": "x"}
+            ]
+        }, {
+            "head": "^",
+            "args": [
+                {"head": "node", "index": 2},
+                {"head": "real", "value": 2}
+            ]
+        }
+    ]
+}
+```
+
 ### List of supported sets
 
 The list of sets supported by MathOptFormat are contained in the

mof.schema.json

@@ -154,7 +154,7 @@
             "type": "object",
             "required": ["head"],
             "oneOf": [{
-                "description": "Unary operators.",
+                "description": "Unary operators",
                 "required": ["args"],
                 "properties": {
                     "head": {
@@ -174,7 +174,7 @@
                     }
                 }
             }, {
-                "description": "Binary operators.",
+                "description": "Binary operators",
                 "required": ["args"],
                 "properties": {
                     "head": {
@@ -190,7 +190,7 @@
                     }
                 }
             }, {
-                "description": "N-ary operators.",
+                "description": "N-ary operators",
                 "required": ["args"],
                 "properties": {
                     "head": {
@@ -205,7 +205,8 @@
                     }
                 }
             }, {
-                "description": "A real-valued numeric constant.",
+                "description": "A real-valued numeric constant",
+                "example": "{\"head\": \"real\", \"value\": 1.0}",
                 "required": ["value"],
                 "properties": {
                     "head": {
@@ -216,7 +217,8 @@
                     }
                 }
             }, {
-                "description": "A complex-valued numeric constant.",
+                "description": "A complex-valued numeric constant",
+                "example": "{\"head\": \"complex\", \"real\": 1.0, \"imag\": 2.0}",
                 "required": ["real", "imag"],
                 "properties": {
                     "head": {
@@ -231,6 +233,7 @@
                 }
             }, {
                 "description": "A reference to an optimization variable",
+                "example": "{\"head\": \"variable\", \"name\": \"x\"}",
                 "required": ["name"],
                 "properties": {
                     "head": {
@@ -242,6 +245,7 @@
                 }
             }, {
                 "description": "A pointer to a (1-indexed) element in the `node_list` field in a nonlinear function",
+                "example": "{\"head\": \"node\", \"index\": 2}",
                 "required": ["index"],
                 "properties": {
                     "head": {

readme_builder/readme_builder.go

@@ -128,7 +128,8 @@ func generateDocs(jsonSchemaFilename string) (string, string, error) {
 		"",
 		processStrings("Vector Functions", data, "vector_functions")}, "\n")
 
-	return setSummary, functionSummary, nil
+	nlSummary := processNonlinear(data)
+	return setSummary, functionSummary + nlSummary, nil
 }
 
 func processStrings(title string, data map[string]interface{}, key string) string {
@@ -148,3 +149,51 @@ func processStrings(title string, data map[string]interface{}, key string) strin
 	}
 	return strings.Join(setStrings, "\n")
 }
+
+func processNonlinear(data map[string]interface{}) string {
+	definitions := data["definitions"].(map[string]interface{})
+	nonlinearTerm := definitions["NonlinearTerm"].(map[string]interface{})
+	functionStrings := []string{
+		"##### Functions",
+		"",
+		"| Name | Arity |"}
+
+	leafStrings := []string{
+		"#### Nonlinear functions",
+		"",
+		"##### Leaf nodes",
+		"| Name | Description | Example |",
+		"| ---- | ----------- | ------- |"}
+
+	for _, setData := range nonlinearTerm["oneOf"].([]interface{}) {
+		object := setData.(map[string]interface{})
+		objects := processOneOf(object)
+
+		switch object["description"] {
+		case "Unary operators":
+			for _, f := range objects {
+				functionStrings = append(functionStrings,
+					fmt.Sprintf("| `\"%s\"` | Unary |", f.Head))
+			}
+		case "Binary operators":
+			for _, f := range objects {
+				functionStrings = append(functionStrings,
+					fmt.Sprintf("| `\"%s\"` | Binary |", f.Head))
+			}
+		case "N-ary operators":
+			for _, f := range objects {
+				functionStrings = append(functionStrings,
+					fmt.Sprintf("| `\"%s\"` | N-ary |", f.Head))
+			}
+		default:
+			if len(objects) == 1 {
+				leafStrings = append(leafStrings,
+					fmt.Sprintf("| `\"%s\"` | %s | %s |", objects[0].Head, objects[0].Description, objects[0].Example))
+			} else {
+				fmt.Println("Unsupported object: %s", object)
+			}
+		}
+	}
+	return "\n" + strings.Join(leafStrings, "\n") + "\n\n" +
+		strings.Join(functionStrings, "\n")
+}