osiris-utils 1.1.6__py3-none-any.whl → 1.1.7__py3-none-any.whl

examples/example_InputDeck.ipynb

@@ -0,0 +1,520 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%load_ext autoreload\n",
+    "%autoreload 2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import osiris_utils as ou"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Interface with Osiris Input Decks\n",
+    "\n",
+    "For many tasks, it might be useful to read simulation parameters directly from the input deck, or algorithmically generate new Osiris input decks (e.g.to run large parameter scans). \n",
+    "\n",
+    "The class `InputDeckIO` allows you to easily perform theses tasks.\n",
+    "You need to provide it two inputs:\n",
+    "- `filename`: path to OSIRIS input deck\n",
+    "- `verbose`: if `True` will print auxiliary information when parsing the input deck\n",
+    "\n",
+    "\n",
+    "## Reading an input deck"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "Parsing input deck : example_data/thermal.1d\n",
+      "Reading simulation\n",
+      "  random_seed = 0\n",
+      "  wall_clock_limit = \"23:50:00\"\n",
+      "  wall_clock_check = 2000\n",
+      "  wall_clock_checkpoint = .true.\n",
+      "Reading node_conf\n",
+      "  node_number(1:1) = 4\n",
+      "  if_periodic(1:1) = .true.\n",
+      "Reading grid\n",
+      "  nx_p(1:1) = 500\n",
+      "  coordinates = \"cartesian\"\n",
+      "Reading time_step\n",
+      "  dt = 0.0099\n",
+      "  ndump = 1\n",
+      "Reading restart\n",
+      "  if_restart = .false.\n",
+      "Reading space\n",
+      "  xmin(1:1) = 0.\n",
+      "  xmax(1:1) = 5.0\n",
+      "  if_move(1:1) = .false.\n",
+      "Reading time\n",
+      "  tmin = 0.0d0\n",
+      "  tmax = 2.5\n",
+      "Reading el_mag_fld\n",
+      "Reading emf_bound\n",
+      "  type(1:2,1) = \"open\",\"open\"\n",
+      "Reading diag_emf\n",
+      "  ndump_fac = 1\n",
+      "  ndump_fac_ene_int = 1\n",
+      "  reports = \"e1\",\"e2\",\"e3\"\n",
+      "Reading particles\n",
+      "  interpolation = \"linear\"\n",
+      "  num_species = 1\n",
+      "Reading species\n",
+      "  name = \"electrons\"\n",
+      "  num_par_max = 2048\n",
+      "  rqm = -1.0\n",
+      "  num_par_x(1:1) = 64\n",
+      "Reading udist\n",
+      "  uth_type = \"thermal\"\n",
+      "  uth(1:3) = 0.01,0.01,0.01\n",
+      "Reading profile\n",
+      "  density = 1\n",
+      "  profile_type = \"uniform\"\n",
+      "Reading spe_bound\n",
+      "Reading diag_species\n",
+      "  ndump_fac_ene = 1\n",
+      "  ndump_fac_temp = 1\n",
+      "  ndump_fac = 1\n",
+      "  reports = \"charge\"\n",
+      "  rep_udist = \"vfl1\",\"T11\"\n",
+      "Reading smooth\n",
+      "Reading diag_current\n",
+      "Input deck successfully parsed\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "deck = ou.InputDeckIO('example_data/thermal.1d', verbose=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Not only does the object load the different module parameters, but also automatically determines other useful information for downstream tasks.\n",
+    "\n",
+    "Examples include:\n",
+    "- `dim`: number of dimensions\n",
+    "- `n_species`: number of species\n",
+    "- `species`: dictionary with `Species` objects with relevant information (e.g. charge, rqm, etc.)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Simulation Dimensions: 1\n",
+      "Number of species: 1\n",
+      "Species: {'electrons': Specie(name=electrons, rqm=-1.0, q=-1.0, m=1.0)}\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"Simulation Dimensions:\", deck.dim)\n",
+    "print(\"Number of species:\", deck.n_species)\n",
+    "print(\"Species:\", deck.species)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`InputDeckIO` stores the state of the input deck in the parameter `self._sections`.\n",
+    "\n",
+    "You should not access this value directly, instead you can use for example its getter function `self.sections` which returns a deepcopy.\n",
+    "\n",
+    "The returned value corresponds to a list of pairs [section_name, dictionary] where the section_name matches the Osiris input deck section name and he dictionary contains the list of (key, values) for the parameters of the section."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "['simulation', {'random_seed': '0', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n",
+      "['node_conf', {'node_number(1:1)': '4', 'if_periodic(1:1)': '.true.'}]\n",
+      "Number of sections: 18\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(deck.sections[0])\n",
+    "print(deck.sections[1])\n",
+    "print('Number of sections:', len(deck.sections))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Another option is to query the object as if it is an iterator, where the key is the section name.\n",
+    "\n",
+    "This will return a list of dictionaries, since multiple sections can have the same name (e.g. you might have multiple species).\n",
+    "\n",
+    "Once again, a deepcopy is being returned so editing the returned values of the dictionaries will not change the original `InputDeckIO` object."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[{'random_seed': '0', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n",
+      "[{'node_number(1:1)': '4', 'if_periodic(1:1)': '.true.'}]\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(deck['simulation'])\n",
+    "print(deck['node_conf'])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally you can also ask for a specific parameter directly with `get_param()`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "0\n",
+      "0\n"
+     ]
+    }
+   ],
+   "source": [
+    "# this one returns a list since there can be multiple sections with the same name\n",
+    "print(deck.get_param(section='simulation', param='random_seed')[0])\n",
+    "# which is equivalent to doing this\n",
+    "print(deck[\"simulation\"][0]['random_seed'])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Editing an input deck\n",
+    "\n",
+    "To safely edit the value of a parameter in an input deck you can use `set_parameter()`.\n",
+    "\n",
+    "**Note**: This re-writes the object values!\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Before [{'random_seed': '0', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n",
+      "After [{'random_seed': '42', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# edit a parameter already exists\n",
+    "print('Before', deck['simulation'])\n",
+    "deck.set_param('simulation', 'random_seed', value=42)\n",
+    "print('After', deck['simulation'])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Before [{'random_seed': '42', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n",
+      "After [{'random_seed': '42', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.', 'new_parameter': '\"HI!\"'}]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# add a parameter\n",
+    "print(\"Before\", deck[\"simulation\"])\n",
+    "deck.set_param(\"simulation\", \"new_parameter\", value='HI!', unexistent_ok=True)\n",
+    "print(\"After\", deck[\"simulation\"])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And you can also delete the parameter using `delete_param()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Before [{'random_seed': '42', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.', 'new_parameter': '\"HI!\"'}]\n",
+      "After [{'random_seed': '42', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# delete a parameter\n",
+    "print(\"Before\", deck[\"simulation\"])\n",
+    "deck.delete_param(\"simulation\", \"new_parameter\")\n",
+    "print(\"After\", deck[\"simulation\"])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Something slighlty more powerful, is the ability to edit a string in the whole input deck (use with care!)\n",
+    "\n",
+    "This can be done for example to automatically change multiple parameter values that are shared / depend on an external quantity.\n",
+    "\n",
+    "We can do this using the function `set_tag()`.\n",
+    "\n",
+    "**Note**: This only works on the parameter values, not section names / parameter names."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Before [{'random_seed': '42', 'wall_clock_limit': '\"23:50:00\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n",
+      "After 1 [{'random_seed': '#tag#', 'wall_clock_limit': '\"#tag#\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n",
+      "After 2 [{'random_seed': 'BOTH CHANGED', 'wall_clock_limit': '\"BOTH CHANGED\"', 'wall_clock_check': '2000', 'wall_clock_checkpoint': '.true.'}]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# this a dummy example where we change some values to #tag#\n",
+    "print(\"Before\", deck[\"simulation\"])\n",
+    "deck.set_tag(\n",
+    "    '42', # this has to be a string\n",
+    "    '#tag#',\n",
+    ")\n",
+    "deck.set_tag(\n",
+    "    '23:50:00', # this has to be a string\n",
+    "    '#tag#',\n",
+    ")\n",
+    "print(\"After 1\", deck[\"simulation\"])\n",
+    "\n",
+    "# and here we change both values at once\n",
+    "deck.set_tag('#tag#', \"BOTH CHANGED\")\n",
+    "print(\"After 2\", deck[\"simulation\"])\n",
+    "# There is a reason why wall_clock_limit has an extra \"\" done worry\n",
+    "# it is because it should be a string, while random_seed is an int!\n",
+    "# InputDeckIO handles these things for you"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Writing changes to file\n",
+    "\n",
+    "Once you did your changes, you can simply generate a new input deck with `print_to_file()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "simulation\n",
+      "{\n",
+      "\trandom_seed = BOTH CHANGED,\n",
+      "\twall_clock_limit = \"BOTH CHANGED\",\n",
+      "\twall_clock_check = 2000,\n",
+      "\twall_clock_checkpoint = .true.,\n",
+      "}\n",
+      "\n",
+      "node_conf\n",
+      "{\n",
+      "\tnode_number(1:1) = 4,\n",
+      "\tif_periodic(1:1) = .true.,\n",
+      "}\n",
+      "\n",
+      "grid\n",
+      "{\n",
+      "\tnx_p(1:1) = 500,\n",
+      "\tcoordinates = \"cartesian\",\n",
+      "}\n",
+      "\n",
+      "time_step\n",
+      "{\n",
+      "\tdt = 0.0099,\n",
+      "\tndump = 1,\n",
+      "}\n",
+      "\n",
+      "restart\n",
+      "{\n",
+      "\tif_restart = .false.,\n",
+      "}\n",
+      "\n",
+      "space\n",
+      "{\n",
+      "\txmin(1:1) = 0.,\n",
+      "\txmax(1:1) = 5.0,\n",
+      "\tif_move(1:1) = .false.,\n",
+      "}\n",
+      "\n",
+      "time\n",
+      "{\n",
+      "\ttmin = 0.0d0,\n",
+      "\ttmax = 2.5,\n",
+      "}\n",
+      "\n",
+      "el_mag_fld\n",
+      "{\n",
+      "}\n",
+      "\n",
+      "emf_bound\n",
+      "{\n",
+      "\ttype(1:2,1) = \"open\", \"open\",\n",
+      "}\n",
+      "\n",
+      "diag_emf\n",
+      "{\n",
+      "\tndump_fac = 1,\n",
+      "\tndump_fac_ene_int = 1,\n",
+      "\treports = \"e1\", \"e2\", \"e3\",\n",
+      "}\n",
+      "\n",
+      "particles\n",
+      "{\n",
+      "\tinterpolation = \"linear\",\n",
+      "\tnum_species = 1,\n",
+      "}\n",
+      "\n",
+      "species\n",
+      "{\n",
+      "\tname = \"electrons\",\n",
+      "\tnum_par_max = 2048,\n",
+      "\trqm = -1.0,\n",
+      "\tnum_par_x(1:1) = 64,\n",
+      "}\n",
+      "\n",
+      "udist\n",
+      "{\n",
+      "\tuth_type = \"thermal\",\n",
+      "\tuth(1:3) = 0.01, 0.01, 0.01,\n",
+      "}\n",
+      "\n",
+      "profile\n",
+      "{\n",
+      "\tdensity = 1,\n",
+      "\tprofile_type = \"uniform\",\n",
+      "}\n",
+      "\n",
+      "spe_bound\n",
+      "{\n",
+      "}\n",
+      "\n",
+      "diag_species\n",
+      "{\n",
+      "\tndump_fac_ene = 1,\n",
+      "\tndump_fac_temp = 1,\n",
+      "\tndump_fac = 1,\n",
+      "\treports = \"charge\",\n",
+      "\trep_udist = \"vfl1\", \"T11\",\n",
+      "}\n",
+      "\n",
+      "smooth\n",
+      "{\n",
+      "}\n",
+      "\n",
+      "diag_current\n",
+      "{\n",
+      "}\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "deck.print_to_file(\"edited-deck.1d\")\n",
+    "! cat edited-deck.1d"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "tese-env",
+   "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.12.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}