tutorials: Updating wording in MP + MBP tutorial (RobotLocomotion#12443)

tutorials/mathematical_program_multibody_plant.ipynb

@@ -16,8 +16,11 @@
    "source": [
     "This shows examples of:\n",
     "* Creating a `MultibodyPlant` containing an IIWA arm\n",
-    "* Adding a custom (but trivial) constraint to a `MathematicalProgram`\n",
-    "which uses `MultibodyPlant`.\n",
+    "* Solve a simple inverse kinematics problem by writing a custom evaluator\n",
+    "for `MathematicalProgram` that can handle both `float` and `AutoDiffXd`\n",
+    "inputs\n",
+    "* Using the custom evaluator in a constraint\n",
+    "* Using the custom evaluator in a cost.\n",
     "\n",
     "***To be added***:\n",
     "* Using `pydrake.multibody.inverse_kinematics`.\n",
@@ -28,11 +31,34 @@
     "Please review the\n",
     "[API for `pydrake.multibody.inverse_kinematics`](\n",
     "https://drake.mit.edu/pydrake/pydrake.multibody.inverse_kinematics.html)\n",
-    "before you delve too far into writing custom evaluators. Chances are,\n",
-    "you will find the functionality you want there.\n",
+    "before you delve too far into writing custom evaluators for use with\n",
+    "`MultibodyPlant`. You may find the functionality you want there."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Inverse Kinematics Problem\n",
     "\n",
-    "The trivial examples below are just for showing how to use\n",
-    "`MultibodyPlant` inside custom evaulators."
+    "In this tutorial, we will be solving a simple inverse kinematics problem to\n",
+    "put Link 7's origin at a given distance from a target position. We will use\n",
+    "`MathematicalProgram` to solve this problem in two different ways: first\n",
+    "using the evaluator as a constraint (with a minimum and maximum distance),\n",
+    "and second using the evaluator as a cost (to get as close as possible).\n",
+    "\n",
+    "For more information about `MathematicalProgram`, please see the\n",
+    "[`MathematicalProgram` Tutorial](./mathematical_program.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup\n",
+    "\n",
+    "First, we will import the necessary modules and load a `MultibodyPlant`\n",
+    "containing an IIWA."
    ]
   },
   {
@@ -77,16 +103,15 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Custom evaluator for height of link 7's origin"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "In order to write a custom evaluator in Python, we must make sure\n",
-    "it handles `dtype=float` |as well as `dtype=object` (which implies\n",
-    "`AutoDiffXd` for `MathematicalProgram` evaulators)."
+    "## Writing our Custom Evaluator\n",
+    "\n",
+    "Our evaluator is implemented using the custom evaluator\n",
+    "`link_7_distance_to_target`, since the its functionality is not already\n",
+    "handled by existing classes in the `inverse_kinematics` submodule.\n",
+    "\n",
+    "Note that in order to write a custom evaluator in Python, we must explicitly\n",
+    "check for `float` and `AutoDiffXd` inputs, as you will see in the implementation\n",
+    "of `link_7_distance_to_target`."
    ]
   },
   {
@@ -135,9 +160,18 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Trivial constraint on distance between link 7's origin and target\n",
+    "## Formulating the Optimization Problems"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Formluation 1: Using the Custom Evaluator in a Constraint\n",
+    "\n",
+    "We will formulate and solve the problem with a basic cost and our custom\n",
+    "evaluator in a constraint.\n",
     "\n",
-    "We create a simple program with a simple cost and our custom constraint.\n",
     "Note that we use the vectorized version of the evaluator."
    ]
   },
@@ -183,7 +217,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Trivial cost on distance between link 7's origin and target\n",
+    "### Formulation 2: Using Custom Evaluator in a Cost\n",
+    "\n",
+    "We will formulate and solve the problem, but this time we will use our custom\n",
+    "evaluator in a cost.\n",
     "\n",
     "Note that we use the scalar version of the evaluator."
    ]