{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Saving and Restoring an Array of Polytopes\n",
    "\n",
    "If you want to deal with a whole family of polytopes at the same time, it will sometimes be convenient to save and restore them to a single file. polymake has a simple mechanism for this, storing your array of polytopes into a single tarball.\n",
    "\n",
    "The necessary functions for this are contained in the script \"tarballs\" that you can load into your polymake session by calling\n",
    "\n",
    "    \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "script(\"tarballs\");"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "It provides the two functions `pack_tarball` and `unpack_tarball`. \n",
    "\n",
    "## Storing\n",
    "\n",
    "Here is a simple example, where we create an array @a containing a cube and a simplex and save this to a file.\n",
    "\n",
    "    \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@a = ();\n",
    "$a[0] = cube(3);\n",
    "$a[1] = simplex(3);\n",
    "pack_tarball(\"simple_polytopes.tgz\",@a);"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "This creates a file `simple_polytopes.tgz` in the current directory that is a tarred (and gzipped) archive containing two polymake files. polymake detects whether you want the archive gzipped or not from the supplied file extension (`*.tar.gz` or `*.tgz`). You can verify this by calling `tar tvfz simple_polytopes.tgz` from the command line:\n",
    "\n",
    "    \n",
    "    [nightingale]:~/temp>tar tvfz simple_polytopes.tgz \n",
    "    -rw------- xxx/yyy 1468 2009-07-01 17:20 1.poly\n",
    "    -rw------- xxx/yyy  854 2009-07-01 17:20 2.poly\n",
    "    [nightingale]:~/temp>\n",
    "\n",
    "\n",
    "If you want to get more descriptive names for your polymake files then you have to set a name for each polytope first.\n",
    "\n",
    "    \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "$a[0]->name = \"my_cube\";\n",
    "$a[1]->name = \"my_simplex\";\n",
    "pack_tarball(\"simple_polytopes.tgz\",@a);"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "sets the names of the files in the tarball to `my_cube.poly` and `my_simplex.poly`:\n",
    "\n",
    "    \n",
    "    [nightingale]:~/temp>tar tvfz simple_polytopes.tgz \n",
    "    -rw------- xxx/yyy  952 2009-07-01 17:21 my_cube.poly\n",
    "    -rw------- xxx/yyy  650 2009-07-01 17:21 my_simplex.poly\n",
    "    [nightingale]:~/temp>\n",
    "\n",
    "\n",
    "## Restoring the array\n",
    "\n",
    "You can restore your saved array by using the function `unpack_tarball`:\n",
    "\n",
    "    \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "my_cube\n",
       "\n"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@a=unpack_tarball(\"simple_polytopes.tgz\");\n",
    "print $a[0]->name;"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "If you just want a specific polytope from your tarball, then you can supply its name in the command:\n",
    "\n",
    "    \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "my_simplex\n",
       "\n"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@a=unpack_tarball(\"simple_polytopes.tgz\",\"my_simplex.poly\");\n",
    "print $a[0]->name;"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "You may supply more than one filename. However, wildcards are not supported. Note that changes in the files are not automatically stored in the archive, you have to call `pack_tarball` to update the files. \n",
    "\n",
    "## Packing archives outside polymake\n",
    "\n",
    "You can of course apply `tar` to your favorite family of polymake files to create a tarball without using polymake. It can be read by polymake as long as the files are at the root of the archive (i.e. don't pack a whole directory tree). The archive also may not contain non-polymake files. \n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "polymake",
   "language": "polymake",
   "name": "polymake"
  },
  "language_info": {
   "codemirror_mode": "perl",
   "file_extension": ".pm",
   "mimetype": "text/x-polymake",
   "name": "polymake"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}