Merge branch 'master' into ckernels

Author: erikvansebille

docs/index.rst

@@ -80,65 +80,73 @@ The best way to get started with Parcels is to have a look at the Jupyter notebo
 
 * `Plotting tutorial <http://nbviewer.jupyter.org/github/OceanParcels/parcels/blob/master/parcels/examples/tutorial_plotting.ipynb>`_ for further explanation on the plotting capabilities of Parcels
 
-.. _installing-linux-macos:
 
-Installing Parcels on Linux and macOS
-=====================================
+.. _installing-parcels:
 
-Parcels depends on a working Python installation, a netCDF installation, a C
-compiler, and various Python packages.
+Installing Parcels
+==================
 
-The simplest way to install Parcels is to use Anaconda and Conda-Forge for all
-requirements. This is the “batteries-included” solution probably suitable for most users. 
-Note that if you already have an existing Python setup that you wish to use for Parcels, you should follow the instructions at the bottom of this section.
+This is the “batteries-included” solution probably suitable for most users.
 
-The five steps below are the installation instructions for Linux and macOS. Note that for Windows, steps 2 and 5 are slightly different, see :ref:`installing-windows` below.
+The simplest way to install Parcels is to use Anaconda and the Parcels Conda-Forge package with the latest release of Parcels.  This package will automatically install (almost) all the requirements for a fully functional installaion of Parcels.
 
-1. Install Anaconda's Miniconda following the steps at https://conda.io/docs/user-guide/install/. All the code below assumes that you download the Python-2 version.
+The steps below are the installation instructions for Linux / macOS and for Windows.  If the commands for Linux / macOS and Windows differ, this is indicated with a comment at the end of the line.
 
-2. Download Parcels' `environment.yml <https://raw.githubusercontent.com/OceanParcels/parcels/master/environment.yml>`_ file, navigate to the directory where you saved that file, and run::
+1. Install Anaconda's Miniconda following the steps at https://conda.io/docs/user-guide/install/.  All the code below assumes that you download the Python-2 version.  If you're on Linux / macOS, it also assumes that you installed Miniconda-2 to your home directory.
 
-    source $HOME/miniconda2/bin/activate root
-    conda env create -f environment.yml -n py2_parcels
-    source $HOME/miniconda2/bin/activate py2_parcels
-    pip install git+https://github.com/OceanParcels/parcels.git@master
+2. Start a terminal (Linux / macOS) or the Anaconda prompt (Windows). Activate the root (or base) environment of your Miniconda and create an environment containing Parcels, all its essential dependencies, and the nice-to-have Jupyter and Basemap package::
 
-3. Validate the installation by downloading the `example_peninsula.py <https://raw.githubusercontent.com/OceanParcels/parcels/master/parcels/examples/example_peninsula.py>`_ file, navigate to the directory where you saved that file, and then run::
+    source $HOME/miniconda2/bin/activate root  # Linux / macOS
+    activate root                              # Windows
 
-    python example_peninsula.py --fieldset 100 100
+    conda create -n py2_parcels -c conda-forge parcels jupyter basemap basemap-data-hires
+
+3. Activate the newly created Parcels environment, get a copy of the the Parcels tutorials and examples, and run the simplest of the examples to validate that you have a working Parcels setup::
 
-4. Optionally, if you want to run all the examples and tutorials, you can get tutorials and example data by running::
+    source $HOME/miniconda2/bin/activate py2_parcels  # Linux / macOS
+    activate py2_parcels                              # Windows
 
     parcels_get_examples parcels_examples
     cd parcels_examples
+
+    python example_peninsula.py --fieldset 100 100
+
+4. Optionally, if you want to run all the examples and tutorials, start Jupyter and open the tutorial notebooks::
+
     jupyter notebook
 
 5. The next time you start a terminal and want to work with Parcels, activate the environment with::
 
