Skip to content

Release Notes§

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§