Concept

The idea of the library is to provide an easy but flexible way for common visualization tasks, allowing for fast interactive data exploration while ensuring high quality publication-ready plots.

Flexibility

The library must not depend on xsuite (i.e. import it), but provide a basic functionality for any data source, e.g. MAD-X or even measurement data (such as timestamps of particle-hits from a TDC based detector).
For example, the FloorPlot can be used with surveys from MAD-X as well as xsuite, allowing to compare the lattice before/after conversion; However, advanced functionality, such as the nice looking boxes, only works when an xsuite line is provided. Another example: The TimeFFTPlot allows to plot FFTs based on data from simulation (particles with at_turn and zeta properties), from timestamp based measurements (hits with timestamp t properties) and even from pre-binned timeseries data (e.g. waveforms).

The user must also always have the ability to pass additional options to modify the appearance of artists, such as linestyles or colors. This is taken care of by providing plot_kwargs=dict(ls="--") parameters.

Properties

A core concept is the usage of properties, which are used to define

• the attribute or key used to access the values from the data object (e.g. betx)
• the units of the data, so that conversion to the desired display-unit can be handled (e.g. m)
• the labels for plot axes and legends (e.g. $\beta_x$)

This concept simplifies the extendability of the library, since a user can register new properties, overwrite labels and units, or register derived properties which are based on calculations using data from other properties. All plots can then immediately use the new or updated properties, without the need to change the individual implementation. In the same way, the developer can simply use the respective methods of the property to get the required data, labels etc. See https://eltos.github.io/xplt/examples/properties.html for usage examples

Properties are typically selected by a kind= parameter in the plot constructor, which allows to quickly explorer a datasets in different dimensions and correlations. For example, the PhaseSpacePlot can be used to show a particle distribution in any desired phase space, just by simply changing kind="x-y" to kind="a-b". See https://eltos.github.io/xplt/examples/phasespace.html for examples

Re-usability

All plots of the library are based on the XPlot class. Many are based on the XManifoldPlot class, which provides the infrastructure to handle subplots, twin-axes and multiple traces (or artists) of a single figure, just by the kind="a,b-c,d+e" string. This allows the user to very quickly add another subplot or trace. From a developer perspective, only the concept of a single trace (artists) has to be implemented, and the rest is taken care of by the XManifoldPlot by looping through the required artists, and taking care of axes labels, units etc. The TwissPlot is a good example, see https://eltos.github.io/xplt/examples/twiss.html

There are also several "Mixins" which add functionality to a plot by subclassing them, such as additional properties for action-angle variables (ParticlePlotMixin), metrics for spill quality evaluation (MetricesMixin), or useful methods for histogramming (ParticleHistogramPlotMixin).

Animations

In the constructor, only the axes and artists are created. Every plot has an update() method, which is used to actually set the data to the respective artists. This method is called in the end of the constructor to allow a single-line plot creation, but the real strength of this comes into play, when creating animations, where the data (or mask) is updated from frame-to-frame. See https://eltos.github.io/xplt/examples/animations.html for examples.

Documentation

Documentation is a crucial aspect to enable other people to effectively and efficiently use the library. All plots and methods must have Google-style docstrings explaining all parameters (including type hints). These are picked up by sphinx when the API documentation is generated automatically. The example notebooks serve two purposes: They are used for testing, and they are also picked up by sphinx and included in the documentation. It is in general a good practice to add new plots there, both to facilitate testing during implementation and debugging, and then to also have it documented without a lot of additional effort.