Add docs for using FLORIS as a library

NREL · Nov 27, 2024 · a4df7e7 · a4df7e7
1 parent 8a2eb4e
commit a4df7e7
Showing 1 changed file with 79 additions and 2 deletions.
diff --git a/docs/advanced_concepts.ipynb b/docs/advanced_concepts.ipynb
@@ -95,16 +95,93 @@
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## FLORIS as a library\n",
+    "\n",
+    "FLORIS is commonly used as a library in other software packages.\n",
+    "In cases where the calling-code will create inputs for FLORIS rather than require them from the\n",
+    "user, it can be helpful to initialize the FLORIS model with default inputs and then\n",
+    "change them in code.\n",
+    "In this case, the following workflow is recommended."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [],
-   "source": []
+   "source": [
+    "import floris\n",
+    "\n",
+    "# Initialize FLORIS with defaults\n",
+    "fmodel = floris.FlorisModel(\"defaults\")\n",
+    "\n",
+    "# Within the calling-code's setup step, update FLORIS as needed\n",
+    "fmodel.set(\n",
+    "    wind_directions=[i for i in range(10)],\n",
+    "    wind_speeds=[5 + i for i in range(10)],\n",
+    "    turbulence_intensities=[i for i in range(10)],\n",
+    "    # turbine_library_path=\"path/to/turbine_library\",   # Shown here for reference\n",
+    "    # turbine_type=[\"my_turbine\"]\n",
+    ")\n",
+    "\n",
+    "# Within the calling code's computation, run FLORIS\n",
+    "fmodel.run()"
+   ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
+   "source": [
+    "Alternatively, the calling-code can import the FLORIS default inputs as a Python dictionary\n",
+    "and modify them directly before initializing the FLORIS model.\n",
+    "This is especially helpful when the calling-code will modify a parameter that isn't\n",
+    "supported by the `FlorisModel.set(...)` command.\n",
+    "In particular, the wake model parameters are not directly accessible, so these can be updated\n",
+    "externally, as shown below.\n",
+    "Note that the `FlorisModel.get_defaults()` function returns a deep copy of the default inputs,\n",
+    "so these can be modified directly without side effects."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import floris\n",
+    "\n",
+    "# Retrieve the default parameters\n",
+    "fdefaults = floris.FlorisModel.get_defaults()\n",
+    "\n",
+    "# Update wake model parameters\n",
+    "fdefaults[\"wake\"][\"model_strings\"][\"velocity_model\"] = \"jensen\"\n",
+    "fdefaults[\"wake\"][\"wake_velocity_parameters\"][\"jensen\"][\"we\"] = 0.05\n",
+    "\n",
+    "# Initialize FLORIS with modified parameters\n",
+    "fmodel = floris.FlorisModel(configuration=fdefaults)\n",
+    "\n",
+    "# Within the calling-code's setup step, update FLORIS as needed\n",
+    "fmodel.set(\n",
+    "    wind_directions=[i for i in range(10)],\n",
+    "    wind_speeds=[5 + i for i in range(10)],\n",
+    "    turbulence_intensities=[i for i in range(10)],\n",
+    "    # turbine_library_path=\"path/to/turbine_library\",   # Shown here for reference\n",
+    "    # turbine_type=[\"my_turbine\"]\n",
+    ")\n",
+    "\n",
+    "# Within the calling code's computation, run FLORIS\n",
+    "fmodel.run()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": []
   }
  ],