doc/ipynb/tuto_lab_user.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import os\n",
    "import fluiddyn as fld\n",
    "import fluidlab"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial: working in the laboratory (user perspective)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "FluidDyn uses the object-oriented programming concepts. It deals with objects, which is a very natural way to represent and drive\n",
    "experiments since experiments consist in objects interacting with each other.\n",
    "\n",
    "Regarding the laboratory, each physical object (a pump, a traverse, a probe, an acquisition board, a tank filled with a stratified fluid...) is represented and controlled by an instance of a class. The experimental results can also be represented by other types of objects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example of a conductivity probe attached to a moving traverse"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Let's consider a real-life example, how to use a conductivity probe attached to a moving traverse. FluidDyn provides the class \n",
    ":class:`fluidlab.objects.probes.MovingConductivityProbe` which can be used like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import the class representing the moving conductivity probe\n",
    "from fluidlab.objects.probes import MovingConductivityProbe\n",
    "\n",
    "# create an instance of this class\n",
    "probe = MovingConductivityProbe()\n",
    "\n",
    "try:\n",
    "    # set a parameter, the sample rate (in Hz)\n",
    "    probe.set_sample_rate(2000)\n",
    "\n",
    "    # just move the probe (in mm and mm/s)\n",
    "    probe.move(deltaz=-100, speed=50)\n",
    "\n",
    "    # just measure without moving (in s)\n",
    "    measurements1 = probe.measure(duration=5)\n",
    "\n",
    "    # move and measure (in mm and mm/s)\n",
    "    measurements2 = probe.move_measure(deltaz=100, speed=100)\n",
    "except AttributeError:\n",
    "    pass"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Of course this is a very simple example and there are more options to create the object *probe* and for the functions. Look at the\n",
    "documentation, i.e. in this case here: :class:`fluidlab.objects.probes.MovingConductivityProbe`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save and load an object"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "For some classes of FluidDyn, the objects can be saved in a file and loaded afterwards. This is a very useful feature! To see how it works, we can consider the example of a tank filled with a stratified fluid, which is represented by the class\n",
    ":class:`fluidlab.objects.tanks.StratifiedTank`. Let's first see how we create a tank:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from fluidlab.objects.tanks import StratifiedTank\n",
    "\n",
    "# create a tank with a linear stratification (see the doc of the class)\n",
    "tank = StratifiedTank(\n",
    "    H=550, S=100, \n",
    "    z=[0, 500], rho=[1.1, 1])"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The numerical object *tank* contains some information and can be use to do useful. We can for example fill the physical tank with the wanted profile (which makes use of some pumps also controlled by FluidDyn, see the class :class:`fluidlab.objects.pumps.MasterFlexPumps`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tank.fill()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The numerical object *tank* can be saved in a file tank.h5 with its function *save* (the documentation explains how to control where the file is saved):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if os.path.exists('/tmp/tank.h5'):\n",
    "    os.remove('/tmp/tank.h5')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tank.save('/tmp')"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "If we come back some days later and we want to use again this particular instance of :class:`fluidlab.objects.tanks.StratifiedTank`.\n",
    "Let's assume that the file is in a directory ``/tmp/exp0``.  If we really know that this file contains the information for loading an object of :class:`fluidlab.objects.tanks.StratifiedTank`, we can obtain the numerical representation of the tank by doing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "del(tank)\n",
    "tank = StratifiedTank(str_path='/tmp')"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "But most of the case, it is easier and safer to use the function :func:`fluiddyn.util.util.create_object_from_file` like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "path_to_tank_h5 = '/tmp/tank.h5'\n",
    "tank = fld.create_object_from_file(path_to_tank_h5)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The function :func:`create_object_from_file` gets the correct class from information written in the file, calls the constructor of this class and return the object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tank.profile.plot()"
   ]
  }
 ],
 "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.7.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}