-    source $HOME/miniconda2/bin/activate py2_parcels
+    source $HOME/miniconda2/bin/activate py2_parcels  # Linux / macOS
+    activate py2_parcels                              # Windows
+
+
+.. _installing-arbitrary-Git-reference:
+
+Installing a non-released version of Parcels
+============================================
 
-An alternative, more advanced option is to use an existing netCDF installation and
-C compiler, ``git clone`` the `master branch of Parcels
-<https://github.com/OceanParcels/parcels>`_
-and ``pip install`` the dependencies in the `environment.yml <https://raw.githubusercontent.com/OceanParcels/parcels/master/environment.yml>`_ file.
+There might be cases where you want to install a version of Parcels that has not been released yet.  (Perhaps, if you want to use a bleeding-edge feature which already is included on Github, but not in the conda-forge package.)
 
-.. _installing-windows:
+Then, just after step 2 of :ref:`installing-parcels` above, remove the conda-forge package again, and use Pip to install Parcels from Github::
+
+    source $HOME/miniconda2/bin/activate py2_parcels_master  # Linux / macOS
+    activate py2_parcels_master                              # Windows
+
+    conda remove parcels
+    pip install git+https://github.com/OceanParcels/parcels.git@master
 
-Installing Parcels on Windows
-=============================
 
-The installation process and usage of Parcels is much the same as under :ref:`installing-linux-macos` above. **However, steps 2 and 5 will be different**, as detailed below:
+.. _installation-dev:
 
-2. Download Parcels' `environment_win.yml <https://raw.githubusercontent.com/OceanParcels/parcels/master/environment_win.yml>`_ file from the main Parcels' directory, start the ``Anaconda Prompt`` from the Windows start menu, navigate to the directory where you saved that file, and then run::
+Installation for developers
+===========================
 
-        activate root
-        conda env create -f environment_win.yml -n py2_parcels
-        activate py2_parcels
-        pip install git+https://github.com/OceanParcels/parcels.git@master
+Parcels depends on a working Python installation, a netCDF installation, a C compiler, and various Python packages.  If you prefer to maintain your own Python installation providing all this, ``git clone`` the `master branch of Parcels <https://github.com/OceanParcels/parcels>`_ and manually ``pip install`` all packages lister under ``dependencies`` in the `environment.yml <https://raw.githubusercontent.com/OceanParcels/parcels/master/environment.yml>`_ file.
 
-5. The next time you start the ``Anaconda Prompt`` and want to work with Parcels, activate the environment with::
+Then, install Parcels in an `editable way <https://pip.pypa.io/en/stable/reference/pip_install/?highlight=editable#cmdoption-e>`_ by running::
 
-        activate py2_parcels
+    pip install -e .
 
 
 Getting involved

parcels/examples/example_decaying_moving_eddy.py

@@ -53,12 +53,12 @@ def true_values(t, x_0, y_0):  # Calculate the expected values for particles at
 def decaying_moving_example(fieldset, mode='scipy', method=AdvectionRK4):
     pset = ParticleSet(fieldset, pclass=ptype[mode], lon=start_lon, lat=start_lat)
 
-    endtime = delta(days=2)
+    runtime = delta(days=2)
     dt = delta(minutes=5)
-    interval = delta(hours=1)
+    outputdt = delta(hours=1)
 
-    pset.execute(method, endtime=endtime, dt=dt, interval=interval,
-                 output_file=pset.ParticleFile(name="DecayingMovingParticle"), show_movie=False)
+    pset.execute(method, runtime=runtime, dt=dt, moviedt=None,
+                 output_file=pset.ParticleFile(name="DecayingMovingParticle", outputdt=outputdt))
 
     return pset
 

parcels/examples/example_globcurrent.py

@@ -73,8 +73,7 @@ def test_globcurrent_particles(mode):
 
     pset = ParticleSet(fieldset, pclass=ptype[mode], lon=lonstart, lat=latstart)
 
