docs/source/example_notebooks/flattening_and_folding_free_default.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Default values for ``free``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import paragami"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can set a default value for whether or not a parameter is free.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a_freeflat:\n",
      "[ 0.13919912  0.41973416  0.12037979  0.7396427   0.44432253 -0.06185827]\n",
      "\n",
      "a:\n",
      "[[1.32101217 0.48242269 0.85011051]\n",
      " [0.48242269 1.4483919  0.81161586]\n",
      " [0.85011051 0.81161586 1.6281241 ]]\n",
      "\n"
     ]
    }
   ],
   "source": [
    "a = np.eye(3) + np.random.random((3, 3))\n",
    "a = 0.5 * (a + a.T)\n",
    "\n",
    "a_free_pattern = paragami.PSDSymmetricMatrixPattern(size=3, free_default=True)\n",
    "\n",
    "a_freeflat = a_free_pattern.flatten(a)\n",
    "print('a_freeflat:\\n{}\\n'.format(a_freeflat))\n",
    "print('a:\\n{}\\n'.format(a_free_pattern.fold(a_freeflat)))\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default is be overridden by setting the argument ``free``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a_flat:\n",
      "[1.32101217 0.48242269 0.85011051 0.48242269 1.4483919  0.81161586\n",
      " 0.85011051 0.81161586 1.6281241 ]\n",
      "\n",
      "a:\n",
      "[[1.32101217 0.48242269 0.85011051]\n",
      " [0.48242269 1.4483919  0.81161586]\n",
      " [0.85011051 0.81161586 1.6281241 ]]\n",
      "\n"
     ]
    }
   ],
   "source": [
    "a_flat = a_free_pattern.flatten(a, free=False)\n",
    "print('a_flat:\\n{}\\n'.format(a_flat))\n",
    "print('a:\\n{}\\n'.format(a_free_pattern.fold(a_flat, free=False)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can change the default by setting the attribute ``free_default``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a_flat:\n",
      "[1.32101217 0.48242269 0.85011051 0.48242269 1.4483919  0.81161586\n",
      " 0.85011051 0.81161586 1.6281241 ]\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Now this pattern is misnamed!\n",
    "a_free_pattern.free_default = False\n",
    "print('a_flat:\\n{}\\n'.format(a_free_pattern.flatten(a)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An error is raised if ``free_default`` is ``None`` and ``free`` is not specified."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Folding with a_free_pattern raised the following ValueError:\n",
      "If ``free_default`` is ``None``, ``free`` must be specified.\n"
     ]
    }
   ],
   "source": [
    "a_free_pattern.free_default = None\n",
    "try:\n",
    "    a_free_pattern.flatten(a)\n",
    "except ValueError as err:\n",
    "    print('Folding with a_free_pattern raised the following ValueError:\\n{}'.format(err))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pattern containers override the default values of their contents so you don't accidentally mix free and non-free flattened values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "This pattern alone is non-free by default:\n",
      "[1.32101217 0.48242269 0.85011051 0.48242269 1.4483919  0.81161586\n",
      " 0.85011051 0.81161586 1.6281241 ]\n",
      "\n",
      "This pattern alone is free by default:\n",
      "[ 0.13919912  0.41973416  0.12037979  0.7396427   0.44432253 -0.06185827]\n",
      "\n",
      "But the dictionary pattern overrides the default:\n",
      "[ 0.13919912  0.41973416  0.12037979  0.7396427   0.44432253 -0.06185827\n",
      "  0.13919912  0.41973416  0.12037979  0.7396427   0.44432253 -0.06185827]\n",
      "\n",
      "If no default is specified, an error is raised so that you do not accidentally mix free and non-free flat values.\n",
      "Folding a container with no default raised the follding ValueError:\n",
      "If ``free_default`` is ``None``, ``free`` must be specified.\n"
     ]
    }
   ],
   "source": [
    "dict_pattern = paragami.PatternDict(free_default=True)\n",
    "\n",
    "dict_pattern['a1'] = paragami.PSDSymmetricMatrixPattern(size=3, free_default=False)\n",
    "dict_pattern['a2'] = paragami.PSDSymmetricMatrixPattern(size=3, free_default=True)\n",
    "\n",
    "print('\\nThis pattern alone is non-free by default:')\n",
    "print(dict_pattern['a1'].flatten(a))\n",
    "\n",
    "print('\\nThis pattern alone is free by default:')\n",
    "print(dict_pattern['a2'].flatten(a))\n",
    "\n",
    "print('\\nBut the dictionary pattern overrides the default:')\n",
    "param_dict = { 'a1': a, 'a2': a}\n",
    "print(dict_pattern.flatten(param_dict))\n",
    "\n",
    "print('\\nIf no default is specified, an error is raised ' +\n",
    "      'so that you do not accidentally mix free and non-free flat values.')\n",
    "dict_pattern_nodefault = paragami.PatternDict()\n",
    "try:\n",
    "    dict_pattern_nodefault.flatten(param_dict)\n",
    "except ValueError as err:\n",
    "    print('Folding a container with no default raised the follding ValueError:\\n{}'.format(err))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}