Built site for gh-pages

.nojekyll

@@ -1 +1 @@
-11886b27
+7722dd69

book/developer_notes.html

@@ -307,7 +307,9 @@ <h2 id="toc-title">Table of contents</h2>
 
   <ul>
   <li><a href="#api-specification" id="toc-api-specification" class="nav-link active" data-scroll-target="#api-specification"><span class="header-section-number">5.1</span> API specification</a></li>
-  <li><a href="#azure-functions" id="toc-azure-functions" class="nav-link" data-scroll-target="#azure-functions"><span class="header-section-number">5.2</span> Azure Functions</a></li>
+  <li><a href="#fastapi-local" id="toc-fastapi-local" class="nav-link" data-scroll-target="#fastapi-local"><span class="header-section-number">5.2</span> FastAPI, local</a></li>
+  <li><a href="#fastapi-over-docker" id="toc-fastapi-over-docker" class="nav-link" data-scroll-target="#fastapi-over-docker"><span class="header-section-number">5.3</span> FastAPI, over Docker</a></li>
+  <li><a href="#azure-functions" id="toc-azure-functions" class="nav-link" data-scroll-target="#azure-functions"><span class="header-section-number">5.4</span> Azure Functions</a></li>
   </ul>
 </nav>
     </div>
@@ -359,9 +361,29 @@ <h2 data-number="5.1" class="anchored" data-anchor-id="api-specification"><span
 <span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a>  <span class="fu">},</span></span>
 <span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a>  <span class="er">...</span></span>
 <span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<p>The function <code>demoland_engine.api.scenario_calc()</code> obeys this schema, and both the FastAPI and the Azure Functions apps simply wrap this function.</p>
 </section>
-<section id="azure-functions" class="level2" data-number="5.2">
-<h2 data-number="5.2" class="anchored" data-anchor-id="azure-functions"><span class="header-section-number">5.2</span> Azure Functions</h2>
+<section id="fastapi-local" class="level2" data-number="5.2">
+<h2 data-number="5.2" class="anchored" data-anchor-id="fastapi-local"><span class="header-section-number">5.2</span> FastAPI, local</h2>
+<p>One way to run the API is to run it locally or over Docker. To do this, there is a FastAPI app located at <code>api/main.py</code>. First make sure you have the optional dependencies for the FastAPI app installed. Go to the top-level directory of the repo and run</p>
+<pre><code>python -m pip install .[api]</code></pre>
+<p>The <code>[api]</code> instructs <code>pip</code> to install the optional dependencies, which can be seen in <code>pyproject.toml</code>.</p>
+<p>Then, again from the top-level directory, run:</p>
+<pre><code>uvicorn main:app --app-dir api --port 5178</code></pre>
+<p>You should now be able to test the API using:</p>
+<pre><code>curl http://localhost:5178/api/scenario -X POST -d "{\"scenario_json\": {}, \"model_identifier\": \"tyne_and_wear\"}" -v -H 'Content-Type: application/json'</code></pre>
+<p>(Note that the <code>Content-Type</code> header is mandatory, otherwise FastAPI doesn’t accept the input.)</p>
+</section>
+<section id="fastapi-over-docker" class="level2" data-number="5.3">
+<h2 data-number="5.3" class="anchored" data-anchor-id="fastapi-over-docker"><span class="header-section-number">5.3</span> FastAPI, over Docker</h2>
+<p><code>Dockerfile.api</code> provides the specification for running the FastAPI app over Docker. Simply do:</p>
+<pre><code>docker build . -f Dockerfile.api -t demoland-api
+docker run -it demoland-api</code></pre>
+<p>The Dockerfile is configured to expose the API on port 80 (which is the default port for HTTP), so you can omit the port number when testing:</p>
+<pre><code>curl http://localhost/api/scenario -X POST -d "{\"scenario_json\": {}, \"model_identifier\": \"tyne_and_wear\"}" -v -H 'Content-Type: application/json'</code></pre>
+</section>
+<section id="azure-functions" class="level2" data-number="5.4">
+<h2 data-number="5.4" class="anchored" data-anchor-id="azure-functions"><span class="header-section-number">5.4</span> Azure Functions</h2>
 <p>The code required to deploy this can be found on the <a href="https://github.com/Urban-Analytics-Technology-Platform/demoland-engine/tree/azure-functions"><code>azure-functions</code> branch of the engine repository</a>, specifically the <code>function_app.py</code> file.</p>
 <p>To deploy a new version of the Azure function, make sure you are a member of the <em>“Land Use Indicator”</em> Azure subscription (the subscription ID is <code>86307bb0-6d16-4077-b1f7-939370d5289a</code>). If you are not, get Dani to add you.</p>
 <p>Then, follow these instructions:</p>

