{ "cells": [ { "cell_type": "code", "execution_count": 1, "id": "0097e51b", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:08.453004Z", "iopub.status.busy": "2026-10-02T14:42:08.452823Z", "iopub.status.idle": "2026-10-02T14:42:08.457191Z", "shell.execute_reply": "2026-10-02T14:42:08.456521Z" }, "papermill": { "duration": 0.008377, "end_time": "2026-10-02T14:42:08.457996+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.449619+00:00", "status": "completed" }, "tags": [ "remove-input", "active-ipynb", "remove-output" ] }, "outputs": [], "source": [ "try:\n", " from openmdao.utils.notebook_utils import notebook_mode # noqa: F401\n", "except ImportError:\n", " !python -m pip install openmdao[notebooks]" ] }, { "attachments": {}, "cell_type": "markdown", "id": "16eca94d", "metadata": { "papermill": { "duration": 0.001617, "end_time": "2026-10-02T14:42:08.461356+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.459739+00:00", "status": "completed" }, "tags": [] }, "source": [ "# Function Metadata API\n", "\n", "Using [ExplicitFuncComp](components/explicit_func_comp.ipynb), you can turn a python function \n", "into a fully functioning OpenMDAO component. However, in order to do that it's sometimes necessary\n", "to attach additional metadata to the function so that OpenMDAO can be informed of things like\n", "variable units and shapes, and partial derivative information. Metadata can be\n", "attached to a function using the function metadata API. It works by wrapping the function in a \n", "callable object that can store the metadata appropriately.\n", "\n", "## Function wrapping\n", "\n", "We wrap a function using the `omf.wrap` function, for example:\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "efc0d25e", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:08.464958Z", "iopub.status.busy": "2026-10-02T14:42:08.464795Z", "iopub.status.idle": "2026-10-02T14:42:08.876146Z", "shell.execute_reply": "2026-10-02T14:42:08.875415Z" }, "papermill": { "duration": 0.414041, "end_time": "2026-10-02T14:42:08.876883+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.462842+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "import openmdao.func_api as omf\n", "\n", "def func(a):\n", " x = a * 2.\n", " return x\n", "\n", "f = omf.wrap(func) " ] }, { "attachments": {}, "cell_type": "markdown", "id": "a24d1444", "metadata": { "papermill": { "duration": 0.00151, "end_time": "2026-10-02T14:42:08.880190+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.878680+00:00", "status": "completed" }, "tags": [] }, "source": [ "`omf.wrap` returns an instance of the `OMWrappedFunc` class that can store various metadata needed by\n", "OpenMDAO. All of the metadata setting functions called on that instance return the instance itself\n", "so they can be stacked together. For example:" ] }, { "cell_type": "code", "execution_count": 3, "id": "bcf861a0", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:08.884102Z", "iopub.status.busy": "2026-10-02T14:42:08.883812Z", "iopub.status.idle": "2026-10-02T14:42:08.886799Z", "shell.execute_reply": "2026-10-02T14:42:08.886130Z" }, "papermill": { "duration": 0.005789, "end_time": "2026-10-02T14:42:08.887423+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.881634+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "f = omf.wrap(func).add_input('a', shape=5).add_output('x', shape=5, units='m')" ] }, { "attachments": {}, "cell_type": "markdown", "id": "8feee09d", "metadata": { "papermill": { "duration": 0.001357, "end_time": "2026-10-02T14:42:08.890230+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.888873+00:00", "status": "completed" }, "tags": [] }, "source": [ "Also, if you need to make many calls to set metadata on the wrapped function, you can stack the calls\n", "vertically, but this will only work if you wrap the entire righ-hand-side expression in parentheses so\n", "that python will treat it all as a single expression. For example:" ] }, { "cell_type": "code", "execution_count": 4, "id": "fd49442c", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:08.984159Z", "iopub.status.busy": "2026-10-02T14:42:08.983959Z", "iopub.status.idle": "2026-10-02T14:42:08.987344Z", "shell.execute_reply": "2026-10-02T14:42:08.986649Z" }, "papermill": { "duration": 0.006064, "end_time": "2026-10-02T14:42:08.987818+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.981754+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "f = (omf.wrap(func)\n", " .defaults(units='m')\n", " .add_input('a', shape=5)\n", " .add_output('x', shape=5))" ] }, { "attachments": {}, "cell_type": "markdown", "id": "75982c86", "metadata": { "papermill": { "duration": 0.003266, "end_time": "2026-10-02T14:42:08.993175+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.989909+00:00", "status": "completed" }, "tags": [] }, "source": [ "If stacking isn't desired, the methods can just be called in the usual way, for example:" ] }, { "cell_type": "code", "execution_count": 5, "id": "d23c2094", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.000400Z", "iopub.status.busy": "2026-10-02T14:42:09.000233Z", "iopub.status.idle": "2026-10-02T14:42:09.005887Z", "shell.execute_reply": "2026-10-02T14:42:09.004416Z" }, "papermill": { "duration": 0.008918, "end_time": "2026-10-02T14:42:09.006451+00:00", "exception": false, "start_time": "2026-10-02T14:42:08.997533+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "f = omf.wrap(func)\n", "f.defaults(units='m')\n", "f.add_input('a', shape=5)\n", "f.add_output('x', shape=5)" ] }, { "attachments": {}, "cell_type": "markdown", "id": "d640e91f", "metadata": { "papermill": { "duration": 0.002482, "end_time": "2026-10-02T14:42:09.070628+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.068146+00:00", "status": "completed" }, "tags": [] }, "source": [ "## Variable metadata\n", "\n", "### Setting the metadata for a single variable\n", "\n", "OpenMDAO needs to know a variable's shape, initial value, and optionally other things like units. \n", "This information can be specified using the `add_input` and `add_output` methods. For example:" ] }, { "cell_type": "code", "execution_count": 6, "id": "ad0ad3f2", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.076465Z", "iopub.status.busy": "2026-10-02T14:42:09.076233Z", "iopub.status.idle": "2026-10-02T14:42:09.080221Z", "shell.execute_reply": "2026-10-02T14:42:09.079493Z" }, "papermill": { "duration": 0.007724, "end_time": "2026-10-02T14:42:09.080811+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.073087+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "def func(x):\n", " y = x.dot(np.random.random(2))\n", " return y\n", "\n", "f = (omf.wrap(func)\n", " .add_input('x', shape=(2,2))\n", " .add_output('y', shape=2))" ] }, { "attachments": {}, "cell_type": "markdown", "id": "1a7d969c", "metadata": { "papermill": { "duration": 0.001705, "end_time": "2026-10-02T14:42:09.084318+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.082613+00:00", "status": "completed" }, "tags": [] }, "source": [ "### Setting metadata for option variables\n", "\n", "A function may have additional non-float or non-float ndarray arguments that, at least in the\n", "OpenMDAO context, will be treated as component options that don't change during a given model\n", "execution. These can be specified using the `declare_option` method. For example:" ] }, { "cell_type": "code", "execution_count": 7, "id": "b8a77486", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.089263Z", "iopub.status.busy": "2026-10-02T14:42:09.089065Z", "iopub.status.idle": "2026-10-02T14:42:09.093503Z", "shell.execute_reply": "2026-10-02T14:42:09.092540Z" }, "papermill": { "duration": 0.007963, "end_time": "2026-10-02T14:42:09.094128+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.086165+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "def func(x, opt):\n", " if opt == 1:\n", " y = x.dot(np.random.random(2))\n", " elif opt == 2:\n", " y = x[:, 1] * 2.\n", " elif opt == 3:\n", " y = x[1, :] * 3.\n", " return y\n", "\n", "f = (omf.wrap(func)\n", " .add_input('x', shape=(2,2))\n", " .declare_option('opt', values=[1, 2, 3])\n", " .add_output('y', shape=2))" ] }, { "attachments": {}, "cell_type": "markdown", "id": "ac65b37e", "metadata": { "papermill": { "duration": 0.002048, "end_time": "2026-10-02T14:42:09.098298+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.096250+00:00", "status": "completed" }, "tags": [] }, "source": [ "The arguments that are passable to `declare_option` are the same as those that are allowed when\n", "declaring option variables in an OpenMDAO component using the [OptionsDictionary](../../_srcdocs/packages/utils/options_dictionary) `declare` method.\n", "\n", "### Setting metadata for multiple variables\n", "\n", "Using the `add_inputs` and `add_outputs` methods you can specify metadata for multiple variables\n", "in the same call. For example:" ] }, { "cell_type": "code", "execution_count": 8, "id": "ecc8f283", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.123480Z", "iopub.status.busy": "2026-10-02T14:42:09.123338Z", "iopub.status.idle": "2026-10-02T14:42:09.126091Z", "shell.execute_reply": "2026-10-02T14:42:09.125467Z" }, "papermill": { "duration": 0.006426, "end_time": "2026-10-02T14:42:09.126786+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.120360+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "def func(a, b):\n", " return a.dot(b), a[:,0] * b * b\n", "\n", "f = (omf.wrap(func)\n", " .add_inputs(a={'shape': (2,2), 'units': 'm'}, b={'shape': 2, 'units': 'm'})\n", " .add_outputs(x={'shape': 2, 'units': 'm**2'}, y={'shape': 2, 'units': 'm**3'}))" ] }, { "attachments": {}, "cell_type": "markdown", "id": "c13ffed3", "metadata": { "papermill": { "duration": 0.002061, "end_time": "2026-10-02T14:42:09.130845+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.128784+00:00", "status": "completed" }, "tags": [] }, "source": [ "### Getting the metadata\n", "\n", "Variable metadata is retrieved from the wrapped function by calling the \n", "`get_input_meta` and `get_output_meta` methods. Each function returns an iterator over (name, \n", "metadata_dict) tuples, one for each input or output variable respectively. For example, the \n", "following code snippet will print the name and shape of each output variable." ] }, { "cell_type": "code", "execution_count": 9, "id": "f010da2a", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.135399Z", "iopub.status.busy": "2026-10-02T14:42:09.135233Z", "iopub.status.idle": "2026-10-02T14:42:09.139004Z", "shell.execute_reply": "2026-10-02T14:42:09.138347Z" }, "papermill": { "duration": 0.006841, "end_time": "2026-10-02T14:42:09.139447+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.132606+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "x (2,)\n", "y (2,)\n" ] } ], "source": [ "for name, meta in f.get_output_meta():\n", " print(name, meta['shape'])" ] }, { "attachments": {}, "cell_type": "markdown", "id": "54c8c37e", "metadata": { "papermill": { "duration": 0.001469, "end_time": "2026-10-02T14:42:09.142466+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.140997+00:00", "status": "completed" }, "tags": [] }, "source": [ "## Setting function default metadata\n", "\n", "Some metadata will be the same for all, or at least most of the variables within a given function,\n", "so we want to be able to specify those defaults easily without too much boilerplate. That's the\n", "purpose of the `defaults` method. For example:" ] }, { "cell_type": "code", "execution_count": 10, "id": "e1af8d4f", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.146321Z", "iopub.status.busy": "2026-10-02T14:42:09.146147Z", "iopub.status.idle": "2026-10-02T14:42:09.149310Z", "shell.execute_reply": "2026-10-02T14:42:09.148669Z" }, "papermill": { "duration": 0.005773, "end_time": "2026-10-02T14:42:09.149778+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.144005+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "def func(a, b, c):\n", " d = a * b * c\n", " return d\n", "\n", "f = omf.wrap(func).defaults(shape=4, units='m')" ] }, { "attachments": {}, "cell_type": "markdown", "id": "19cd5065", "metadata": { "papermill": { "duration": 0.001489, "end_time": "2026-10-02T14:42:09.152799+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.151310+00:00", "status": "completed" }, "tags": [] }, "source": [ "Any metadata that is specific to a particular variable will override any defaults specified in\n", "`defaults`. For example:" ] }, { "cell_type": "code", "execution_count": 11, "id": "94744696", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.156463Z", "iopub.status.busy": "2026-10-02T14:42:09.156300Z", "iopub.status.idle": "2026-10-02T14:42:09.159388Z", "shell.execute_reply": "2026-10-02T14:42:09.158453Z" }, "papermill": { "duration": 0.005685, "end_time": "2026-10-02T14:42:09.159958+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.154273+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "import numpy as np\n", "\n", "def func(a, b, c=np.ones(3)): # shape of c is 3 which overrides the `defaults` shape of 4\n", " d = a * b\n", " e = c * 1.5\n", " return d, e\n", "\n", "f = omf.wrap(func).defaults(shape=4, units='m')" ] }, { "attachments": {}, "cell_type": "markdown", "id": "7bb7dff8", "metadata": { "papermill": { "duration": 0.001914, "end_time": "2026-10-02T14:42:09.164248+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.162334+00:00", "status": "completed" }, "tags": [] }, "source": [ "\n", "### Assumed default values\n", "\n", "In order to stay consistent with OpenMDAO's default value policy, we assume the same default\n", "behavior for functions, so if no shape or default value is supplied for a function variable, we\n", "assume that is has the value 1.0. If the `shape` is provided and either the default value is\n", "not provided or is provided as a scalar value, then the assumed default value will be\n", "`np.ones(shape) * scalar_value`, where `scalar_value` is 1.0 if not specified.\n", "If `shape` is provided along with a non-scalar default value that has a different shape, then\n", "an exception will be raised.\n", "\n", "\n", "## Variable names\n", "\n", "### Setting variable names\n", "\n", "We don't need to set input names because the function can always be inspected for those, but\n", "we do need to associate output names with function return values. Those return values, if they are \n", "simple variables, for example, `return x, y`, will give us the output variable names we need. \n", "But in those cases where the function returns expressions rather than simple variables, we need \n", "another way to specify what the names of those output variables should be. The `output_names` \n", "method provides a concise way to do this, for example:" ] }, { "cell_type": "code", "execution_count": 12, "id": "a8e2c2db", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.169053Z", "iopub.status.busy": "2026-10-02T14:42:09.168924Z", "iopub.status.idle": "2026-10-02T14:42:09.171495Z", "shell.execute_reply": "2026-10-02T14:42:09.171046Z" }, "papermill": { "duration": 0.005741, "end_time": "2026-10-02T14:42:09.172060+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.166319+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "def func(a, b, c):\n", " return a * b * c, a * b -c # two return values that don't have simple names\n", "\n", "f = omf.wrap(func).output_names('d', 'e') # name of return values are 'd' and 'e'" ] }, { "attachments": {}, "cell_type": "markdown", "id": "94b4f3cd", "metadata": { "papermill": { "duration": 0.002031, "end_time": "2026-10-02T14:42:09.176075+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.174044+00:00", "status": "completed" }, "tags": [] }, "source": [ "If we have metadata we need to supply for the outputs, we could instead just use the\n", "`add_outputs` method mentioned earlier, for example:" ] }, { "cell_type": "code", "execution_count": 13, "id": "dfbf1c03", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.181123Z", "iopub.status.busy": "2026-10-02T14:42:09.180942Z", "iopub.status.idle": "2026-10-02T14:42:09.183828Z", "shell.execute_reply": "2026-10-02T14:42:09.183048Z" }, "papermill": { "duration": 0.006164, "end_time": "2026-10-02T14:42:09.184329+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.178165+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "def func(a, b, c):\n", " return a * b * c, a * b -c # two return values that don't have simple names\n", "\n", "# names of return values are 'd' and 'e'. \n", "f = omf.wrap(func).add_outputs(d={'units': 'm'}, e={'units': 'ft'})" ] }, { "attachments": {}, "cell_type": "markdown", "id": "ba585060", "metadata": { "papermill": { "duration": 0.002308, "end_time": "2026-10-02T14:42:09.250938+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.248630+00:00", "status": "completed" }, "tags": [] }, "source": [ "As mentioned above, if the function's return values are simple variable names, we don't need to\n", "specify the output names because we can determine them by inspecting the function, e.g., " ] }, { "cell_type": "code", "execution_count": 14, "id": "038b3146", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.256414Z", "iopub.status.busy": "2026-10-02T14:42:09.256232Z", "iopub.status.idle": "2026-10-02T14:42:09.258836Z", "shell.execute_reply": "2026-10-02T14:42:09.258255Z" }, "papermill": { "duration": 0.006109, "end_time": "2026-10-02T14:42:09.259360+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.253251+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "def func(a, b, c):\n", " d = a * b * c\n", " e = a * b -c\n", " return d, e # we know from inspection that the output names are 'd' and 'e'" ] }, { "attachments": {}, "cell_type": "markdown", "id": "07c48a3f", "metadata": { "papermill": { "duration": 0.005691, "end_time": "2026-10-02T14:42:09.266811+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.261120+00:00", "status": "completed" }, "tags": [] }, "source": [ "Note that in the function above, we didn't have to wrap it at all. This is possible because we can \n", "inspect the source code to determine the output names and we assume the default value of all inputs\n", "and outputs is 1.0. If any inputs or outputs of a function have any non-default metadata, e.g.,\n", "val, units, shape, etc., then that function would have to be wrapped and those metadata values\n", "would have to be specified. Also, if we plan to compute derivatives for the function then we would\n", "need to specify which partials are nonzero using the `declare_partials` method.\n", "\n", "If one or more output names are not specified and cannot be determined by inspection, then they \n", "must be specified using `add_output` calls. The number of `add_output` calls corresponding to unnamed\n", "return values must match the total number of unnamed return values, and they will be matched to those \n", "return values in the order that they are called. Any call to `add_output` with an output name that \n", "corresponds to one already specified can occur in any order. In the example below, there\n", "are two return values and neither output name is specified, so two calls to `add_output` are needed." ] }, { "cell_type": "code", "execution_count": 15, "id": "ea29f698", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.378689Z", "iopub.status.busy": "2026-10-02T14:42:09.378545Z", "iopub.status.idle": "2026-10-02T14:42:09.381481Z", "shell.execute_reply": "2026-10-02T14:42:09.380832Z" }, "papermill": { "duration": 0.007068, "end_time": "2026-10-02T14:42:09.382191+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.375123+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "def func(x):\n", " return x.dot(np.random.random(2)), x*1.5 # 2 return values and we can't infer the names\n", "f = (omf.wrap(func)\n", " .add_input('x', shape=(2,2))\n", " .add_output('y', shape=2) # 'y' is the name of the first return value\n", " .add_output('z', shape=(2,2))) # 'z' is the name of the second return value" ] }, { "attachments": {}, "cell_type": "markdown", "id": "6b734732", "metadata": { "papermill": { "duration": 0.002196, "end_time": "2026-10-02T14:42:09.386708+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.384512+00:00", "status": "completed" }, "tags": [] }, "source": [ "In the example above, the output names would be assumed to be `['y', 'z']`.\n", "\n", "### Getting variable names\n", "\n", "Lists of input names and output names can be retrieved by calling `get_input_names` and \n", "`get_output_names` respectively, e.g., " ] }, { "cell_type": "code", "execution_count": 16, "id": "d95cf61b", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.392581Z", "iopub.status.busy": "2026-10-02T14:42:09.392413Z", "iopub.status.idle": "2026-10-02T14:42:09.395516Z", "shell.execute_reply": "2026-10-02T14:42:09.394899Z" }, "papermill": { "duration": 0.007077, "end_time": "2026-10-02T14:42:09.396077+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.389000+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "input names = ['x']\n", "output names = ['y', 'z']\n" ] } ], "source": [ "print('input names =', list(f.get_input_names()))\n", "print('output names = ', list(f.get_output_names()))" ] }, { "attachments": {}, "cell_type": "markdown", "id": "d3707b32", "metadata": { "papermill": { "duration": 0.001869, "end_time": "2026-10-02T14:42:09.400171+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.398302+00:00", "status": "completed" }, "tags": [] }, "source": [ "## Partial derivatives\n", "\n", "### Setting partial derivative information\n", "\n", "Metadata that will help OpenMDAO to compute partial derivatives\n", "for the function can be defined using the `declare_partials` and `declare_coloring` methods.\n", "For example:" ] }, { "cell_type": "code", "execution_count": 17, "id": "de230609", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.405007Z", "iopub.status.busy": "2026-10-02T14:42:09.404854Z", "iopub.status.idle": "2026-10-02T14:42:09.407796Z", "shell.execute_reply": "2026-10-02T14:42:09.407119Z" }, "papermill": { "duration": 0.006075, "end_time": "2026-10-02T14:42:09.408187+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.402112+00:00", "status": "completed" }, "tags": [] }, "outputs": [], "source": [ "import numpy as np\n", "\n", "def func(x, y, z=3): \n", " foo = np.log(z)/(3*x+2*y)\n", " bar = 2*x+y\n", " return foo, bar\n", "\n", "f = (omf.wrap(func)\n", " .declare_partials(of='*', wrt='*', method='cs')\n", " .declare_coloring(wrt='*', method='cs')\n", " .defaults(shape=4))" ] }, { "attachments": {}, "cell_type": "markdown", "id": "79f109ab", "metadata": { "papermill": { "duration": 0.001935, "end_time": "2026-10-02T14:42:09.411991+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.410056+00:00", "status": "completed" }, "tags": [] }, "source": [ "The arguments for the `declare_partials` and `declare_coloring` methods match those\n", "of the same methods on [Component](../../_srcdocs/packages/core/component). Multiple calls\n", "can be made to `declare_partials` to set up different partials, but `declare_coloring` may only\n", "be called once.\n", "\n", "Note that all nonzero partial derivatives *must* be declared or OpenMDAO will assume they are zero.\n", "\n", "### Getting partial derivative information\n", "\n", "The arguments passed to the `declare_partials` and `declare_coloring` methods can be retrieved \n", "using the `get_declare_partials` and `get_declare_coloring` methods respectively. Each of these\n", "returns a list where each entry is the keyword args dict from each call, in the order that they\n", "where called." ] }, { "cell_type": "code", "execution_count": 18, "id": "320ad69b", "metadata": { "execution": { "iopub.execute_input": "2026-10-02T14:42:09.416458Z", "iopub.status.busy": "2026-10-02T14:42:09.416336Z", "iopub.status.idle": "2026-10-02T14:42:09.418901Z", "shell.execute_reply": "2026-10-02T14:42:09.418315Z" }, "papermill": { "duration": 0.005586, "end_time": "2026-10-02T14:42:09.419495+00:00", "exception": false, "start_time": "2026-10-02T14:42:09.413909+00:00", "status": "completed" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[{'method': 'cs', 'of': '*', 'wrt': '*'}]\n", "{'method': 'cs', 'wrt': '*'}\n" ] } ], "source": [ "print(f.get_declare_partials()) # returns a list of args dicts for multiple calls\n", "print(f.get_declare_coloring()) # returns args dict for a single call to declare_coloring" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.14" }, "orphan": true, "papermill": { "default_parameters": {}, "duration": 1.98235, "end_time": "2026-10-02T14:42:09.737599+00:00", "environment_variables": {}, "exception": null, "input_path": "/home/runner/work/OpenMDAO/OpenMDAO/openmdao/docs/openmdao_book/features/building_blocks/func_api.ipynb", "output_path": "/home/runner/work/OpenMDAO/OpenMDAO/openmdao/docs/_executed_book/features/building_blocks/func_api.ipynb", "parameters": {}, "start_time": "2026-10-02T14:42:07.755249+00:00", "version": "2.7.0" } }, "nbformat": 4, "nbformat_minor": 5 }