-    pset.execute(AdvectionRK4, runtime=delta(days=1), dt=delta(minutes=5),
-                 interval=delta(hours=1))
+    pset.execute(AdvectionRK4, runtime=delta(days=1), dt=delta(minutes=5))
 
     assert(abs(pset[0].lon - 23.8) < 1)
     assert(abs(pset[0].lat - -35.3) < 1)
@@ -88,5 +87,4 @@ def test_globcurrent_time_extrapolation_error(mode):
     pset = ParticleSet(fieldset, pclass=ptype[mode], lon=[25], lat=[-35],
                        time=fieldset.U.time[0]-delta(days=1).total_seconds())
 
-    pset.execute(AdvectionRK4, runtime=delta(days=1),
-                 dt=delta(minutes=5), interval=delta(hours=1))
+    pset.execute(AdvectionRK4, runtime=delta(days=1), dt=delta(minutes=5))

parcels/examples/example_moving_eddies.py

@@ -84,11 +84,11 @@ def moving_eddies_example(fieldset, npart=2, mode='jit', verbose=False,
         print("Initial particle positions:\n%s" % pset)
 
     # Execute for 1 week, with 1 hour timesteps and hourly output
-    endtime = delta(days=7)
-    print("MovingEddies: Advecting %d particles for %s" % (npart, str(endtime)))
-    pset.execute(method, endtime=endtime, dt=delta(hours=1),
-                 output_file=pset.ParticleFile(name="EddyParticle"),
-                 interval=delta(hours=1), show_movie=False)
+    runtime = delta(days=7)
+    print("MovingEddies: Advecting %d particles for %s" % (npart, str(runtime)))
+    pset.execute(method, runtime=runtime, dt=delta(hours=1),
+                 output_file=pset.ParticleFile(name="EddyParticle", outputdt=delta(hours=1)),
+                 moviedt=None)
 
     if verbose:
         print("Final particle positions:\n%s" % pset)
@@ -106,16 +106,16 @@ def test_moving_eddies_fwdbwd(mode, npart=2):
                                  start=(3.3, 46.), finish=(3.3, 47.8))
 
     # Execte for 14 days, with 30sec timesteps and hourly output
-    endtime = delta(days=1)
+    runtime = delta(days=1)
     dt = delta(minutes=5)
-    interval = delta(hours=1)
-    print("MovingEddies: Advecting %d particles for %s" % (npart, str(endtime)))
-    pset.execute(method, endtime=endtime, dt=dt, interval=interval,
-                 output_file=pset.ParticleFile(name="EddyParticlefwd"))
+    outputdt = delta(hours=1)
+    print("MovingEddies: Advecting %d particles for %s" % (npart, str(runtime)))
+    pset.execute(method, runtime=runtime, dt=dt,
+                 output_file=pset.ParticleFile(name="EddyParticlefwd", outputdt=outputdt))
 
     print("Now running in backward time mode")
-    pset.execute(method, endtime=0, dt=-dt, interval=-interval,
-                 output_file=pset.ParticleFile(name="EddyParticlebwd"))
+    pset.execute(method, endtime=0, dt=-dt,
+                 output_file=pset.ParticleFile(name="EddyParticlebwd", outputdt=outputdt))
 
     assert(pset[0].lon > 3.2 and 45.9 < pset[0].lat < 46.1)
     assert(pset[1].lon > 3.2 and 47.7 < pset[1].lat < 47.9)

parcels/examples/example_nemo_curvilinear.py

@@ -30,10 +30,10 @@ def periodicBC(particle, pieldSet, time, dt):
             particle.lon -= 360
 
     pset = ParticleSet.from_list(field_set, ptype[mode], lon=lonp, lat=latp)
-    pfile = ParticleFile(outfile, pset)
+    pfile = ParticleFile(outfile, pset, outputdt=delta(days=1))
     kernels = pset.Kernel(AdvectionRK4) + periodicBC
     pset.execute(kernels, runtime=delta(days=1)*160, dt=delta(hours=6),
-                 interval=delta(days=1), output_file=pfile)
+                 output_file=pfile)
     assert np.allclose([pset[i].lat - latp[i] for i in range(len(pset))], 0, atol=1e-3)
 
 