index.html

@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Anna Zanchetta, Martin Fleischmann, Dani Arribas-Bel; The Alan Turing Institute">
-<meta name="dcterms.date" content="2024-01-17">
+<meta name="dcterms.date" content="2024-01-18">
 
 <title>Land Use Demonstrator</title>
 <style>
@@ -300,7 +300,7 @@ <h1 class="title">Land Use Demonstrator</h1>
     <div>
     <div class="quarto-title-meta-heading">Published</div>
     <div class="quarto-title-meta-contents">
-      <p class="date">January 17, 2024</p>
+      <p class="date">January 18, 2024</p>
     </div>
   </div>
 

search.json

@@ -165,14 +165,28 @@
     "href": "book/developer_notes.html#api-specification",
     "title": "5  Developer notes",
     "section": "5.1 API specification",
-    "text": "5.1 API specification\nThe calculation of indicators for custom scenarios in the web app relies on an API. Right now, the web app uses an API which is hosted as an Azure Function.\nIn particular, the function must accept a POST body that looks like this. Only output areas which are changed relative to the baseline need to be included in the inner JSON object:\n{\n  \"model_identifier\": string,\n  \"scenario_json\": {\n    output_area_name: {\n      \"signature_type\": int | null,\n      \"job\": float | null,\n      \"use\": float | null,\n      \"greenspace\": float | null\n    },\n    ...\n  }\n}\nUpon success, this must return a JSON response with the following format (all output areas must be included):\n{\n  output_area_name: {\n    \"air_quality\": float,\n    \"house_price\": float,\n    \"job_accessibility\": float,\n    \"greenspace_accessibility\": float,\n    \"signature_type\": int\n  },\n  ...\n}"
+    "text": "5.1 API specification\nThe calculation of indicators for custom scenarios in the web app relies on an API. Right now, the web app uses an API which is hosted as an Azure Function.\nIn particular, the function must accept a POST body that looks like this. Only output areas which are changed relative to the baseline need to be included in the inner JSON object:\n{\n  \"model_identifier\": string,\n  \"scenario_json\": {\n    output_area_name: {\n      \"signature_type\": int | null,\n      \"job\": float | null,\n      \"use\": float | null,\n      \"greenspace\": float | null\n    },\n    ...\n  }\n}\nUpon success, this must return a JSON response with the following format (all output areas must be included):\n{\n  output_area_name: {\n    \"air_quality\": float,\n    \"house_price\": float,\n    \"job_accessibility\": float,\n    \"greenspace_accessibility\": float,\n    \"signature_type\": int\n  },\n  ...\n}\nThe function demoland_engine.api.scenario_calc() obeys this schema, and both the FastAPI and the Azure Functions apps simply wrap this function."
+  },
+  {
+    "objectID": "book/developer_notes.html#fastapi-local",
+    "href": "book/developer_notes.html#fastapi-local",
+    "title": "5  Developer notes",
+    "section": "5.2 FastAPI, local",
+    "text": "5.2 FastAPI, local\nOne way to run the API is to run it locally or over Docker. To do this, there is a FastAPI app located at api/main.py. First make sure you have the optional dependencies for the FastAPI app installed. Go to the top-level directory of the repo and run\npython -m pip install .[api]\nThe [api] instructs pip to install the optional dependencies, which can be seen in pyproject.toml.\nThen, again from the top-level directory, run:\nuvicorn main:app --app-dir api --port 5178\nYou should now be able to test the API using:\ncurl http://localhost:5178/api/scenario -X POST -d \"{\\\"scenario_json\\\": {}, \\\"model_identifier\\\": \\\"tyne_and_wear\\\"}\" -v -H 'Content-Type: application/json'\n(Note that the Content-Type header is mandatory, otherwise FastAPI doesn’t accept the input.)"
+  },
+  {
+    "objectID": "book/developer_notes.html#fastapi-over-docker",
+    "href": "book/developer_notes.html#fastapi-over-docker",
+    "title": "5  Developer notes",
+    "section": "5.3 FastAPI, over Docker",
+    "text": "5.3 FastAPI, over Docker\nDockerfile.api provides the specification for running the FastAPI app over Docker. Simply do:\ndocker build . -f Dockerfile.api -t demoland-api\ndocker run -it demoland-api\nThe Dockerfile is configured to expose the API on port 80 (which is the default port for HTTP), so you can omit the port number when testing:\ncurl http://localhost/api/scenario -X POST -d \"{\\\"scenario_json\\\": {}, \\\"model_identifier\\\": \\\"tyne_and_wear\\\"}\" -v -H 'Content-Type: application/json'"
   },
   {
     "objectID": "book/developer_notes.html#azure-functions",
     "href": "book/developer_notes.html#azure-functions",
     "title": "5  Developer notes",
-    "section": "5.2 Azure Functions",
-    "text": "5.2 Azure Functions\nThe code required to deploy this can be found on the azure-functions branch of the engine repository, specifically the function_app.py file.\nTo deploy a new version of the Azure function, make sure you are a member of the “Land Use Indicator” Azure subscription (the subscription ID is 86307bb0-6d16-4077-b1f7-939370d5289a). If you are not, get Dani to add you.\nThen, follow these instructions:\n\nLog in to Azure. This will open a browser window where you can log in with your Microsoft account.\n az login\nSet your active subscription to the one above:\naz account set -s 86307bb0-6d16-4077-b1f7-939370d5289a\nInstall the Azure Functions Core Tools. The following Homebrew command works on macOS; for other operating systems, refer to the Azure docs\nbrew tap azure/functions\nbrew install azure-functions-core-tools@4\nClone the demoland-engine repository (if you don’t already have it), and cd to the top level of the demoland-engine repository.\nTo test the function locally, run:\nfunc start\nYou should then be able to access the API at http://localhost:7071/api/scenario. For example, you can test it using the following command, which asks it to calculate the baseline indicators (an empty scenario means no changes relative to the baseline):\ncurl http://localhost:7071/api/scenario -X POST -d \"{\\\"scenario_json\\\": {}, \\\"model_identifier\\\": \\\"tyne_and_wear\\\"}\" -v\nTo deploy it to Azure, run the following, which will take a few minutes:\nfunc azure functionapp publish demolandapi\nTest it with:\ncurl https://demolandapi.azurewebsites.net/api/scenario -X POST -d \"{\\\"scenario_json\\\": {}, \\\"model_identifier\\\": \\\"tyne_and_wear\\\"}\" -v"
+    "section": "5.4 Azure Functions",
+    "text": "5.4 Azure Functions\nThe code required to deploy this can be found on the azure-functions branch of the engine repository, specifically the function_app.py file.\nTo deploy a new version of the Azure function, make sure you are a member of the “Land Use Indicator” Azure subscription (the subscription ID is 86307bb0-6d16-4077-b1f7-939370d5289a). If you are not, get Dani to add you.\nThen, follow these instructions:\n\nLog in to Azure. This will open a browser window where you can log in with your Microsoft account.\n az login\nSet your active subscription to the one above:\naz account set -s 86307bb0-6d16-4077-b1f7-939370d5289a\nInstall the Azure Functions Core Tools. The following Homebrew command works on macOS; for other operating systems, refer to the Azure docs\nbrew tap azure/functions\nbrew install azure-functions-core-tools@4\nClone the demoland-engine repository (if you don’t already have it), and cd to the top level of the demoland-engine repository.\nTo test the function locally, run:\nfunc start\nYou should then be able to access the API at http://localhost:7071/api/scenario. For example, you can test it using the following command, which asks it to calculate the baseline indicators (an empty scenario means no changes relative to the baseline):\ncurl http://localhost:7071/api/scenario -X POST -d \"{\\\"scenario_json\\\": {}, \\\"model_identifier\\\": \\\"tyne_and_wear\\\"}\" -v\nTo deploy it to Azure, run the following, which will take a few minutes:\nfunc azure functionapp publish demolandapi\nTest it with:\ncurl https://demolandapi.azurewebsites.net/api/scenario -X POST -d \"{\\\"scenario_json\\\": {}, \\\"model_identifier\\\": \\\"tyne_and_wear\\\"}\" -v"
   },
   {
     "objectID": "code/01_baseline/01_accessibility.html#variables-definition-and-data-import",