adding docs for operators (#598)

* write start of L_Plus.md * Plus and Minus docs and its notebook * wrote doc pages for all the operators. * fix to meet agreed format * Created using Colaboratory * add multiplicationDemonstration.ipynb * add absoluteValues.ipynb * add factorial.ipynb * add toInt_demonstration.ipynb * fixed absoluteValues.ipynb * added notebook links * fixed L_Minus.md typo * improved these notebooks with hz66-404 suggestions * fixed typo
conjure-cp · Nov 2, 2023 · 37112e0 · 37112e0
1 parent 4f39a3d
commit 37112e0
Show file tree

Hide file tree

Showing 14 changed files with 1,621 additions and 2 deletions.
diff --git a/docs/bits/function/toInt.md b/docs/bits/function/toInt.md
@@ -0,0 +1,7 @@
+# toInt
+
+```boolean --> integer```
+This function converts a boolean value to an integer. 
+```false``` values map to ```0``` and ```true``` values map to ```1```.
+
+See how this works [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/toInt_demonstration.ipynb).
diff --git a/docs/bits/operator/L_Div.md b/docs/bits/operator/L_Div.md
@@ -9,6 +9,6 @@ This is meant to ensure that for integers x and y, y!=0
 ```
 holds 
 
-See a worked example [here](https://github.com/conjure-cp/conjure/tree/main/docs/notebooks/division_and_mod_demonstration.ipynb)
+See a worked example [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/division_and_mod_demonstration.ipynb)
 
-And a slightly more complex example using an instance of the n-fractions puzzle [here](https://github.com/conjure-cp/conjure/tree/main/docs/notebooks/division_n_fractions.ipynb)
+And a slightly more complex example using an instance of the n-fractions puzzle [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/division_n_fractions.ipynb)
diff --git a/docs/bits/operator/L_Minus.md b/docs/bits/operator/L_Minus.md
@@ -0,0 +1,13 @@
+# - (minus)
+The subtraction operator. 
+It is both a unary and a binary operator. This means that, 
+``` 
+a - b 
+```
+will subtract b from a. As well as negate values such that
+```
+-a  = (-1) * a 
+```
+
+This can only be performed on integers.
+See this in action [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/addition_and_subtraction_examples.ipynb).
diff --git a/docs/bits/operator/L_Plus.md b/docs/bits/operator/L_Plus.md
@@ -0,0 +1,10 @@
+# + (plus)
+This is the addition operator.
+```
+a + b
+```
+will return the sum of ```a```and ```b```.
+
+This operation can only be performed on integers.
+
+See this in action [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/addition_and_subtraction_examples.ipynb).
diff --git a/docs/bits/operator/L_Pow.md b/docs/bits/operator/L_Pow.md
@@ -0,0 +1,18 @@
+# ** (power)
+
+This is the exponent operator.
+
+```
+a ** b 
+```
+
+will return ```a```<sup>```b```</sup> if ```a``` and ```b``` are positive integers.
+
+Savile Row will flag negative exponents (negative values of ```b```) as errors. However, conjure will not flag this as an error.
+
+``` x ** y = x * (x ** (y-1))``` holds if ```x``` is an integer and ```y``` is a positive integer.
+This ensures that ```x ** 0 = 1``` for all ```x```.
+
+For more information see [here](https://conjure.readthedocs.io/en/latest/essence.html#arithmetic-operators).
+
+See this in action [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/powers.ipynb).
diff --git a/docs/bits/operator/L_Times.md b/docs/bits/operator/L_Times.md
@@ -0,0 +1,10 @@
+# * (times)
+This is the multiplication operator.
+
+For example, 
+```
+a * b
+```
+will return ```a``` multiplied by ```b```, if ```a``` and ```b``` are integers.
+
+See this in action [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/multiplication_demonstration.ipynb).
diff --git a/docs/bits/operator/L_abs.md b/docs/bits/operator/L_abs.md
@@ -0,0 +1,14 @@
+# |x| (absolute value)
+
+This is the absolute value operator. It returns the absolute value of ```x```.
+This is calculated using
+```( 2 * toInt( x >= 0) - 1) * x = |x|```
+
+If ```x``` is a positive integer, then [toInt](https://github.com/conjure-cp/conjure/blob/main/docs/bits/function/toInt.md) returns 1, making ```1 * x = |x|```.
+
+If ```x``` is a non-positive integer, then [toInt](https://github.com/conjure-cp/conjure/blob/main/docs/bits/function/toInt.md) returns 0, making ```-1 * x = |x|```.
+
+This holds for integers ```x``` such that ```|x| <= 2```<sup>```62```</sup>```-2```.
+Outside of this range, errors may be flagged up by Savile Row or Minion.
+
+See how this works [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/absoluteValues.ipynb).
diff --git a/docs/bits/operator/post_factorial.md b/docs/bits/operator/post_factorial.md
@@ -0,0 +1,11 @@
+# x! (factorial)
+
+This is the factorial operator.
+
+```x!``` will return the factorial of x - as in the product of all integers from ```1``` to ```x```.
+
+When ``` x <= 0 ```, ```x! = 0```.
+
+It can't be directly used in expressions with decision variables. For more information about this see [here.](https://conjure.readthedocs.io/en/latest/essence.html#arithmetic-operators)
+
+To see how this works see [here](https://github.com/conjure-cp/conjure/blob/main/docs/notebooks/factorial.ipynb).
diff --git a/docs/notebooks/absoluteValues.ipynb b/docs/notebooks/absoluteValues.ipynb
@@ -0,0 +1,213 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "colab_type": "text",
+        "id": "view-in-github"
+      },
+      "source": [
+        "<a href=\"https://colab.research.google.com/github/conjure-cp/conjure/blob/main/docs/notebooks/absoluteValues.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "c8dzxMmmUdOv"
+      },
+      "source": [
+        "## Absolute Value"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 1,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/",
+          "height": 138
+        },
+        "id": "ymW8a8GxPCWV",
+        "outputId": "d7fe26e5-e479-4ac6-fccf-efa39690b5e6"
+      },
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Installing Conjure version v2.5.0 and Conjure Notebook version v0.0.8...\n",
+            "Downloading...\n",
+            "Conjure: The Automated Constraint Modelling Tool\n",
+            "Release version 2.5.0\n",
+            "Repository version 41536c055 (2023-05-18 14:03:02 +0100)\n"
+          ]
+        },
+        {
+          "data": {
+            "application/javascript": "\"use strict\";\n\nCodeMirror.defineMode(\"text/conjure\", function (config) {\n\n    var isOperatorChar = /[+\\-*=<>%^\\/]/;\n\n    var keywords = {\n        \"forall\": true,\n        \"allDifferent\": true,\n        \"allDiff\": true,\n        \"alldifferent_except\": true,\n        \"dim\": true,\n        \"toSet\": true,\n        \"toMSet\": true,\n        \"toRelation\": true,\n        \"maximising\": true,\n        \"minimising\": true,\n        \"forAll\": true,\n        \"exists\": true,\n        \"toInt\": true,\n        \"sum\": true,\n        \"be\": true,\n        \"bijective\": true,\n        \"bool\": true,\n        \"by\": true,\n        \"complete\": true,\n        \"defined\": true,\n        \"domain\": true,\n        \"in\": true,\n        \"or\": true,\n        \"and\": true,\n        \"false\": true,\n        \"find\": true,\n        \"from\": true,\n        \"function\": true,\n        \"given\": true,\n        \"image\": true,\n        \"indexed\": true,\n        \"injective\": true,\n        \"int\": true,\n        \"intersect\": true,\n        \"freq\": true,\n        \"lambda\": true,\n        \"language\": true,\n        \"letting\": true,\n        \"matrix\": true,\n        \"maxNumParts\": true,\n        \"maxOccur\": true,\n        \"maxPartSize\": true,\n        \"maxSize\": true,\n        \"minNumParts\": true,\n        \"minOccur\": true,\n        \"minPartSize\": true,\n        \"minSize\": true,\n        \"mset\": true,\n        \"numParts\": true,\n        \"of\": true,\n        \"partial\": true,\n        \"partition\": true,\n        \"partSize\": true,\n        \"preImage\": true,\n        \"quantifier\": true,\n        \"range\": true,\n        \"regular\": true,\n        \"relation\": true,\n        \"representation\": true,\n        \"set\": true,\n        \"size\": true,\n        \"subset\": true,\n        \"subsetEq\": true,\n        \"such\": true,\n        \"supset\": true,\n        \"supsetEq\": true,\n        \"surjective\": true,\n        \"that\": true,\n        \"together\": true,\n        \"enum\": true,\n        \"total\": true,\n        \"true\": true,\n        \"new\": true,\n        \"type\": true,\n        \"tuple\": true,\n        \"union\": true,\n        \"where\": true,\n        \"branching\": true,\n        \"on\": true\n    };  \n    var punc = \":;,.(){}[]\";\n\n    function tokenBase(stream, state) {\n        var ch = stream.next();\n        if (ch == '\"') {\n            state.tokenize.push(tokenString);\n            return tokenString(stream, state);\n        }\n        if (/[\\d\\.]/.test(ch)) {\n            if (ch == \".\") {\n                stream.match(/^[0-9]+([eE][\\-+]?[0-9]+)?/);\n            } else if (ch == \"0\") {\n                stream.match(/^[xX][0-9a-fA-F]+/) || stream.match(/^0[0-7]+/);\n            } else {\n                stream.match(/^[0-9]*\\.?[0-9]*([eE][\\-+]?[0-9]+)?/);\n            }\n            return \"number\";\n        }\n        if (ch == \"/\") {\n            if (stream.eat(\"*\")) {\n                state.tokenize.push(tokenComment);\n                return tokenComment(stream, state);\n            }\n        }\n        if (ch == \"$\") {\n            stream.skipToEnd();\n            return \"comment\";\n        }\n        if (isOperatorChar.test(ch)) {\n            stream.eatWhile(isOperatorChar);\n            return \"operator\";\n        }\n        if (punc.indexOf(ch) > -1) {\n            return \"punctuation\";\n        }\n        stream.eatWhile(/[\\w\\$_\\xa1-\\uffff]/);\n        var cur = stream.current();\n        \n        if (keywords.propertyIsEnumerable(cur)) {\n            return \"keyword\";\n        }\n        return \"variable\";\n    }\n\n    function tokenComment(stream, state) {\n        var maybeEnd = false, ch;\n        while (ch = stream.next()) {\n            if (ch == \"/\" && maybeEnd) {\n                state.tokenize.pop();\n                break;\n            }\n            maybeEnd = (ch == \"*\");\n        }\n        return \"comment\";\n    }\n\n    function tokenUntilClosingParen() {\n        var depth = 0;\n        return function (stream, state, prev) {\n            var inner = tokenBase(stream, state, prev);\n            console.log(\"untilClosing\", inner, stream.current());\n            if (inner == \"punctuation\") {\n                if (stream.current() == \"(\") {\n                    ++depth;\n                } else if (stream.current() == \")\") {\n                    if (depth == 0) {\n                        stream.backUp(1)\n                        state.tokenize.pop()\n                        return state.tokenize[state.tokenize.length - 1](stream, state)\n                    } else {\n                        --depth;\n                    }\n                }\n            }\n            return inner;\n        }\n    }\n\n    function tokenString(stream, state) {\n        var escaped = false, next, end = false;\n        while ((next = stream.next()) != null) {\n            if (next == '(' && escaped) {\n                state.tokenize.push(tokenUntilClosingParen());\n                return \"string\";\n            }\n            if (next == '\"' && !escaped) { end = true; break; }\n            escaped = !escaped && next == \"\\\\\";\n        }\n        if (end || !escaped)\n            state.tokenize.pop();\n        return \"string\";\n    }\n\n    return {\n        startState: function (basecolumn) {\n            return {\n                tokenize: []\n            };\n        },\n\n        token: function (stream, state) {\n            if (stream.eatSpace()) return null;\n            var style = (state.tokenize[state.tokenize.length - 1] || tokenBase)(stream, state);\n            console.log(\"token\", style);\n            return style;\n        },\n\n        blockCommentStart: \"/*\",\n        blockCommentEnd: \"*/\",\n        lineComment: \"$\"\n    };\n});\n\n\nCodeMirror.defineMIME(\"text/conjure\", \"text/conjure\");\n\nrequire(['notebook/js/codecell'], function (codecell) {\n    codecell.CodeCell.options_default.highlight_modes['magic_text/conjure'] = { 'reg': [/%?%conjure/] };\n    Jupyter.notebook.events.one('kernel_ready.Kernel', function () {\n        Jupyter.notebook.get_cells().map(function (cell) {\n            if (cell.cell_type == 'code') { cell.auto_highlight(); }\n        });\n    });\n});\n\n",
+            "text/plain": [
+              "<IPython.core.display.Javascript object>"
+            ]
+          },
+          "metadata": {},
+          "output_type": "display_data"
+        },
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Conjure extension is loaded.\n",
+            "For usage help run: %conjure_help\n"
+          ]
+        }
+      ],
+      "source": [
+        "!source <(curl -s https://raw.githubusercontent.com/conjure-cp/conjure-notebook/v0.0.8/scripts/install-colab.sh)\n",
+        "%load_ext conjure"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "oaLG9qniVBXy"
+      },
+      "source": [
+        "You can find the absolute value of an integer x by writing |x|."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/",
+          "height": 54
+        },
+        "id": "hZ3N7FSRUn8K",
+        "outputId": "0932d240-fd53-42ae-94d7-0f88575b8d85"
+      },
+      "outputs": [
+        {
+          "data": {
+            "text/markdown": [
+              "```json\n",
+              "{\"conjure_solutions\": [{\"x\": -5, \"y\": 5}, {\"x\": -4, \"y\": 4}, {\"x\": -3, \"y\": 3}, {\"x\": -2, \"y\": 2}, {\"x\": -1, \"y\": 1}, {\"x\": 0, \"y\": 0}, {\"x\": 1, \"y\": 1}, {\"x\": 2, \"y\": 2}, {\"x\": 3, \"y\": 3}, {\"x\": 4, \"y\": 4}, {\"x\": 5, \"y\": 5}]}\n",
+              "```"
+            ],
+            "text/plain": [
+              "<IPython.core.display.Markdown object>"
+            ]
+          },
+          "metadata": {},
+          "output_type": "display_data"
+        }
+      ],
+      "source": [
+        "%%conjure --number-of-solutions=all\n",
+        "find x, y: int (-5..5) such that |x| = y"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "afDKvxbnW9DT"
+      },
+      "source": [
+        "This works while |x| <= 2<sup>62</sup> - 2"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "So this works:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 3,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/",
+          "height": 34
+        },
+        "id": "W5TXkLeYXgyE",
+        "outputId": "bf56da8f-3f31-4187-9d67-8374dc64c02f"
+      },
+      "outputs": [
+        {
+          "data": {
+            "text/markdown": [
+              "```json\n",
+              "{\"x\": 4611686018427387902, \"y\": 4611686018427387902}\n",
+              "```"
+            ],
+            "text/plain": [
+              "<IPython.core.display.Markdown object>"
+            ]
+          },
+          "metadata": {},
+          "output_type": "display_data"
+        }
+      ],
+      "source": [
+        "%%conjure --number-of-solutions=all --solver=minion\n",
+        "\n",
+        "find x, y: int(2**62-2) such that |x| = y"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "But this doesn't:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 4,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "7qxV01yPYV4c",
+        "outputId": "849237f5-45c2-49cb-d44f-49d0ad33ce7c"
+      },
+      "outputs": [
+        {
+          "name": "stderr",
+          "output_type": "stream",
+          "text": [
+            "Exception: Error:\n",
+            "    Savile Row stdout: \n",
+            "    Savile Row stderr: ERROR: Number exceeds 64-bit integer range: 18446744073709551616\n",
+            "\n",
+            "    Savile Row exit-code: 1\n",
+            "\n"
+          ]
+        }
+      ],
+      "source": [
+        "%%conjure --number-of-solutions=all\n",
+        "\n",
+        "find x, y: int(2**64) such that |x| = y"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "authorship_tag": "ABX9TyNS0NGUrTvuqDF07X0yUo5V",
+      "include_colab_link": true,
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}