{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Implementing a Declarative Node using the ddn.basic.node Module\n", "\n", "In this notebook we demonstrate how to implement a declarative node using the ddn.basic.node module. This will allow us to explore the behavior of the node and solve simple bi-level optimization problems. For more sophisticated problems and integrating into large deep learning models use modules in the package ddn.pytorch instead.\n", "\n", "We consider the problem of minimizing the KL-divergence between the input $x$ and output $y$ subject to the output forming a valid probablility vector (i.e., the elements of $y$ be positive and sum to one). We will assume strictly positive $x$. The problem can be written formally as\n", "\n", "$$\n", "\\begin{array}{rll}\n", "y =& \\text{argmin}_u & - \\sum_{i=1}^{n} x_i \\log u_i \\\\\n", "& \\text{subject to} & \\sum_{i=1}^{n} u_i = 1\n", "\\end{array}\n", "$$\n", "where the positivity constraint on $y$ is automatically satisfied by the domain of the log function.\n", "\n", "A nice feature of this problem is that we can solve it in closed-form as\n", "$$\n", "y = \\frac{1}{\\sum_{i=1}^{n} x_i} x.\n", "$$\n", "\n", "However, we will only use this for verification and pretend for now that we do not have a closed-form solution. Instead we will make use of the scipy.optimize module to solve the problem via an iterative method. Deriving our deep declarative node from the LinEqConstDeclarativeNode class, we will need to implement two functions: the objective function and the solve function (the constraint and gradient functions are implemented for us).\n" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import numpy as np\n", "import scipy.optimize as opt\n", "\n", "import sys\n", "sys.path.append(\"../\")\n", "from ddn.basic.node import *\n", "\n", "import warnings\n", "warnings.filterwarnings('ignore')\n", "\n", "# create the example node\n", "class MinKLNode(LinEqConstDeclarativeNode):\n", " def __init__(self, n):\n", " # Here we establish the linear equality constraint, Au = b. Since we want the sum of the\n", " # u_i to equal one we set A to be the all-ones row vector and b to be the scalar 1.\n", " super().__init__(n, n, np.ones((1,n)), np.ones((1,1)))\n", "\n", " def objective(self, x, u):\n", " return -1.0 * np.dot(x, np.log(u))\n", " \n", " def solve(self, x):\n", " # Solve the constrained optimization problem using scipy's built-in minimize function. Here we\n", " # initialize the solver at the uniform distribution.\n", " u0 = np.ones((self.dim_y,)) / self.dim_y\n", " result = opt.minimize(lambda u: self.objective(x, u), u0,\n", " constraints={'type': 'eq', 'fun': lambda u: (np.dot(self.A, u) - self.b)[0]})\n", " \n", " # The solve function must always return two arguments, the solution and context (i.e., cached values needed\n", " # for computing the gradient). In the case of linearly constrained problems we do not need the dual solution\n", " # in computing the gradient so we return None for context.\n", " return result.x, None" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Input: [0.37433256 0.34202705 0.00900571 0.18080674 0.63722868]\n", "Expected output: [0.2425375 0.22160612 0.00583498 0.11714828 0.41287312]\n", "Actual output: [0.24256142 0.22163053 0.00583478 0.11714742 0.41282586]\n" ] } ], "source": [ "# test the node\n", "node = MinKLNode(5)\n", "x = np.random.random(5)\n", "print(\"Input: {}\".format(x))\n", "print(\"Expected output: {}\".format(x / np.sum(x)))\n", "\n", "y, _ = node.solve(x)\n", "print(\"Actual output: {}\".format(y))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We now plot the function and gradient sweeping the first component of the input $x_1$ from 0.1 to 10.0 while holding the other elements of $x$ constant." ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "image/png": "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\n", "text/plain": [ "