{"id":13744708,"url":"https://github.com/google-research/tensorflow_constrained_optimization","last_synced_at":"2025-04-05T03:02:34.204Z","repository":{"id":57474144,"uuid":"167427139","full_name":"google-research/tensorflow_constrained_optimization","owner":"google-research","description":null,"archived":false,"fork":false,"pushed_at":"2021-07-09T19:13:56.000Z","size":2063,"stargazers_count":309,"open_issues_count":13,"forks_count":53,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-03-29T02:02:29.481Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google-research.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-24T19:48:48.000Z","updated_at":"2025-03-17T08:52:57.000Z","dependencies_parsed_at":"2022-09-10T18:03:23.105Z","dependency_job_id":null,"html_url":"https://github.com/google-research/tensorflow_constrained_optimization","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-research%2Ftensorflow_constrained_optimization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-research%2Ftensorflow_constrained_optimization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-research%2Ftensorflow_constrained_optimization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-research%2Ftensorflow_constrained_optimization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google-research","download_url":"https://codeload.github.com/google-research/tensorflow_constrained_optimization/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280190,"owners_count":20912966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T05:01:14.572Z","updated_at":"2025-04-05T03:02:34.157Z","avatar_url":"https://github.com/google-research.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003c!-- Copyright 2018 The TensorFlow Constrained Optimization Authors. All Rights\nReserved.\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use\nthis file except in compliance with the License. You may obtain a copy of the\nLicense at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed\nunder the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR\nCONDITIONS OF ANY KIND, either express or implied. See the License for the\nspecific language governing permissions and limitations under the License.\n=============================================================================--\u003e\n\n# TensorFlow Constrained Optimization (TFCO)\n\nTFCO is a library for optimizing inequality-constrained problems in TensorFlow\n1.14 and later (including TensorFlow 2). In the most general case, both the\nobjective function and the constraints are represented as `Tensor`s, giving\nusers the maximum amount of flexibility in specifying their optimization\nproblems. Constructing these `Tensor`s can be cumbersome, so we also provide\nhelper functions to make it easy to construct constrained optimization problems\nbased on *rates*, i.e. proportions of the training data on which some event\noccurs (e.g. the error rate, true positive rate, recall, etc).\n\nFor full details, motivation, and theoretical results on the approach taken by\nthis library, please refer to:\n\n\u003e Cotter, Jiang and Sridharan. \"Two-Player Games for Efficient Non-Convex\n\u003e Constrained Optimization\".\n\u003e [ALT'19](http://proceedings.mlr.press/v98/cotter19a.html),\n\u003e [arXiv](https://arxiv.org/abs/1804.06500)\n\nand:\n\n\u003e Narasimhan, Cotter and Gupta. \"Optimizing Generalized Rate Metrics with Three\n\u003e Players\".\n\u003e [NeurIPS'19](https://papers.nips.cc/paper/9258-optimizing-generalized-rate-metrics-with-three-players)\n\nwhich will be referred to as [CoJiSr19] and [NaCoGu19], respectively, throughout\nthe remainder of this document. For more information on this library's optional\n\"two-dataset\" approach to improving generalization, please see:\n\n\u003e Cotter, Gupta, Jiang, Srebro, Sridharan, Wang, Woodworth and You. \"Training\n\u003e Well-Generalizing Classifiers for Fairness Metrics and Other Data-Dependent\n\u003e Constraints\".\n\u003e [ICML'19](http://proceedings.mlr.press/v97/cotter19b/cotter19b.pdf),\n\u003e [arXiv](https://arxiv.org/abs/1807.00028)\n\nwhich will be referred to as [CotterEtAl19].\n\n### Proxy constraints\n\nImagine that we want to constrain the recall of a binary classifier to be at\nleast 90%. Since the recall is proportional to the number of true positive\nclassifications, which itself is a sum of indicator functions, this constraint\nis non-differentiable, and therefore cannot be used in a problem that will be\noptimized using a (stochastic) gradient-based algorithm.\n\nFor this and similar problems, TFCO supports so-called *proxy constraints*,\nwhich are differentiable (or sub/super-differentiable) approximations of the\noriginal constraints. For example, one could create a proxy recall function by\nreplacing the indicator functions with sigmoids. During optimization, each proxy\nconstraint function will be penalized, with the magnitude of the penalty being\nchosen to satisfy the corresponding *original* (non-proxy) constraint.\n\n### Rate helpers\n\nWhile TFCO can optimize \"low-level\" constrained optimization problems\nrepresented in terms of `Tensor`s (by creating a\n`ConstrainedMinimizationProblem` directly), one of TFCO's main goals is to make\nit easy to configure and optimize problems based on rates. This includes both\nvery simple settings, e.g. maximizing precision subject to a recall constraint,\nand more complex, e.g. maximizing ROC AUC subject to the constraint that the\nmaximum and minimum error rates over some particular slices of the data should\nbe within 10% of each other. To this end, we provide high-level \"rate helpers\",\nfor which proxy constraints are handled automatically, and with which one can\nwrite optimization problems in simple mathematical notation (i.e. minimize\n*this* expression subject to *this* list of algebraic constraints).\n\nThese helpers include a number of functions for constructing (in\n\"binary_rates.py\", \"multiclass_rates.py\" and \"general_rates.py\") and\nmanipulating (\"operations.py\", and Python arithmetic operators) rates. Some of\nthese, as described in [NaCoGu19], require introducing slack variables and extra\nimplicit constraints to the resulting optimization problem, which, again, is\nhandled automatically.\n\n### Shrinking\n\nThis library is designed to deal with a very flexible class of constrained\nproblems, but this flexibility can make optimization considerably more\ndifficult: on a non-convex problem, if one uses the \"standard\" approach of\nintroducing a Lagrange multiplier for each constraint, and then jointly\nmaximizing over the Lagrange multipliers and minimizing over the model\nparameters, then a stable stationary point might not even *exist*. Hence, in\nsuch cases, one might experience oscillation, instead of convergence.\n\nThankfully, it turns out that even if, over the course of optimization, no\n*particular* iterate does a good job of minimizing the objective while\nsatisfying the constraints, the *sequence* of iterates, on average, usually\nwill. This observation suggests the following approach: at training time, we'll\nperiodically snapshot the model state during optimization; then, at evaluation\ntime, each time we're given a new example to evaluate, we'll sample one of the\nsaved snapshots uniformly at random, and apply it to the example. This\n*stochastic model* will generally perform well, both with respect to the\nobjective function, and the constraints.\n\nIn fact, we can do better: it's possible to post-process the set of snapshots to\nfind a distribution over at most **m+1** snapshots, where **m** is the number of\nconstraints, that will be at least as good (and will often be much better) than\nthe (much larger) uniform distribution described above. If you're unable or\nunwilling to use a stochastic model at all, then you can instead use a heuristic\nto choose the single best snapshot.\n\nIn many cases, these issues can be ignored. However, if you experience\noscillation during training, or if you want to squeeze every last drop of\nperformance out of your model, consider using the \"shrinking\" procedure of\n[CoJiSr19], which is implemented in the \"candidates.py\" file.\n\n## Public contents\n\n*   [constrained_minimization_problem.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/constrained_minimization_problem.py):\n    contains the `ConstrainedMinimizationProblem` interface, representing an\n    inequality-constrained problem. Your own constrained optimization problems\n    should be represented using implementations of this interface. If using the\n    rate-based helpers, such objects can be constructed as\n    `RateMinimizationProblem`s.\n\n*   [candidates.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/candidates.py):\n    contains two functions, `find_best_candidate_distribution` and\n    `find_best_candidate_index`. Both of these functions are given a set of\n    candidate solutions to a constrained optimization problem, from which the\n    former finds the best distribution over at most **m+1** candidates, and the\n    latter heuristically finds the single best candidate. As discussed above,\n    the set of candidates will typically be model snapshots saved periodically\n    during optimization. Both of these functions require that scipy be\n    installed.\n\n    The `find_best_candidate_distribution` function implements the approach\n    described in Lemma 3 of [CoJiSr19], while `find_best_candidate_index`\n    implements the heuristic used for hyperparameter search in the experiments\n    of Section 5.2.\n\n*   [Optimizing general inequality-constrained problems](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/train/)\n\n    *   [constrained_optimizer.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/train/constrained_optimizer.py):\n        contains `ConstrainedOptimizerV1` and `ConstrainedOptimizerV2`, which\n        inherit from `tf.compat.v1.train.Optimizer` and\n        `tf.keras.optimizers.Optimizer`, respectively, and are the base classes\n        for our constrained optimizers. The main difference between our\n        constrained optimizers, and normal TensorFlow optimizers, is that ours\n        can optimize `ConstrainedMinimizationProblem`s in addition to loss\n        functions.\n\n    *   [lagrangian_optimizer.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/train/lagrangian_optimizer.py):\n        contains the `LagrangianOptimizerV1` and `LagrangianOptimizerV2`\n        implementations, which are constrained optimizers implementing the\n        Lagrangian approach discussed above (with additive updates to the\n        Lagrange multipliers). You recommend these optimizers for problems\n        *without* proxy constraints. They may also work well on problems *with*\n        proxy constraints, but we recommend using a proxy-Lagrangian optimizer,\n        instead.\n\n        These optimizers are most similar to Algorithm 3 in Appendix C.3 of\n        [CoJiSr19], which is discussed in Section 3. The two differences are\n        that they use proxy constraints (if they're provided) in the update of\n        the model parameters, and use wrapped `Optimizer`s, instead of SGD, for\n        the \"inner\" updates.\n\n    *   [proxy_lagrangian_optimizer.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/train/proxy_lagrangian_optimizer.py):\n        contains the `ProxyLagrangianOptimizerV1` and\n        `ProxyLagrangianOptimizerV2` implementations, which are constrained\n        optimizers implementing the proxy-Lagrangian approach mentioned above.\n        We recommend using these optimizers for problems *with* proxy\n        constraints.\n\n        A `ProxyLagrangianOptimizerVx` optimizer with multiplicative swap-regret\n        updates is most similar to Algorithm 2 in Section 4 of [CoJiSr19], with\n        the difference being that it uses wrapped `Optimizer`s, instead of SGD,\n        for the \"inner\" updates.\n\n*   [Helpers for constructing rate-based optimization problems](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/rates/)\n\n    *   [subsettable_context.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/rates/subsettable_context.py):\n        contains the `rate_context` function, which takes a `Tensor` of\n        predictions (or, in eager mode, a nullary function returning a `Tensor`,\n        i.e. the output of a TensorFlow model, through which gradients can be\n        propagated), and optionally `Tensor`s of labels and weights, and returns\n        an object representing a (subset of a) minibatch on which one may\n        calculate rates.\n\n        The related `split_rate_context` function takes *two* `Tensor`s of\n        predictions, labels and weights, the first for the \"penalty\" portion of\n        the objective, and the second for the \"constraint\" portion. The purpose\n        of splitting the context is to improve generalization performance: see\n        [CotterEtAl19] for full details.\n\n        The most important property of these objects is that they are\n        subsettable: if you want to calculate a rate on e.g. only the\n        negatively-labeled examples, or only those examples belonging to a\n        certain protected class, then this can be accomplished via the `subset`\n        method. However, you should *use great caution* with the `subset`\n        method: if the desired subset is a very small proportion of the dataset\n        (e.g. a protected class that's an extreme minority), then the resulting\n        stochastic gradients will be noisy, and during training your model will\n        converge very slowly. Instead, it is usually better (but less\n        convenient) to create an entirely separate dataset for each rare subset,\n        and to construct each subset context directly from each such dataset.\n\n    *   [binary_rates.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/rates/binary_rates.py),\n        [multiclass_rates.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/rates/multiclass_rates.py),\n        and\n        [general_rates.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/rates/general_rates.py):\n        contains functions for constructing rates from contexts. These rates are\n        the \"heart\" of this library, and can be combined into more complicated\n        expressions using python arithmetic operators, or into constraints using\n        comparison operators.\n\n    *   [operations.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/rates/operations.py):\n        contains functions for manipulating rate expressions, including\n        `wrap_rate`, which can be used to convert a `Tensor` into a rate object,\n        as well as `lower_bound` and `upper_bound`, which convert lists of rates\n        into rates representing lower- and upper-bounds on all elements of the\n        list.\n\n    *   [loss.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/rates/loss.py):\n        contains loss functions used in constructing rates. These can be passed\n        as parameters to the optional `penalty_loss` and `constraint_loss`\n        functions in \"binary_rates.py\", \"multiclass_rates.py\" and\n        \"general_rates.py\" (above).\n\n    *   [rate_minimization_problem.py](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/tensorflow_constrained_optimization/python/rates/rate_minimization_problem.py):\n        contains the `RateMinimizationProblem` class, which constructs a\n        `ConstrainedMinimizationProblem` (suitable for use by\n        `ConstrainedOptimizer`s) from a rate expression to minimize, and a list\n        of rate constraints to impose.\n\n## Convex example using proxy constraints\n\nThis is a simple example of recall-constrained optimization on simulated data:\nwe seek a classifier that minimizes the average hinge loss while constraining\nrecall to be at least 90%.\n\nWe'll start with the required imports\u0026mdash;notice the definition of `tfco`:\n\n```python\nimport math\nimport numpy as np\nfrom six.moves import xrange\nimport tensorflow as tf\n\nimport tensorflow_constrained_optimization as tfco\n```\n\nWe'll next create a simple simulated dataset by sampling 1000 random\n10-dimensional feature vectors from a Gaussian, finding their labels using a\nrandom \"ground truth\" linear model, and then adding noise by randomly flipping\n200 labels.\n\n```python\n# Create a simulated 10-dimensional training dataset consisting of 1000 labeled\n# examples, of which 800 are labeled correctly and 200 are mislabeled.\nnum_examples = 1000\nnum_mislabeled_examples = 200\ndimension = 10\n# We will constrain the recall to be at least 90%.\nrecall_lower_bound = 0.9\n\n# Create random \"ground truth\" parameters for a linear model.\nground_truth_weights = np.random.normal(size=dimension) / math.sqrt(dimension)\nground_truth_threshold = 0\n\n# Generate a random set of features for each example.\nfeatures = np.random.normal(size=(num_examples, dimension)).astype(\n    np.float32) / math.sqrt(dimension)\n# Compute the labels from these features given the ground truth linear model.\nlabels = (np.matmul(features, ground_truth_weights) \u003e\n          ground_truth_threshold).astype(np.float32)\n# Add noise by randomly flipping num_mislabeled_examples labels.\nmislabeled_indices = np.random.choice(\n    num_examples, num_mislabeled_examples, replace=False)\nlabels[mislabeled_indices] = 1 - labels[mislabeled_indices]\n```\n\nWe're now ready to construct our model, and the corresponding optimization\nproblem. We'll use a linear model of the form **f(x) = w^T x - t**, where **w**\nis the `weights`, and **t** is the `threshold`.\n\n```python\n# Create variables containing the model parameters.\nweights = tf.Variable(tf.zeros(dimension), dtype=tf.float32, name=\"weights\")\nthreshold = tf.Variable(0.0, dtype=tf.float32, name=\"threshold\")\n\n# Create the optimization problem.\nconstant_labels = tf.constant(labels, dtype=tf.float32)\nconstant_features = tf.constant(features, dtype=tf.float32)\ndef predictions():\n  return tf.tensordot(constant_features, weights, axes=(1, 0)) - threshold\n```\n\nNotice that `predictions` is a nullary function returning a `Tensor`. This is\nneeded to support eager mode, but in graph mode, it's fine for it to simply be a\n`Tensor`. To see how this example could work in graph mode, please see the\nJupyter notebook containing a more-comprehensive version of this example\n([Recall_constraint.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Recall_constraint.ipynb)).\n\nNow that we have the output of our linear model (in the `predictions` variable),\nwe can move on to constructing the optimization problem. At this point, there\nare two ways to proceed:\n\n1.  We can use the rate helpers provided by the TFCO library. This is the\n    easiest way to construct optimization problems based on *rates* (where a\n    \"rate\" is the proportion of training examples on which some event occurs).\n2.  We could instead create an implementation of the\n    `ConstrainedMinimizationProblem` interface. This is the most flexible\n    approach. In particular, it is not limited to problems expressed in terms of\n    rates.\n\nHere, we'll only consider the first of these options. To see how to use the\nsecond option, please refer to\n[Recall_constraint.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Recall_constraint.ipynb).\n\n### Rate helpers\n\nThe main motivation of TFCO is to make it easy to create and optimize\nconstrained problems written in terms of linear combinations of *rates*, where a\n\"rate\" is the proportion of training examples on which an event occurs (e.g. the\nfalse positive rate, which is the number of negatively-labeled examples on which\nthe model makes a positive prediction, divided by the number of\nnegatively-labeled examples). Our current example (minimizing a hinge relaxation\nof the error rate subject to a recall constraint) is such a problem.\n\n```python\n# Like the predictions, in eager mode, the labels should be a nullary function\n# returning a Tensor. In graph mode, you can drop the lambda.\ncontext = tfco.rate_context(predictions, labels=lambda: constant_labels)\nproblem = tfco.RateMinimizationProblem(\n    tfco.error_rate(context), [tfco.recall(context) \u003e= recall_lower_bound])\n```\n\nThe first argument of all rate-construction helpers (`error_rate` and `recall`\nare the ones used here) is a \"context\" object, which represents what we're\ntaking the rate *of*. For example, in a fairness problem, we might wish to\nconstrain the `positive_prediction_rate`s of two protected classes (i.e. two\nsubsets of the data) to be similar. In that case, we would create a context\nrepresenting the entire dataset, then call the context's `subset` method to\ncreate contexts for the two protected classes, and finally call the\n`positive_prediction_rate` helper on the two resulting contexts. Here, we only\ncreate a single context, representing the entire dataset, since we're only\nconcerned with the error rate and recall.\n\nIn addition to the context, rate-construction helpers also take two optional\nnamed parameters\u0026mdash;not used here\u0026mdash;named `penalty_loss` and\n`constraint_loss`, of which the former is used to define the proxy constraints,\nand the latter the \"true\" constraints. These default to the hinge and zero-one\nlosses, respectively. The consequence of this is that we will attempt to\nminimize the average hinge loss (a relaxation of the error rate using the\n`penalty_loss`), while constraining the *true* recall (using the\n`constraint_loss`) by essentially learning how much we should penalize the\nhinge-constrained recall (`penalty_loss`, again).\n\nThe `RateMinimizationProblem` class implements the\n`ConstrainedMinimizationProblem` interface, and is constructed from a rate\nexpression to be minimized (the first parameter), subject to a list of rate\nconstraints (the second). Using this class is typically more convenient and\nreadable than constructing a `ConstrainedMinimizationProblem` manually: the\nobjects returned by `error_rate` and `recall`\u0026mdash;and all other\nrate-constructing and rate-combining functions\u0026mdash;can be manipulated using\npython arithmetic operators (e.g. \"`0.5 * tfco.error_rate(context1) -\ntfco.true_positive_rate(context2)`\"), or converted into a constraint using a\ncomparison operator.\n\n### Wrapping up\n\nWe're almost ready to train our model, but first we'll create a couple of\nfunctions to measure its performance. We're interested in two quantities: the\naverage hinge loss (which we seek to minimize), and the recall (which we\nconstrain).\n\n```python\ndef average_hinge_loss(labels, predictions):\n  # Recall that the labels are binary (0 or 1).\n  signed_labels = (labels * 2) - 1\n  return np.mean(np.maximum(0.0, 1.0 - signed_labels * predictions))\n\ndef recall(labels, predictions):\n  # Recall that the labels are binary (0 or 1).\n  positive_count = np.sum(labels)\n  true_positives = labels * (predictions \u003e 0)\n  true_positive_count = np.sum(true_positives)\n  return true_positive_count / positive_count\n```\n\nAs was mentioned earlier, a Lagrangian optimizer often suffices for problems\nwithout proxy constraints, but a proxy-Lagrangian optimizer is recommended for\nproblems *with* proxy constraints. Since this problem contains proxy\nconstraints, we use the `ProxyLagrangianOptimizerV2`.\n\nFor this problem, the constraint is fairly easy to satisfy, so we can use the\nsame \"inner\" optimizer (an Adagrad optimizer with a learning rate of 1) for\noptimization of both the model parameters (`weights` and `threshold`), and the\ninternal parameters associated with the constraints (these are the analogues of\nthe Lagrange multipliers used by the proxy-Lagrangian formulation). For more\ndifficult problems, it will often be necessary to use different optimizers, with\ndifferent learning rates (presumably found via a hyperparameter search): to\naccomplish this, pass *both* the `optimizer` and `constraint_optimizer`\nparameters to `ProxyLagrangianOptimizerV2`'s constructor.\n\nSince this is a convex problem (both the objective and proxy constraint\nfunctions are convex), we can just take the last iterate. Periodic snapshotting,\nand the use of the `find_best_candidate_distribution` or\n`find_best_candidate_index` functions, is generally only necessary for\nnon-convex problems (and even then, it isn't *always* necessary).\n\n```python\n# ProxyLagrangianOptimizerV2 is based on tf.keras.optimizers.Optimizer.\n# ProxyLagrangianOptimizerV1 (which we do not use here) would work equally well,\n# but is based on the older tf.compat.v1.train.Optimizer.\noptimizer = tfco.ProxyLagrangianOptimizerV2(\n    optimizer=tf.keras.optimizers.Adagrad(learning_rate=1.0),\n    num_constraints=problem.num_constraints)\n\n# In addition to the model parameters (weights and threshold), we also need to\n# optimize over any trainable variables associated with the problem (e.g.\n# implicit slack variables and weight denominators), and those associated with\n# the optimizer (the analogues of the Lagrange multipliers used by the\n# proxy-Lagrangian formulation).\nvar_list = ([weights, threshold] + problem.trainable_variables +\n            optimizer.trainable_variables())\n\nfor ii in xrange(1000):\n  optimizer.minimize(problem, var_list=var_list)\n\ntrained_weights = weights.numpy()\ntrained_threshold = threshold.numpy()\n\ntrained_predictions = np.matmul(features, trained_weights) - trained_threshold\nprint(\"Constrained average hinge loss = %f\" % average_hinge_loss(\n    labels, trained_predictions))\nprint(\"Constrained recall = %f\" % recall(labels, trained_predictions))\n```\n\nNotice that this code is intended to run in eager mode (there is no session): in\n[Recall_constraint.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Recall_constraint.ipynb),\nwe also show how to train in graph mode. Running this code results in the\nfollowing output (due to the randomness of the dataset, you'll get a different\nresult when you run it):\n\n```none\nConstrained average hinge loss = 0.683846\nConstrained recall = 0.899791\n```\n\nAs we hoped, the recall is extremely close to 90%\u0026mdash;and, thanks to the fact\nthat the optimizer uses a (hinge) proxy constraint only when needed, and the\nactual (zero-one) constraint whenever possible, this is the *true* recall, not a\nhinge approximation.\n\nFor comparison, let's try optimizing the same problem *without* the recall\nconstraint:\n\n```python\noptimizer = tf.keras.optimizers.Adagrad(learning_rate=1.0)\nvar_list = [weights, threshold]\n\nfor ii in xrange(1000):\n  # For optimizing the unconstrained problem, we just minimize the \"objective\"\n  # portion of the minimization problem.\n  optimizer.minimize(problem.objective, var_list=var_list)\n\ntrained_weights = weights.numpy()\ntrained_threshold = threshold.numpy()\n\ntrained_predictions = np.matmul(features, trained_weights) - trained_threshold\nprint(\"Unconstrained average hinge loss = %f\" % average_hinge_loss(\n    labels, trained_predictions))\nprint(\"Unconstrained recall = %f\" % recall(labels, trained_predictions))\n```\n\nThis code gives the following output (again, you'll get a different answer,\nsince the dataset is random):\n\n```none\nUnconstrained average hinge loss = 0.612755\nUnconstrained recall = 0.801670\n```\n\nBecause there is no constraint, the unconstrained problem does a better job of\nminimizing the average hinge loss, but naturally doesn't approach 90% recall.\n\n## More examples\n\nThe\n[examples](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/)\ndirectory contains several illustrations of how one can use this library:\n\n*   [Colaboratory](https://colab.research.google.com/) notebooks:\n\n    1.  [Recall_constraint.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Recall_constraint.ipynb):\n        **Start here!** This is a more-comprehensive version of the above simple\n        example. In particular, it can run in either graph or eager modes, shows\n        how to manually create a `ConstrainedMinimizationProblem` instead of\n        using the rate helpers, and illustrates the use of both V1 and V2\n        optimizers.\n\n    1.  [Recall_constraint_keras.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Recall_constraint_keras.ipynb):\n        Same as\n        [Recall_constraint.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Recall_constraint.ipynb),\n        but uses Keras instead of raw TensorFlow.\n        \n    1.  [Recall_constraint_estimator.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Recall_constraint_estimator.ipynb):\n        Same as\n        [Recall_constraint.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Recall_constraint.ipynb),\n        but uses a *canned* estimator instead of raw TensorFlow. See\n        [PRAUC_training.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/PRAUC_training.ipynb)\n        for a tutorial on using TFCO with a *custom* estimator.\n\n    1.  [Wiki_toxicity_fairness.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/Wiki_toxicity_fairness.ipynb):\n        This notebook shows how to train a *fair* classifier to predict whether\n        a comment posted on a Wiki Talk page contain toxic content. The notebook\n        discusses two criteria for fairness and shows how to enforce them by\n        constructing a rate-based optimization optimization problem.\n\n    1.  [CelebA_fairness.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/CelebA_fairness.ipynb):\n        This notebook shows how to train a *fair* classifier to predict to\n        detect a celebrity's smile in images using tf.keras and the large-scale\n        CelebFaces Attributes dataset. The model trained in this notebook is\n        evaluating for fairness across age group, with the false positive rate\n        set as the constraint.\n\n    1.  [PRAUC_training.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/colab/PRAUC_training.ipynb):\n        This notebook shows how to train a model to maximize the *Area Under the\n        Precision-Recall Curve (PR-AUC)*. We'll show how to train the model both\n        with (i) plain TensorFlow (in eager mode), and (ii) with a custom\n        tf.Estimator.\n\n*   [Jupyter](https://jupyter.org/) notebooks:\n\n    1.  [Fairness_adult.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/jupyter/Fairness_adult.ipynb):\n        This notebook shows how to train classifiers for fairness constraints on\n        the UCI Adult dataset using the helpers for constructing rate-based\n        optimization problems.\n\n    1.  [Minibatch_training.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/jupyter/Minibatch_training.ipynb):\n        This notebook describes how to solve a rate-constrained training problem\n        using *minibatches*. The notebook focuses on problems where one wishes\n        to impose a constraint on a group of examples constituting an extreme\n        minority of the training set, and shows how one can speed up convergence\n        by using separate streams of minibatches for each group.\n\n    1.  [Oscillation_compas.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/jupyter/Oscillation_compas.ipynb):\n        This notebook illustrates the oscillation issue raised in the\n        \"shrinking\" section (above): it's possible that the individual iterates\n        won't converge when using the Lagrangian approach to training with\n        fairness constraints, even though they do converge *on average*. This\n        motivate more careful selection of solutions or the use of a stochastic\n        classifier.\n\n    1.  [Post_processing.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/jupyter/Post_processing.ipynb):\n        This notebook describes how to use the shrinking procedure of\n        [CoJiSr19], as discussed in the \"shrinking\" section (above), to\n        post-process the iterates of a constrained optimizer and construct a\n        stochastic classifier from them. For applications where a stochastic\n        classifier is not acceptable, we show how to use a heuristic to pick the\n        best deterministic classifier from the iterates found by the optimizer.\n\n    1.  [Generalization_communities.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/jupyter/Generalization_communities.ipynb):\n        This notebook shows how to improve fairness generalization performance\n        on the UCI Communities and Crime dataset with the split dataset approach\n        of [CotterEtAl19], using the `split_rate_context` helper.\n\n    1.  [Churn.ipynb](https://github.com/google-research/tensorflow_constrained_optimization/tree/master/examples/jupyter/Churn.ipynb):\n        This notebook describes how to use rate constraints for low-churn\n        classification. That is, to train for accuracy while ensuring the\n        predictions don't differ by much compared to a baseline model.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-research%2Ftensorflow_constrained_optimization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle-research%2Ftensorflow_constrained_optimization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-research%2Ftensorflow_constrained_optimization/lists"}