doc/interactive_tutorial/07-Channels.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "# preamble script to check and install AMUSE components if necessary\n",
    "\n",
    "# required packages for this tutorial:\n",
    "PACKAGES=\"amuse-framework\"\n",
    "# skip in case a full development install is present\n",
    "pip show amuse-devel && exit 0\n",
    "for package in ${PACKAGES} \n",
    "do\n",
    "  pip show ${package} || pip install ${package}\n",
    "done"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# the following fixes are highly recommended\n",
    "\n",
    "#allow oversubscription for openMPI\n",
    "import os\n",
    "os.environ[\"OMPI_MCA_rmaps_base_oversubscribe\"]=\"true\"\n",
    "\n",
    "# use lower cpu resources for idle codes\n",
    "from amuse.support import options\n",
    "options.GlobalOptions.instance().override_value_for_option(\"polling_interval_in_milliseconds\", 10)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "from matplotlib import pyplot\n",
    "import numpy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Part of interaction between codes in AMUSE is based on exchanging data between the *community* codes or exchanging data between these codes and AMUSE. As you might have noticed in the pervious tutorial topic, every code provides access to particle collections or grids. The data of these collections or grids *live* inside the code, while the data of collections created in the script *live* inside the python process.\n",
    "\n",
    "\n",
    "<p style=\"background-color: lightyellow\">\n",
    "<em>Background:</em> All data storage of particle collections (or grids) is implemented by different storage classes. AMUSE supports storage classes that simply store the data in python lists and numpy arrays. AMUSE also supports storage classes that send messages to the codes to perform the actual storage and retrieval. At the script level the interface to these classes is all the same, so in normal use they behave the same. The performance of the different storage classes will vary, for a code storage the data may be sent over an internet connection causing slower reaction times. Smart usage of channels and caching data in memory sets will increase performance.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from amuse.lab import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is easy to make two collections with the same particles, we only have to copy the collection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "particles1 = Particles(4)\n",
    "particles2 = particles1.copy()\n",
    "print(particles1)\n",
    "print(particles2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The particles in the collection have the same keys and are considered the same particles in AMUSE, although they are not identical."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(particles1[1] == particles2[1])\n",
    "print(particles1[1] is particles2[1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Setting the mass of the particles in one collection will not influence the particles in the second collection."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "particles1.mass = [5, 6, 7, 8] | units.MSun\n",
    "particles1.radius = [1, 2, 3, 4] | units.RSun\n",
    "print(particles2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You could however easily copy the data over with an attribute assignment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "particles2.mass = particles1.mass\n",
    "print(particles2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However this will fail (or be incorrect) if one of the sets changed in before the copy action"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "particles2.remove_particle(particles2[2])\n",
    "particles2.mass = particles1.mass\n",
    "print(particles2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In general assuming that the number and order of particles in sets is maintained is unsafe. The particle set indices no longer refer to the same particles as we removed the third particle from `particles2`. We just tried to copy the masses based on the position of the particle in the collection and not based on the identity of the particle. In complex scripts where particles are removed and added due to physical processes this will cause incorrect results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(particles1[2] == particles2[2])\n",
    "print(particles1[2].mass)\n",
    "print(particles2[2].mass)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "AMUSE provides channels to track the particle identities and optimize the transport of attribute values between collections. Channels are save to use when adding or removing particles. Channels are uni-directional, you'll need two to be able to do bi-derectional information exchange."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "channel_from_1_to_2 = particles1.new_channel_to(particles2)\n",
    "channel_from_1_to_2.copy_attribute(\"mass\")\n",
    "print(particles1)\n",
    "print(particles2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see the particles with the same key now also have the same mass. Channels are always defined between exactly 2 collections and will only copy data of the overlapping particles in both collections. In the abouve case data of 3 particles was copied. \n",
    "\n",
    "Channels can copy an attribute from one set to another and give the copy a new name. This is useful, as some codes define particles with attributes having the same name but a script my assign a different meaning to these names. A stellar evolution code will define the star radius as just that, the star radius, but a stellar dynamics code might interpret the star radius as the star interaction radius (which will be factors larger)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "channel_from_1_to_2.copy_attribute(\"mass\", \"core_mass\")\n",
    "print(particles2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Channels can be used to copy multiple attributes in one go, this can optimize data transport between codes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "channel_from_1_to_2.copy_attributes([\"mass\", \"radius\"])\n",
    "print(particles2)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.8.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}