Skip to content

Release Notes§

Version 2.1.4§

Released 16-07-2026

Bug Fixes§

  • 47b5c34: Fix bug that raised an exception when a record was empty

Refactoring§

  • ff743e9: Add argument compat = 'no_conflicts' explicitly to xarray.merge calls due to futurewarning

    According to an xarray FutureWarning, a future version of xarray will use compat = 'override' as the default for xarray.merge.

Version 2.1.3§

Released 16-07-2026

Bug Fixes§

  • 79edd1b: Several changes to make sure that ozzy.open_series and ozzy.open_compare work with the openpmd backend

  • 8df975a: Workaround for openpmd-viewer issue #443

  • 490f2d9: Foresee particle quantities that may not have the macroweighted attribute

  • f003e3c: Bug for species with id information

Refactoring§

  • 7d1d6af: Make look-up of simulation files more readable

    The find_quants function in backend_interface uses a regex pattern that should be defined at the top of each backend module to find groups of files belonging to a certain PIC code. The regex patterns for each backend have been modified such that each capturing group in the pattern is now named: "name", "number", "file_ending". This makes the code in find_quants more readable and less prone to bugs.

  • 0496273: Remove error handling for a missing tol-colors package, since it is now available on conda-forge

    The package tol-colors is a dependency of ozzy, but it used to be available only on PyPI. This means that it couldn't be specified as a requirement for the ozzy distribution on conda-forge. This is now resolved.

Version 2.1.2§

Released 14-07-2026

Bug Fixes§

  • 7487756: Fix bug in part of backend that handles species data

Refactoring§

  • 0e2447a: Update new_dataset function such that it's compatible with latest changes to xarray.dataset()

    In version v2026.04.0, the Dataset constructor stopped accepting a Dataset as the data_vars argument.

Version 2.1.1§

Released 24-06-2026

