sdf-xarray 0.2.6__tar.gz → 0.3.1__tar.gz

{sdf_xarray-0.2.6 → sdf_xarray-0.3.1}/CONTRIBUTING.md

@@ -33,7 +33,7 @@ To run these tools locally, install the optional dependencies and run:
 
 ```bash
 pip install "sdf-xarray[lint]"
-ruff check
+ruff check src tests
 ```
 
 ### Running and Adding Tests

{sdf_xarray-0.2.6 → sdf_xarray-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.2.6
+Version: 0.3.1
 Summary: Provides a backend for xarray to read SDF files as created by the EPOCH plasma PIC code.
 Author-Email: Peter Hill <peter.hill@york.ac.uk>, Joel Adams <joel.adams@york.ac.uk>, Shaun Doherty <shaun.doherty@york.ac.uk>
 License-Expression: BSD-3-Clause
@@ -61,6 +61,9 @@ sdf-xarray provides a backend for [xarray](https://xarray.dev) to read SDF files
 [EPOCH](https://epochpic.github.io) using the [SDF-C](https://github.com/epochpic/SDF_C) library.
 Part of [BEAM](#broad-epoch-analysis-modules-beam) (Broad EPOCH Analysis Modules).
 
+> [!IMPORTANT]
+> To install this package make sure you are using one of the Python versions listed above.
+
 ## Installation
 
 Install from PyPI with:

{sdf_xarray-0.2.6 → sdf_xarray-0.3.1}/README.md

@@ -13,6 +13,9 @@ sdf-xarray provides a backend for [xarray](https://xarray.dev) to read SDF files
 [EPOCH](https://epochpic.github.io) using the [SDF-C](https://github.com/epochpic/SDF_C) library.
 Part of [BEAM](#broad-epoch-analysis-modules-beam) (Broad EPOCH Analysis Modules).
 
+> [!IMPORTANT]
+> To install this package make sure you are using one of the Python versions listed above.
+
 ## Installation
 
 Install from PyPI with:

{sdf_xarray-0.2.6 → sdf_xarray-0.3.1}/docs/conf.py

@@ -8,9 +8,9 @@ from importlib.metadata import version as get_version
 from pathlib import Path
 
 with suppress(ImportError):
-    import matplotlib
+    import matplotlib as mpl
 
-    matplotlib.use("Agg")
+    mpl.use("Agg")
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 

{sdf_xarray-0.2.6 → sdf_xarray-0.3.1}/docs/getting_started.rst

@@ -7,6 +7,15 @@
 Installation
 ------------
 
+.. |python_versions_pypi| image:: https://img.shields.io/pypi/pyversions/sdf-xarray.svg
+   :alt: Supported Python versions
+   :target: https://pypi.org/project/sdf-xarray/
+
+.. important::
+
+   To install this package, ensure that you are using one of the supported Python
+   versions: |python_versions_pypi|
+
 Install sdf-xarray from PyPI with:
 
 .. code-block:: bash
@@ -28,7 +37,7 @@ Usage
 `xarray`. There are several ways to load SDF files:
 
 - To load a single file, use :func:`xarray.open_dataset`.
-- To load multiple files, use :func:`xarray.open_mfdataset` or :func:`sdf_xarray.open_mfdataset`.
+- To load multiple files, use :func:`xarray.open_mfdataset` or :func:`sdf_xarray.open_mfdataset` (Recommended). 
 - To access the raw contents of a single SDF file, use :func:`sdf_xarray.sdf_interface.SDFFile`.
 
 .. note::
@@ -42,21 +51,32 @@ Basic usage:
 .. ipython:: python
 
     import xarray as xr
+    import sdf_xarray as sdfxr
     with xr.open_dataset("tutorial_dataset_1d/0010.sdf") as df:
         print(df["Electric_Field_Ex"])
 
 Multi file loading
 ~~~~~~~~~~~~~~~~~~
 
-To open a whole simulation at once, pass
-``preprocess=sdf_xarray.SDFPreprocess()`` to `xarray.open_mfdataset`:
+To open a whole simulation's files at once use the :func:`sdf_xarray.open_mfdataset` function:
+
+.. ipython:: python
+    
+    sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
+
+You can alternatively open the dataset using the xarray's :func:`xarray.open_mfdataset`
+along with the ``preprocess=sdfxr.SDFPreprocess()``:
 
 .. ipython:: python
 
-    from sdf_xarray import SDFPreprocess
-    xr.open_mfdataset("tutorial_dataset_1d/*.sdf", preprocess=SDFPreprocess())
+    xr.open_mfdataset(
+        "tutorial_dataset_1d/*.sdf",
+        join="outer",
+        compat="no_conflicts",
+        preprocess=sdfxr.SDFPreprocess()
+    )
 
-`SDFPreprocess` checks that all the files are from the same simulation, and
+:class:`sdf_xarray.SDFPreprocess` checks that all the files are from the same simulation, and
 ensures there's a ``time`` dimension so the files are correctly concatenated.
 
 If your simulation has multiple ``output`` blocks so that not all variables are
@@ -64,12 +84,11 @@ output at every time step, then those variables will have ``NaN`` values at the
 corresponding time points.
 
 Alternatively, we can create a separate time dimensions for each ``output``
-block using `sdf_xarray.open_mfdataset` with ``separate_times=True``:
+block using :func:`sdf_xarray.open_mfdataset` with ``separate_times=True``:
 
 .. ipython:: python
 
-    from sdf_xarray import open_mfdataset
-    open_mfdataset("tutorial_dataset_1d/*.sdf", separate_times=True)
+    sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf", separate_times=True)
 
 This is better for memory consumption, at the cost of perhaps slightly less
 friendly comparisons between variables on different time coordinates.

{sdf_xarray-0.2.6 → sdf_xarray-0.3.1}/docs/key_functionality.rst

@@ -6,17 +6,17 @@ Key Functionality
 
 .. ipython:: python
 
+   import xarray as xr
+   import sdf_xarray as sdfxr
    import matplotlib.pyplot as plt
    from IPython.display import display, HTML
-   import xarray as xr
-   from sdf_xarray import SDFFile, SDFPreprocess
 
 Loading SDF Files
 -----------------
 There are several ways to load SDF files:
 
 - To load a single file, use :func:`xarray.open_dataset`.
-- To load multiple files, use :func:`xarray.open_mfdataset` or :func:`sdf_xarray.open_mfdataset`.
+- To load multiple files, use :func:`sdf_xarray.open_mfdataset` or :func:`xarray.open_mfdataset`.
 - To access the raw contents of a single SDF file, use :func:`sdf_xarray.sdf_interface.SDFFile`.
 
 .. note::
@@ -34,28 +34,48 @@ Loading a Single Raw SDF File
 
 .. ipython:: python
 
-   with SDFFile("tutorial_dataset_1d/0010.sdf") as sdf_file:
+   with sdfxr.SDFFile("tutorial_dataset_1d/0010.sdf") as sdf_file:
       print(sdf_file.variables)
 
 Loading all SDF Files for a Simulation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When loading in all the files we have do some processing of the data
+Multiple files can be loaded using one of two methods. The first of which
+is by using the :func:`sdf_xarray.open_mfdataset`
+
+.. ipython:: python
+
+   sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
+
+Alternatively files can be loaded using :func:`xarray.open_mfdataset`
+however when loading in all the files we have do some processing of the data
 so that we can correctly align it along the time dimension; This is
 done via the ``preprocess`` parameter.
 
 .. ipython:: python
 
-   xr.open_mfdataset("tutorial_dataset_1d/*.sdf", preprocess=SDFPreprocess())
+   xr.open_mfdataset(
+      "tutorial_dataset_1d/*.sdf",
+      join="outer",
+      compat="no_conflicts",
+      preprocess=sdfxr.SDFPreprocess())
 
 Reading particle data
 ~~~~~~~~~~~~~~~~~~~~~
 
 .. warning::
-   It is **not recommended** to use :func:`xarray.open_mfdataset` or :func:`open_mfdataset` to load particle data from multiple SDF outputs. The number of particles often varies between outputs, which can lead to inconsistent array shapes that these functions cannot handle. Instead, consider loading each file individually and then concatenating them manually.
+   It is **not recommended** to use :func:`xarray.open_mfdataset` or
+   :func:`sdf_xarray.open_mfdataset` to load particle data from multiple
+   SDF outputs. The number of particles often varies between outputs,
+   which can lead to inconsistent array shapes that these functions
+   cannot handle. Instead, consider loading each file individually and
+   then concatenating them manually.
 
 .. note::
-   When loading multiple probes from a single SDF file, you **must** use the `probe_names` parameter to assign a unique name to each. For example, use `probe_names=["Front_Electron_Probe", "Back_Electron_Probe"]`. Failing to do so will result in dimension name conflicts.
+   When loading multiple probes from a single SDF file, you **must** use the
+   ``probe_names`` parameter to assign a unique name to each. For example,
+   use ``probe_names=["Front_Electron_Probe", "Back_Electron_Probe"]``.
+   Failing to do so will result in dimension name conflicts.
 
 By default, particle data isn't kept as it takes up a lot of space.
 Pass ``keep_particles=True`` as a keyword argument to
@@ -85,7 +105,7 @@ looking at when you call ``.values``
 
 .. ipython:: python
 
-   ds = xr.open_mfdataset("tutorial_dataset_1d/*.sdf", preprocess=SDFPreprocess())
+   ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 
    ds["Electric_Field_Ex"]
 

sdf_xarray-0.3.1/docs/tutorial_dataset_2d/input.deck

@@ -0,0 +1,65 @@
+begin:control
+  nx = 64
+  ny = 64
+
+  # Final time of simulation
+  t_end = 5 * femto
+
+  # Size of domain
+  x_min = 0
+  x_max = 6 * micron
+
+  y_min = 0
+  y_max = 6 * micron
+
+  stdout_frequency = 1
+  nparticles = nx * ny * 50
+end:control
+
+begin:constant
+    n_elec = 1000
+    L_target_x = 2 * micron
+    L_target_y = 4 * micron
+
+    x_center = (x_min + x_max) / 2
+    y_center = (y_min + y_max) / 2
+
+    density_profile = if( (abs(x - x_center) lt L_target_x/2), if( (abs(y - y_center) lt L_target_y/2), 1, 0), 0)
+end:constant
+
+begin:boundaries
+  bc_x_min = periodic
+  bc_x_max = periodic
+  bc_y_min = periodic
+  bc_y_max = periodic
+end:boundaries
+
+
+begin:species
+  name = Electron
+  frac = 0.5
+  number_density = n_elec * density_profile
+  identify:electron
+end:species
+
+begin:species
+  name = Ion
+  frac = 0.5
+  number_density = n_elec * density_profile
+  identify:proton
+end:species
+
+begin:output_global
+    force_last_to_be_restartable = F
+end:output_global
+
+begin:output
+  name = normal
+
+  dt_snapshot = 1 * femto
+
+  grid = always
+  number_density = always + species
+
+end:output
+

sdf_xarray-0.3.1/docs/unit_conversion.rst

@@ -0,0 +1,228 @@
+.. _sec-unit-conversion:
+
+===============
+Unit Conversion
+===============
+
+The ``sdf-xarray`` package automatically extracts the units for each
+coordinate/variable/constant from an SDF file and stores them as an :class:`xarray.Dataset`
+attribute called ``"units"``. Sometimes we want to convert our data from one format to
+another, e.g. converting the grid coordinates from meters to microns, time from seconds 
+to femto-seconds or particle energy from Joules to electron-volts.
+
+.. ipython:: python
+
+    from sdf_xarray import open_mfdataset
+    import matplotlib.pyplot as plt
+    plt.rcParams.update({
+        "axes.labelsize": 16,
+        "xtick.labelsize": 14,
+        "ytick.labelsize": 14,
+        "axes.titlesize": 16
+    })
+
+
+=====================
+Rescaling Coordinates
+=====================
+
+For simple scaling and unit relabeling of coordinates (e.g., converting meters to microns),
+the most straightforward approach is to use the ``rescale_coords()`` method  
+via the custom ``xarray.Dataset.epoch`` dataset accessor.  
+
+This method scales the coordinate values by a given multiplier and updates the ``"units"``
+attribute in one step.
+
+Rescaling Grid Coordinates
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We can use the ``xarray.Dataset.epoch.rescale_coords()`` method to convert X, Y, and Z
+coordinates from meters (m) to microns (µm) by applying a multiplier of ``1e6``.
+
+.. ipython:: python
+
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(16, 6))
+
+    with open_mfdataset("tutorial_dataset_2d/*.sdf") as ds:
+        ds_in_microns = ds.epoch.rescale_coords(
+            multiplier=1e6, 
+            unit_label="µm", 
+            coord_names=["X_Grid_mid", "Y_Grid_mid"]
+        )
+        derived_number_density = ds["Derived_Number_Density_Electron"].isel(time=0).compute()
+        derived_number_density_microns = ds_in_microns["Derived_Number_Density_Electron"].isel(time=0).compute()
+
+    derived_number_density.plot(ax=ax1, x="X_Grid_mid", y="Y_Grid_mid")
+    ax1.set_title("Original X Coordinate (m)")
+
+    derived_number_density_microns.plot(ax=ax2, x="X_Grid_mid", y="Y_Grid_mid")
+    ax2.set_title("Rescaled X Coordinate (µm)")
+
+    @savefig coordinate_conversion.png width=9in
+    fig.tight_layout()
+
+
+Rescaling Time Coordinate
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We can also use the ``xarray.Dataset.epoch.rescale_coords()`` method to convert the time
+coordinate from seconds (s) to femto-seconds (fs) by applying a multiplier of ``1e15``.
+
+.. ipython:: python
+    
+    with open_mfdataset("tutorial_dataset_2d/*.sdf") as ds:
+        ds_time_in_femto = ds.epoch.rescale_coords(
+            multiplier=1e15, 
+            unit_label="fs", 
+            coord_names="time"
+        )
+
+        print(f"[Original] units: {ds['time'].attrs['units']}, values: {ds['time'].values}")
+        print(f"[Rescaled] units: {ds_time_in_femto['time'].attrs['units']}, values: {ds_time_in_femto['time'].values}")
+
+
+================================
+Unit Conversion with pint-xarray
+================================
+
+While this is sufficient for most use cases, we can enhance this functionality
+using the `pint <https://pint.readthedocs.io/en/stable/getting/index.html>`_ library.
+Pint allows us to specify the units of a given array and convert them
+to another, which is incredibly handy. We can take this a step further,
+however, and utilize the `pint-xarray
+<https://pint-xarray.readthedocs.io/en/latest/>`_ library. This library
+allows us to infer units directly from an `xarray.Dataset.attrs` while
+retaining all the information about the `xarray.Dataset`. This works
+very similarly to taking a NumPy array and multiplying it by a constant or
+another array, which returns a new array; however, this library will also
+retain the unit logic (specifically the ``"units"`` information).
+
+.. note::
+    Unit conversion is not supported on coordinates in ``pint-xarray`` which is due to an
+    underlying issue with how ``xarray`` implements indexes.
+
+Installation
+~~~~~~~~~~~~
+
+To install the pint libraries you can simply run the following optional
+dependency pip command which will install both the ``pint`` and ``pint-xarray``
+libraries. You can install these optional dependencies via pip:
+
+.. code:: console
+
+    $ pip install "sdf_xarray[pint]"
+
+.. note::
+    Once you install ``pint-xarray`` it is automatically picked up and loaded
+    by the code so you should have access to the ``xarray.Dataset.pint`` accessor.
+
+Quantifying Arrays
+~~~~~~~~~~~~~~~~~~
+
+When using ``pint-xarray``, the library attempts to infer units from the
+``"units"`` attribute on each `xarray.DataArray`. Alternatively, you can
+also specify the units yourself by passing a string into the 
+``xarray.Dataset.DataArray.pint.quantify()`` function call. Once the type is inferred
+the original `xarray.DataArray` will be converted to a `pint.Quantity`
+and the ``"units"`` attribute will
+be removed.
+
+In the following example we will extract the time-resolved total particle
+energy of electrons which is measured in Joules and convert it to electron
+volts.
+
+.. ipython:: python
+
+    with open_mfdataset("tutorial_dataset_1d/*.sdf") as ds:
+        total_particle_energy = ds["Total_Particle_Energy_Electron"]
+
+    total_particle_energy
+
+    total_particle_energy = ds["Total_Particle_Energy_Electron"].pint.quantify()
+
+    total_particle_energy
+
+
+Now that this dataset has been converted a `pint.Quantity`, we can check
+it's units and dimensionality
+
+.. ipython:: python
+
+    total_particle_energy.pint.units
+    total_particle_energy.pint.dimensionality
+
+
+Converting Units
+~~~~~~~~~~~~~~~~
+
+We can now convert it to electron volts utilising the `pint.Quantity.to`
+function
+
+.. ipython:: python
+
+    total_particle_energy_ev = total_particle_energy.pint.to("eV")
+
+Unit Propagation
+~~~~~~~~~~~~~~~~
+
+Suppose instead of converting to ``"eV"``, we want to convert to ``"W"``
+(watts). To do this, we divide the total particle energy by time. However,
+since coordinates in `xarray.Dataset` cannot be directly converted to
+`pint.Quantity`, we must first extract the coordinate values manually
+and create a new Pint quantity for time.
+
+Once both arrays are quantified, Pint will automatically handle the unit
+propagation when we perform arithmetic operations like division.
+
+.. note::
+    Pint does not automatically simplify ``"J/s"`` to ``"W"``, so we use
+    `pint.Quantity.to` to convert the unit string. Since these units are
+    the same it will not change the underlying data, only the units. This is
+    only a small formatting choice and is not required.
+
+.. ipython:: python
+
+    import pint
+    time_values = total_particle_energy.coords["time"].data
+    time = pint.Quantity(time_values, "s")
+    total_particle_energy_w = total_particle_energy / time
+    total_particle_energy_w.pint.units
+    total_particle_energy_w = total_particle_energy_w.pint.to("W")
+    total_particle_energy_w.pint.units
+
+Dequantifying and Restoring Units
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+    If this function is not called prior to plotting then the ``units`` will be
+    inferred from the `pint.Quantity` array which will return the long
+    name of the units. i.e. instead of returning ``"eV"`` it will return
+    ``"electron_volt"``.
+
+The ``xarray.Dataset.DataArray.pint.dequantify`` function converts the data from
+`pint.Quantity` back to the original `xarray.DataArray` and adds
+the ``"units"`` attribute back in. It also has an optional ``format`` parameter
+that allows you to specify the formatting type of ``"units"`` attribute. We
+have used the ``format="~P"`` option as it shortens the unit to its
+"short pretty" format (``"eV"``). For more options, see the `Pint formatting
+documentation <https://pint.readthedocs.io/en/stable/user/formatting.html>`_.
+
+.. ipython:: python
+
+    total_particle_energy_ev = total_particle_energy_ev.pint.dequantify(format="~P")
+    total_particle_energy_w = total_particle_energy_w.pint.dequantify(format="~P")
+    total_particle_energy_ev
+
+To confirm the conversion has worked correctly, we can plot the original and
+converted `xarray.Dataset` side by side:
+
+.. ipython:: python
+    
+    fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(16,8))
+    ds["Total_Particle_Energy_Electron"].plot(ax=ax1)
+    total_particle_energy_ev.plot(ax=ax2)
+    total_particle_energy_w.plot(ax=ax3)
+    ax4.set_visible(False)
+    fig.suptitle("Comparison of conversion from Joules to electron volts and watts", fontsize="18")
+    @savefig unit_conversion.png width=9in
+    fig.tight_layout()

{sdf_xarray-0.2.6 → sdf_xarray-0.3.1}/src/sdf_xarray/__init__.py

@@ -1,13 +1,17 @@
+import contextlib
 import os
 import re
 from collections import Counter, defaultdict
 from collections.abc import Callable, Iterable
+from importlib.metadata import version
 from itertools import product
+from os import PathLike as os_PathLike
 from pathlib import Path
 from typing import ClassVar
 
 import numpy as np
 import xarray as xr
+from packaging.version import Version
 from xarray.backends import AbstractDataStore, BackendArray, BackendEntrypoint
 from xarray.backends.file_manager import CachingFileManager
 from xarray.backends.locks import ensure_lock
@@ -15,12 +19,24 @@ from xarray.core import indexing
 from xarray.core.utils import close_on_error, try_read_magic_number_from_path
 from xarray.core.variable import Variable
 
-# NOTE: Do not delete this line, otherwise the "epoch" accessor will not be
-# imported when the user imports sdf_xarray
+# NOTE: Do not delete these lines, otherwise the "epoch" dataset and dataarray
+# accessors will not be imported when the user imports sdf_xarray
+import sdf_xarray.dataset_accessor
 import sdf_xarray.plotting  # noqa: F401
 
+# NOTE: This attempts to initialise with the "pint" accessor if the user
+# has installed the package
+with contextlib.suppress(ImportError):
+    import pint_xarray  # noqa: F401
+
 from .sdf_interface import Constant, SDFFile  # type: ignore  # noqa: PGH003
 
+# TODO Remove this once the new kwarg options are fully implemented
+if Version(version("xarray")) >= Version("2025.8.0"):
+    xr.set_options(use_new_combine_kwarg_defaults=True)
+
+PathLike = str | os_PathLike
+
 
 def _rename_with_underscore(name: str) -> str:
     """A lot of the variable names have spaces, forward slashes and dashes in them, which
@@ -51,14 +67,32 @@ def _process_latex_name(variable_name: str) -> str:
     return variable_name
 
 
+def _resolve_glob(path_glob: PathLike | Iterable[PathLike]):
+    """
+    Normalise input path_glob into a sorted list of absolute, resolved Path objects.
+    """
+
+    try:
+        p = Path(path_glob)
+        paths = list(p.parent.glob(p.name)) if p.name == "*.sdf" else list(p)
+    except TypeError:
+        paths = list({Path(p) for p in path_glob})
+
+    paths = sorted(p.resolve() for p in paths)
+    if not paths:
+        raise FileNotFoundError(f"No files matched pattern or input: {path_glob!r}")
+    return paths
+
+
 def combine_datasets(path_glob: Iterable | str, **kwargs) -> xr.Dataset:
     """Combine all datasets using a single time dimension"""
 
     return xr.open_mfdataset(
         path_glob,
-        data_vars="minimal",
-        coords="minimal",
-        compat="override",
+        data_vars="all",
+        coords="different",
+        compat="no_conflicts",
+        join="outer",
         preprocess=SDFPreprocess(),
         **kwargs,
     )
@@ -103,19 +137,13 @@ def open_mfdataset(
         List of EPOCH probe names
     """
 
-    # TODO: This is not very robust, look at how xarray.open_mfdataset does it
-    if isinstance(path_glob, str):
-        path_glob = Path().glob(path_glob)
-
-    # Coerce to list because we might need to use the sequence multiple times
-    path_glob = sorted(list(path_glob))  # noqa: C414
-
+    path_glob = _resolve_glob(path_glob)
     if not separate_times:
         return combine_datasets(
             path_glob, keep_particles=keep_particles, probe_names=probe_names
         )
 
-    time_dims, var_times_map = make_time_dims(path_glob)
+    _, var_times_map = make_time_dims(path_glob)
     all_dfs = [
         xr.open_dataset(f, keep_particles=keep_particles, probe_names=probe_names)
         for f in path_glob
@@ -136,7 +164,12 @@ def open_mfdataset(
                 )
 
     return xr.combine_by_coords(
-        all_dfs, data_vars="minimal", combine_attrs="drop_conflicts"
+        all_dfs,
+        data_vars="all",
+        coords="different",
+        combine_attrs="drop_conflicts",
+        join="outer",
+        compat="no_conflicts",
     )
 
 

{sdf_xarray-0.2.6 → sdf_xarray-0.3.1}/src/sdf_xarray/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.6'
-__version_tuple__ = version_tuple = (0, 2, 6)
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
 
-__commit_id__ = commit_id = 'g67411803b'
+__commit_id__ = commit_id = 'gce5426d4a'