parcels/examples/example_ofam.py

@@ -42,8 +42,7 @@ def test_ofam_particles(mode):
 
     pset = ParticleSet(fieldset, pclass=ptype[mode], lon=lonstart, lat=latstart, depth=depstart)
 
-    pset.execute(AdvectionRK4, runtime=delta(days=10), dt=delta(minutes=5),
-                 interval=delta(hours=6))
+    pset.execute(AdvectionRK4, runtime=delta(days=10), dt=delta(minutes=5))
 
     assert(abs(pset[0].lon - 173) < 1)
     assert(abs(pset[0].lat - 11) < 1)

parcels/examples/example_peninsula.py

@@ -109,10 +109,9 @@ def __repr__(self):
     dt = delta(minutes=5)
     k_adv = pset.Kernel(method)
     k_p = pset.Kernel(UpdateP)
-    out = pset.ParticleFile(name="MyParticle") if output else None
-    interval = delta(hours=1) if output else -1
+    out = pset.ParticleFile(name="MyParticle", outputdt=delta(hours=1)) if output else None
     print("Peninsula: Advecting %d particles for %s" % (npart, str(time)))
-    pset.execute(k_adv + k_p, endtime=time, dt=dt, output_file=out, interval=interval)
+    pset.execute(k_adv + k_p, runtime=time, dt=dt, output_file=out)
 
     if verbose:
         print("Final particle positions:\n%s" % pset)

parcels/examples/example_radial_rotation.py

@@ -55,12 +55,12 @@ def rotation_example(fieldset, mode='jit', method=AdvectionRK4):
                                  start=(30., 30.),
                                  finish=(30., 50.))  # One particle in centre, one on periphery of Field.
 
-    endtime = delta(hours=17)
+    runtime = delta(hours=17)
     dt = delta(minutes=5)
-    interval = delta(hours=1)
+    outputdt = delta(hours=1)
 
-    pset.execute(method, endtime=endtime, dt=dt, interval=interval,
-                 output_file=pset.ParticleFile(name="RadialParticle"), show_movie=False)
+    pset.execute(method, runtime=runtime, dt=dt, moviedt=None,
+                 output_file=pset.ParticleFile(name="RadialParticle", outputdt=outputdt))
 
     return pset
 

parcels/examples/example_stommel.py

@@ -93,12 +93,12 @@ class MyParticle(ParticleClass):
     # Execute for 30 days, with 1hour timesteps and 12-hourly output
     runtime = delta(days=30)
     dt = delta(hours=1)
-    interval = delta(hours=12)
+    outputdt = delta(hours=12)
     print("Stommel: Advecting %d particles for %s" % (npart, runtime))
     timer.psetinit.stop()
     timer.psetrun = timer.Timer('Pset_run', parent=timer.pset)
-    pset.execute(method + pset.Kernel(UpdateP), runtime=runtime, dt=dt, interval=interval,
-                 output_file=pset.ParticleFile(name="StommelParticle"), show_movie=False)
+    pset.execute(method + pset.Kernel(UpdateP), runtime=runtime, dt=dt,
+                 moviedt=None, output_file=pset.ParticleFile(name="StommelParticle", outputdt=outputdt))
 
     if verbose:
         print("Final particle positions:\n%s" % pset)

parcels/examples/parcels_tutorial.ipynb

@@ -383,8 +383,7 @@
     "pset.execute(AdvectionRK4,                 # the kernel (which defines how particles move)\n",
     "             runtime=timedelta(days=6),    # the total length of the run\n",
     "             dt=timedelta(minutes=5),      # the timestep of the kernel\n",