Bug Fixes§

  • 3783f30: Add error handling when some packages are missing

    A warning is now printed when one of tol_colors, hvplot or IPython packages are not installed. Since (tol_colors is not yet available on conda-forge)[https://github.com/conda-forge/staged-recipes/pull/29265], it is not installed by default in ozzy's conda-forge distribution (i.e. when ozzy is installed via conda or mamba). The dependencies hvplot and IPython are not installed by default in ozzy's PyPI distribution (i.e. via pip).

    Note for developers: When installing ozzy via poetry, hvplot and IPython are also not installed by default. These dependencies are part of the optional group "interactive". To include them, run poetry install -E interactive instead of the basic poetry install.

Version 2.1.0§

Released 23-06-2026

Bug Fixes§

  • 6d88b1a: Add data_vars argument explicitly to xarray open_dataset and open_mfdataset functions

    Received FutureWarning from xarray regarding the data_vars argument.

  • 896223b: Make upack_attr function accept more types of hdf5 attributes

Documentation§

  • 08a4315: Update acknowledgment and license information to reflect the fact that paul tol's color schemes are not bundled directly with ozzy anymore

  • dd47d78: Add openpmd examples to "reading files" section of user guide

  • 61e5207: Add openpmd examples to open and open_series docstrings

  • 5391613: Update some details in user guide

  • 4b98ad1: Include link to xarray dataset documentation

  • 2f199d3: Include link to xarray dataset documentation

  • 4df715a: Update with information about openpmd backend

  • 2224d8a: Correct docstring for files argument of ozzy.open_series

Features§

  • b973357: Make ozzy.open_compare compatible with openpmd files

    The open_compare function assumes that each output quantity from a simulation code is associated with a set of files. openPMD files usually contain multiple quantities ("records") in a single set of files. This implementation tries to get around this, although it's probably not the best solution.

  • ec070da: Implement openpmd backend

    ozzy should now be able to read openPMD files in HDF5 format.

  • db425d0: Add quantity definitions for electric field and charge density

  • 4b0d0fc: Add very basic support for physical unit conversion

    Start a submodule to handle physical units with pint. At the moment, this feature is only used to parse the unit metadata in OpenPMD files. It might be interesting to extend unit support to other parts of ozzy.

  • 4262909: Add helper function to find items in hdf5 files

Refactoring§

Version 2.0.5§

Released 22-01-2026

Bug Fixes§

  • ba1e991: Fix some bugs related to the bins argument in the hist and hist_proj functions of ozzy.plot and add binrange and binwidth arguments

Version 2.0.4§

Released 11-11-2025

Bug Fixes§

  • 1ddd4af: Badly formulated if-statement in emittance functions

Version 2.0.3§

Released 11-11-2025

Bug Fixes§

  • 577afa7: Improve handling of variable labels in ´get_emittance´

Documentation§

  • 176bc05: Formatting issue in one of documentation pages

  • 928cb92: Add icon to mark external links, and open these links in new tab by default

  • 6e285d2: Add information about backend-specific arguments in the ozzy open functions

Refactoring§

  • 3131e16: Change how emittance is handled for axisymmetric geometry in get_slice_emittance, update docstring

  • afb8ca4: Change how emittance is handled for axisymmetric in get_emittance, update docstring

Version 2.0.2§

Released 06-11-2025

Bug Fixes§

  • 1e3d55d: Bug that was preventing lcode files like emaxf.dat to be read

Documentation§

  • c966cd4: Correct typo in docstring of lcode_backends.convert_q

Refactoring§

  • 70da7e3: Add argument to xarray.concat and xarray.merge calls due to xarray futurewarning

    Add the argument join="outer" explicitly when call xarray.concat to avoid getting an error in the future, when xarray changes the default value of join from "outer" to "exact". See warning: 

    FutureWarning: In a future version of xarray the default value for join will change from join='outer' to join='exact'.

Version 2.0.1§

Released 05-09-2025

Bug Fixes§

  • bcd0bf6: Bug in helper function ozzy.utils.prep_file_input was preventing ozzy from finding files to open, raising filenotfounderror

Version 2.0.0§

Released 29-08-2025

Bug Fixes§

  • 6404186: Fix bug in bin_into_grid (and get_phase_space, which depends on it) for axisymmetric data

    This bug was possibly producing incorrect results when bin_into_grid or get_phase_space were called on an axisymmetric particle dataset, and where all of these conditions were met:

    • r_var was provided as an argument (other than None)

    • for get_phase_space, the argument axisym was set to True

    • the radial variable r_var was not part of either the axes_ds (for bin_into_grid) or vars (for get_phase_space) argument

Documentation§

  • 4ff3d2e: Restructure the "data object methods" section of the code reference and other small updates

  • 6cec2a7: Improve example of convert_q method

Features§

  • 7855a10: Add function to get the weighted median of some variable in a particle dataset

    Particle data from PIC codes is often weighted (often in the form of an individual macroparticle "charge"), which means that the calculation of a median value is not as straightforward as for other discrete and unweighted data. This method ensures that a median value can be calculated correctly, taking the macroparticle weights into account.

    This function can be called as a particle method, e.g. part_ds.ozzy.get_weighted_mean, where part_ds is an ozzy particle Dataset object (i.e., with attribute pic_data_type = "part").

Refactoring§

  • cb5973f: Make all arguments for variable names consistent

    Some functions have input arguments where the name of a certain variable can be specificied. The naming for this type of argument has been made consistent across the code. For example, the arguments time_dim or tvar have been renamed to t_var.

    Breaking change: TypeError may be raised when some functions are called using the old argument names

    Please make sure to update your scripts with the new arguments (e.g. w_var instead of wvar).

  • f668c5d: Add hidden method _contains_datavars to ozzy dataset objects to simplify input validation in other parts of the code

    Given a list of variable names, this method checks whether each variable exists in the Dataset as a data variable and raises a KeyError if it doesn't. This is useful when implementing new functions that require some data variables as input (for example get_emittance or get_energy_spectrum).

Version 1.3.4§

Released 26-08-2025

Bug Fixes§

  • d3403f1: Turn off savefig.transparent in default rcparams when using the movie function

    Each frame was previously being saved with a transparent background, which meant that the movies produced with ozzy.plot.movie were superimposing all of the frames.

Version 1.3.3§

Released 29-07-2025

Bug Fixes§

  • 3675499: Correct a bug in get_energy_spectrum

Version 1.3.2§

Released 29-07-2025

Bug Fixes§

  • 6effaee: Correct a couple of bugs in the calculation of the normalized emittance

Version 1.3.1§

Released 23-07-2025

Bug Fixes§

  • 8a02447: Error when trying to save the output of get_slice_emittance or get_energy_spectrum

    These particle methods use a special binning and grouping function (flox.xarray.xarray_reduce) for increased efficiency. However, this function creates a coordinate for the binned variable with the data type pandas.Interval, which makes it impossible to save the data with ds.ozzy.save. The binned coordinate is now converted into a normal numpy array, using the midpoints of each interval element.

Documentation§

  • 3242468: Add docstring to new utility function convert_interval_to_mid

Refactoring§

  • 4fc223d: Add timing information to several particle methods

    The particle methods get_phase_space, get_emittance, get_slice_emittance, get_energy_spectrum now print the time taken to complete.

  • ef3420f: Add timing information to several particle methods

    The particle methods get_phase_space, get_emittance, get_slice_emittance, get_energy_spectrum now print the time taken to complete.

Version 1.3.0§

Released 16-07-2025

Bug Fixes§

  • 2f8993b: Use absolute value of weight variable for ozzy.plot.hist and ozzy.plot.hist_proj

    The weighting variable in data objects is often a charge (e.g. do['q']), which means that it has a charge sign. This would show up in histograms as negative counts.

  • ade7881: Accept filenames for beamfiles (and plasma and fields files) with more flexible patterns

    Now accepts the regex filename pattern "beamfile\w*\.bin" instead of "beamfile.bin". The same applies to plasma.bin and fields.bin files.

    Before:

    ✅ beamfile.bin

    ❌ beamfile_changed.bin

    ❌ beamfile2.bin

    Now:

    ✅ beamfile.bin

    ✅ beamfile_changed.bin

    ✅ beamfile2.bin

  • cdf5a87: Bug in bin_into_grid where the time dimension was hardcoded as "t"

Documentation§

Features§

  • cfa8949: Add energy spectrum calculation

    Add get_energy_spectrum method to particle datasets, which calculates energy histograms with proper binning and attribute handling. See documentation for examples of usage.

  • a542991: Add method to get the slice emittance get_slice_emittance

    Includes some changes to the get_emittance method and its documentation. It is now possible to choose between the normalized and geometric emittance, for example.

Refactoring§

  • 10eef35: The output of get_slice_emittance now adopts any label and units attributes provided with axis_ds

  • 4d876ca: Add utility function to insert string at a given index

  • fb3cc12: Add time_dim and weight_var arguments in get_phase_space

    The function get_phase_space calls bin_into_grid, which was setting some defaults for the time_dim and weight_var arguments. This is not the case anymore.

  • f0e45a7: Add time_dim and weight_var arguments in get_phase_space

    The function get_phase_space calls bin_into_grid, which was setting some defaults for the time_dim and weight_var arguments. This is not the case anymore.

Version 1.2.10§

Released 23-06-2025

Bug Fixes§

  • 3953907: Use absolute value of weight variable for ozzy.plot.hist and ozzy.plot.hist_proj

    The weighting variable in data objects is often a charge (e.g. do['q']), which means that it has a charge sign. This would show up in histograms as negative counts.

Documentation§

  • 0e9829a: Update changelog manually

Version 1.2.9§

Released 20-06-2025

Bug Fixes§

  • f25affb: Accept filenames for beamfiles (and plasma and fields files) with more flexible patterns

    Now accepts the regex filename pattern "beamfile\w*\.bin" instead of "beamfile.bin". The same applies to plasma.bin and fields.bin files.

    Before:

    ✅ beamfile.bin

    ❌ beamfile_changed.bin

    ❌ beamfile2.bin

    Now:

    ✅ beamfile.bin

    ✅ beamfile_changed.bin

    ✅ beamfile2.bin

Version 1.2.8§

Released 20-06-2025

Bug Fixes§

  • 4cc2da9: Bug in bin_into_grid where the time dimension was hardcoded as "t"

Version 1.2.7§

Released 23-05-2025

Bug Fixes§

  • 741f0af: Ability to use paul tol's reversed colormaps by appending '_r'

  • d5bcdcb: Assign dtype to concatenated data before chunking

Version 1.2.6§

Released 08-05-2025

Bug Fixes§

  • d5d84f2: Make sure that raw files containing no particles at all can still be assigned times and concatenated

  • 824cfed: Bug for raw files with no particle tag data

Version 1.2.5§

Released 30-04-2025

Bug Fixes§

  • 08ad9a6: Fix bug that was causing an error when hist or hist_proj were called with weight_var = none

Version 1.2.4§

Released 30-04-2025

Bug Fixes§

  • 89eac7e: Change algorithm so that spatially averaged (savg) grid data can be read

Refactoring§

  • 83b988e: Tweaked some parameters in local_maxima_and_zero_crossings to improve peak and zero finding

  • 0ff220f: Better formatting of progress bar in vphi_from_fit

  • a899159: Minor improvements to the vphi_from_fit function

Version 1.2.3§

Released 14-04-2025

Bug Fixes§

  • 92a2ed0: Bug in ozzy.plot.hist and ozzy.plot.hist_proj for weighted data

Version 1.2.2§

Released 09-04-2025

Bug Fixes§

  • 1319ddf: Typo was preventing ozzy.statistics from being imported

Version 1.2.1§

Released 09-04-2025

Bug Fixes§

  • 57daddd: Bug in local_maxima_and_zero_crossings

Documentation§

  • f4700b4: Correct typos in docstring for ozzy.fields.local_maxima_and_zero_crossings

Version 1.2.0§

Released 03-04-2025

Features§

  • 454aeee: Add function to find local field maxima and zero crossings

Version 1.1.2§

Released 17-02-2025

Bug Fixes§

  • 46d59fc: Trigger new release to publish python-3.13-compatible update to pypi

Version 1.1.1§

Released 17-02-2025

Bug Fixes§

  • 6066a3f: Update package dependencies so that package works with python 3.13

Version 1.1.0§

Released 17-02-2025

Documentation§

  • a156af7: Instruct users to use the function ozzy.utils.axis_from_extent to create the axes dataset required for bin_into_grid

Features§

  • 7c39207: Add functions to plot distributions of particle data

    Add ozzy.plot.hist and ozzy.plot.hist_proj to easily plot density distributions (histograms) of particle data, taking advantage of the seaborn functions seaborn.histplot and seaborn.jointplot.

    Previously it would have been necessary to bin the data first, and then plot, e.g.: 

    import ozzy as oz
import ozzy.plot as oplt
# A particle data Dataset
ds = oz.Dataset(..., pic_data_type="part")
ds_ps = ds.ozzy.get_phase_space(["p2", "x2"])
ds_ps["rho"].plot()
    While now the following code is enough: 
    import ozzy as oz
import ozzy.plot as oplt
ds = oz.Dataset(..., pic_data_type='part')
oplt.hist(ds, x="x2", y="p2")

Refactoring§

  • 703dfd3: Change ozzy.plot defaults to display a plot grid

Version 1.0.9§

Released 28-01-2025

Bug Fixes§

  • a3cfe10: One argument of set_attr_if_exists was missing its default value, which was throwing an error e.g. when ds.ozzy.save was called

Version 1.0.8§

Released 24-01-2025

Bug Fixes§

  • 83329ef: Fft method was throwing error due to data being a chunked dask array

Documentation§

  • 85a5f71: Small formatting corrections

Version 1.0.7§

Released 26-11-2024

Bug Fixes§

  • 48d0b14: Fix bug that would throw error when using open_compare with multiple backends and with backend-specific keyword arguments

Documentation§

  • 25b11d8: Disable instant loading since this causes the feedback widget to only show after reloading the page

  • e2c93ce: Update installation instructions (now available on conda-forge) and update package dependencies (especially makedocs-material)

Version 1.0.6§

Released 13-11-2024

Bug Fixes§

  • 65c7549: Expression with double quotes inside double quotes was throwing an error for python 3.10

Version 1.0.5§

Released 13-11-2024

Bug Fixes§

  • 2c5fa8e: Remove obsolete argument for backend.parse_data that was being called from ozzy.open_compare and raising an error

Documentation§

  • 60afa7d: Fix some broken links after update

Version 1.0.4§

Released 12-11-2024

Bug Fixes§

  • 5cd488c: Fix error thrown by bin_into_grid when called on a data object that didn't contain a 't' coordinate

  • 776a1a2: Fix missing-argument error when trying to read beamfile.bin files

Documentation§

  • b43f5dc: Update documentation

  • 6c726a5: Update "installation" and "getting started" page

  • 1bf9a95: Change heading formatting of changelog template

Refactoring§

  • 825b7ab: Change how backend-specific arguments are passed from the open functions to each backend (easier to extend)

Version 1.0.3§

Released 04-11-2024

Documentation§

  • 1c50582: Correct changelog template

Version 1.0.2§

Released 04-11-2024

Documentation§

  • 2d1afe0: Update installation instructions

Version 1.0.1§

Released 04-11-2024

Bug Fixes§

  • 0e0f1f2: Fix attribute assignment in bin_into_grid and reorder dimensions after binning (for chunking and performance)

  • 9674d63: Fix bug where open_compare was printing out "reading files" even when it had found no files

Documentation§

  • 28e05c2: Change template for automatic changelog generation

  • d91795b: Add plot_func argument to movie docstring

  • 2a97bb6: Add release notes to website, create custom changelog template

Features§

  • 10abc79: Publish package on pypi with as ozzy-pic

  • 0d2020a: Add function to get beam emittance

  • 1ac93ae: Add function to create an interactive animation using hvplot

  • 3540a8e: Make movie more customisable by having a function argument that can edit the plot at each frame

  • dd58a21: Add co-moving variables such as x1_box to particle data as well

Performance Improvements§

  • e67f696: Reorder and rechunk dimensions of data after binning in bin_into_grid

Refactoring§

  • 0e98bbb: Harmonize the metadata of lcode particle data (momentum) to standard names and units, update docs and tests

    The third momentum component in LCODE particle data corresponds to either \(p_z\) in Cartesian geometry or the angular momentum \(L\) in axisymmetric/cylindrical geometry. This is now taken into account via the boolean parameter axisym (True by default). In cylindrical geometry the third momentum component is renamed and a new 'p3' variable is added to the dataset, corresponding to \(p_\theta = L / r\).

    In addition, all momenta in LCODE particle data are normalised to \(m_e \ c\). The units are now converted to \(m_\mathrm{sp} \ c\), using the charge-to-mass ratio in the data and the new argument abs_q (absolute value of the normalised bunch particle charge).

  • d7da0c8: Replace statistics.parts_into_grid with dataset method bin_into_grid

    Replace statistics.parts_into_grid with a Dataset method called bin_into_grid accessible to particle data (pic_data_type = 'part').

    Breaking change: statistics.parts_into_grid does not work anymore

    Please replace the function statistics.parts_into_grid with the ds.ozzy.bin_into_grid method. As an example, the following code

    import ozzy as oz
import ozzy.statistics as stats
import numpy as np

particles = oz.Dataset(
    {
        "x1": ("pid", np.random.uniform(0, 10, 10000)),
        "x2": ("pid", np.random.uniform(0, 5, 10000)),
        "q": ("pid", np.ones(10000)),
    },
    coords={"pid": np.arange(10000)},
    attrs={"pic_data_type": "part"}
)

axes = oz.Dataset(
    coords={
        "x1": np.linspace(0, 10, 101),
        "x2": np.linspace(0, 5, 51),
    },
    attrs={"pic_data_type": "grid"}
)

binned = stats.parts_into_grid(particles, axes, r_var="x2")
grid_data_axisym = particles.ozzy.bin_into_grid(axes, r_var="x2")
    should be replaced by

    import ozzy as oz
import numpy as np
...
binned = particles.ozzy.bin_into_grid(axes, r_var="x2")

  • 5840bc4: Make str_exists argument of get_attr_if_exists optional

  • 5d53830: Use helper functions to handle dataarray attributes whenever possible

Version 0.2.1§

Released 21-10-2024

Bug Fixes§

  • 0c2bb5f: Error is now raised when an invalid n0 argument is passed to convert_q

Documentation§

  • 426b187: Add feedback widget across pages

  • 7877d0e: Try to add umami analytics in different way

  • 3e62f7b: Add umami analytics for documentation website

  • ae7b7b3: Add black as project dependency for better formatting of code signatures in documentation

  • 0bd401b: Debug and small corrections

  • 29be6fd: Change main blurb, include install instructions with git and poetry

Refactoring§

  • a2d20bc: Add two helper functions to set dataarray attributes depending on whether they already exist or not, + unit tests for these functions

Version 0.2.0§

Released 15-10-2024

Features§

  • b4b61c7: Save movies of ozzy plots

Version 0.1.7§

Released 07-10-2024

Bug Fixes§

  • 6fcd37d: Get_phase_space bug fixes

    • no error when limits are set automatically and all quantity values are zero
    • make sure that axisymmetric geometry is taken into account correctly when the radius variable isn't being binned directly

  • c12f766: Correct units of particle momenta

Version 0.1.6§

Released 30-09-2024

Bug Fixes§

  • 96a7340: Units in parts_into_grid are now fetched from raw_ds argument

Version 0.1.5§

Released 23-09-2024

Performance Improvements§

  • d4d08a5: Improve concatenation of tb files along time

Refactoring§

Version 0.1.4§

Released 18-09-2024

Bug Fixes§

Features§

  • de9520c: Scaffolding for emittance method

Refactoring§

  • 506f060: Replace ~ with not

  • 9ce2c8a: Utils function to set attributes if they exist

Version 0.1.3§

Released 17-09-2024

Bug Fixes§

Version 0.1.2§

Released 17-09-2024

Bug Fixes§

  • d48785c: Change units of density in parts_into_grid

Refactoring§

  • 0bd8cc1: Change norm. units of q in particle data

  • 1c5d48e: Add axisym argument to get_phase_space

Version 0.1.1§

Released 13-08-2024

Bug Fixes§

  • fed8f27: Automatic extent calculation for phase space even when min = max

Documentation§

  • 1ef5d22: Include zenodo reference

Refactoring§

  • 2d79f50: Utils function to set attributes if they exist

Version 0.1.0§

Released 16-07-2024

Features§

  • 109e196: Set up cd of ozzy releases

Version 0.0.1§

Released 16-07-2024

Bug Fixes§

  • 8e5fabd: Use correct function to register colormap

Version 0.0.0§

Released 16-07-2024

Documentation§