-    "             interval=timedelta(hours=1),  # the interval at which output is stored\n",
-    "             output_file=pset.ParticleFile(name=\"EddyParticles\"))  # the name of the output file"
+    "             output_file=pset.ParticleFile(name=\"EddyParticles\", outputdt=timedelta(hours=1)))  # the file name and the time step of the outputs"
    ]
   },
   {
@@ -981,7 +980,7 @@
     "editable": true
    },
    "source": [
-    "Now one of the neat features of Parcels is that the particles can be plotted as a movie *during execution*, which is great for debugging. To rerun the particles while plotting them on top of the zonal velocity field (`fieldset.U`), first reinitialise the `ParticleSet` and then re-execute. However, now rather than saving the output to a file, display a movie using the `show_movie` keyword, in this case with the zonal velocity `fieldset.U` as background"
+    "Now one of the neat features of Parcels is that the particles can be plotted as a movie *during execution*, which is great for debugging. To rerun the particles while plotting them on top of the zonal velocity field (`fieldset.U`), first reinitialise the `ParticleSet` and then re-execute. However, now rather than saving the output to a file, display a movie using the `moviedt` display frequency, in this case with the zonal velocity `fieldset.U` as background"
    ]
   },
   {
@@ -1000,8 +999,8 @@
     "# pset.execute(AdvectionRK4,\n",
     "#              runtime=timedelta(days=6),\n",
     "#              dt=timedelta(minutes=5),\n",
-    "#              interval=timedelta(hours=1),\n",
-    "#              show_movie=fieldset.U)"
+    "#              moviedt=timedelta(hours=1),\n",
+    "#              movie_background_field=fieldset.U)"
    ]
   },
   {
@@ -1036,9 +1035,8 @@
    "source": [
     "pset.execute(AdvectionRK4,\n",
     "             dt=-timedelta(minutes=5),      # negative timestep for backward run\n",
-    "             endtime=timedelta(days=0),     # the end time of the run\n",
-    "             interval=-timedelta(hours=1),  # negative interval for backward run\n",
-    "             output_file=pset.ParticleFile(name=\"EddyParticles_Bwd\"))  # the name of the output file"
+    "             runtime=timedelta(days=0),     # the run time\n",
+    "             output_file=pset.ParticleFile(name=\"EddyParticles_Bwd\", outputdt=timedelta(hours=1)))  # the file name and the time step of the outputs"
    ]
   },
   {
@@ -1165,8 +1163,7 @@
     "pset.execute(AdvectionRK4 + k_WestVel,  # simply add kernels using the + operator\n",
     "             runtime=timedelta(days=3),\n",
     "             dt=timedelta(minutes=5),\n",
-    "             interval=timedelta(hours=1),\n",
-    "             output_file=pset.ParticleFile(name=\"EddyParticles_WestVel\"))"
+    "             output_file=pset.ParticleFile(name=\"EddyParticles_WestVel\", outputdt=timedelta(hours=1)))"
    ]
   },
   {
@@ -1385,8 +1382,7 @@
     "pset.execute(AdvectionRK4,\n",
     "             runtime=timedelta(days=10),\n",
     "             dt=timedelta(minutes=5),\n",
-    "             interval=timedelta(hours=6),\n",
-    "             output_file=pset.ParticleFile(name=\"GlobCurrentParticles\"))"
+    "             output_file=pset.ParticleFile(name=\"GlobCurrentParticles\", outputdt=timedelta(hours=6)))"
    ]
   },
   {
@@ -1773,8 +1769,7 @@
     "pset.execute(AdvectionRK4 + k_dist,  # Add kernels using the + operator.\n",
     "             runtime=timedelta(days=6),\n",
     "             dt=timedelta(minutes=5),\n",
-    "             interval=timedelta(hours=1),\n",
-    "             output_file=pset.ParticleFile(name=\"EddyParticles_Dist\"))"
+    "             output_file=pset.ParticleFile(name=\"EddyParticles_Dist\", outputdt=timedelta(hours=1)))"
    ]
   },
   {