power_step module

Returns:

Instruments data at thresholds, as plotted in the figure.

_instruments_by_class(instrument_class, measurement_points=None, instruments_to_ignore=())

Get all instruments of desired class from measurement_points.

But remove the instruments to ignore.

Parameters:

instrument_class (ABCMeta) – Class of the desired instruments.
measurement_points (Sequence[IMeasurementPoint] | None, default: None) – The measurement points from which you want the instruments. The default is None, in which case we look into every IMeasurementPoint attribute of self.
instruments_to_ignore (Sequence[Instrument | str], default: ()) – The Instrument or instrument names you do not want.

Return type:

Returns:

All the instruments matching the required conditions.

_instruments_by_name(instrument_names)

Get all instruments of desired name from measurement_points.

Parameters:

instrument_name – Name of the desired instruments.
instrument_names (Sequence[str])

Return type:

Returns:

All the instruments matching the required conditions.

_plot_instruments_single_time_step(step_idx, keep_one_frame_over, axes_instruments, artists=None, last_frame=None)

Plot all instruments signal at proper axe and time step.

Parameters:

step_idx (int)
keep_one_frame_over (int)
axes_instruments (dict[Axes, list[Instrument]])
artists (Sequence[Artist] | None, default: None)
last_frame (int | None, default: None)

Return type:

Sequence[Artist] | None

_power_growth_array(growth_array_kw=None)

Determine where power grows, decreases, is stable.

Parameters:: growth_array_kw (dict[str, Any] | None, default: None)
Return type:: ndarray[tuple[Any, ...], dtype[double]]

_prepare_animation_fig(to_plot, measurement_points_to_exclude=(), instruments_to_ignore_for_limits=(), instruments_to_ignore=(), **fig_kw)

Create the figure and axes for the animation.

Parameters:

to_plot (Sequence[ABCMeta]) – Classes of instruments you want to see.
measurement_points_to_exclude (tuple[str, ...], default: ()) – Measurement points that should not appear.
instruments_to_ignore_for_limits (tuple[str, ...], default: ()) – Instruments to plot, but that can go off limits.
instruments_to_ignore (Sequence[Instrument | str], default: ()) – Instruments that will not even be plotted.
fig_kw – Other keyword arguments for Figure.

Return type:

tuple[Figure, dict[Axes, list[Instrument]]]

Returns:

fig – Figure holding the axes.
axes_instruments – Links the instruments to plot with the Axes they should be plotted on.

_set_x_data(xdata, predicate=None, exclude=())

Set the data that will be used for x-axis.

Parameters:

xdata (ABCMeta | None) – Class of an instrument, or None (in this case, use default index).
exclude (Sequence[str], default: ()) – Name of instruments to exclude. Deprecated, prefer predicate.
predicate (Callable[[ABCMeta | Instrument | str], bool] | None, default: None) – Instrument filtering function.

Return type:

tuple[list[Series], list[str] | None]

Returns:

list[pd.Series] – Contains the data used for x axis.
list[str] | None – Name of the column(s) used for x axis.

_set_y_data(data_to_plot, *ydata, exclude=(), predicate=None, column_names='', masks=None, raw=False, **kwargs)

Set the y-data that will be plotted.

Parameters:

data_to_plot (list[Series | DataFrame]) – List already containing the x-data, or nothing if the index is to be used.
*ydata (ABCMeta) – The class of the instruments to plot.
exclude (Sequence[str], default: ()) – Name of some instruments to exclude. Deprecated, prefer using predicate.
predicate (Callable[[ABCMeta | Instrument | str], bool] | None, default: None) – Instrument filtering function.
column_names (str | list[str], default: '') – To override the default column names. This is used in particular with the method TestCampaign.sweet_plot(), when all_on_same_plot=True.
masks (dict[str, ndarray[tuple[Any, ...], dtype[bool]]] | None, default: None) – A dictionary where each key is a suffix used to label the split columns, and each value is a boolean mask of the same length as the input data. Keys must start with two underscores (__) to enable consistent column naming and compatibility with downstream styling logic (e.g., grouping lines by base column in plots). If multiple masks are True at the same row index, a ValueError is raised.
raw (bool, default: False) – To get raw data (generally acquisition voltage) instead of physical data.
kwargs – Other keyword arguments.

Return type:

tuple[list[Series], list[list[str]], dict[str, str]]

Returns:

data_to_plot – List containing all the series that will be plotted.
y_columns – Contains, for every subplot, the name of the columns to plot. If column_names is provided, it overrides the given y_columns.
color – Dictionary linking column names in df_to_plot to HTML colors. Used to keep the same color between different instruments at the same PickUp.

add_instrument(instrument, measurement_point)

Manually add an instrument.

Parameters:

instrument (Instrument)
measurement_point (str | IMeasurementPoint)

Return type:

add_post_treater(post_treater, instrument_class=<class 'multipac_testbench.instruments.instrument.Instrument'>, only_pick_up_which_name_is=())

Add post-treatment functions to instruments.

Todo

Find out why following lines result in strange plot linestyles.

measurement_points: list[IMeasurementPoint] = self.pick_ups
if self.global_diagnostics is not None:
    measurement_points.append(self.global_diagnostics)

Parameters:

post_treater (Callable[[ndarray[tuple[Any, ...], dtype[double]]], ndarray[tuple[Any, ...], dtype[double]]])
instrument_class (ABCMeta, default: <class 'multipac_testbench.instruments.instrument.Instrument'>)
only_pick_up_which_name_is (Collection[str], default: ())

Return type:

animate_instruments_vs_position(instruments_to_plot, gif_path=None, fps=50, keep_one_frame_over=1, interval=None, only_first_frame=False, last_frame=None, **fig_kw)

Represent measured signals with probe position.

Todo

last_frame badly handled: gif will be as long as if the last_frame was not set, except that images won’t be updated after the last frame.

Parameters:

instruments_to_plot (Sequence[ABCMeta])
gif_path (Path | None, default: None)
fps (int, default: 50)
keep_one_frame_over (int, default: 1)
interval (int | None, default: None)
only_first_frame (bool, default: False)
last_frame (int | None, default: None)

Return type:

FuncAnimation | list[Axes]

data_for_perez_scaling_law(threshold_set, xdata, use_theoretical_xdata=False, **kwargs)

Get the data necessary to plot the Perez scaling law.

In particular, the last measured voltage thresholds, and $SWR$ or $R$ according to xdata at corresponding time steps.

Use it with local multipactor, ie avoid ThresholdSet created with a threshold_reducer.

Parameters:

threshold_set (ThresholdSet | dict[MultipactorTest, ThresholdSet]) – Object telling where multipactor happens.
xdata (ABCMeta) – Desired type of xdata, generally SWR or ReflectionCoefficient.
use_theoretical_xdata (bool, default: False) – To use theoretical xdata. Works only for reflection coefficient and standing wave ratio.
kwargs – Currently unused.

Return type:

tuple[DataFrame, dict[str, tuple[float, float, float] | None]]

Returns:

df – Holds the last voltage thresholds, as well as corresponding $R$ or $SWR$ values. Column headers look like: "NI9205_E4 @ upper threshold (according to NI9205_MP4l)".
label_to_color – Maps every y-column of the dataframe to a specific color.

data_for_somersalo_scaling_law(threshold_set, use_theoretical_r=False, **kwargs)

Get the data necessary to plot the Somersalo scaling law.

In particular, the last detected power thresholds, and the reflection coefficient $R$ at the corresponding time steps. Lower and upper thresholds are returned, even if Somersalo scaling law does not concern the upper threshold.

Use it with global multipactor, ie with ThresholdSet created with threshold_reducer="all".

Parameters:

threshold_set (ThresholdSet | dict[MultipactorTest, ThresholdSet]) – Object telling where multipactor happens.
use_theoretical_r (bool, default: False) – If set to True, we use the $R$ corresponding to the user-defined $SWR$.
kwargs – Other keyword arguments passed to ThresholdSet.data_at_thresholds().

Return type:

Returns:

Holds the forward power at the last upper and lower thresholds, as well as corresponding $R$ values (same time steps).

data_for_susceptibility(threshold_set, ydata=<class 'abc.ABCMeta'>, use_theoretical_swr=False, d_cm=1.0955, fd_col='$f\\\\cdot d~[\\\\mathrm{MHz cm}]', **kwargs)

Get the data required to create the susceptibility plot.

In particular, voltage or power thresholds according to ydata, SWR, and $f\cdot d$ product.

Parameters:

threshold_set (ThresholdSet | Mapping[MultipactorTest, ThresholdSet]) – Object telling where multipactor happens.
ydata (ABCMeta, default: <class 'abc.ABCMeta'>) – Type of instrument of which you want data in y-axis. In general, you will want FieldProbe or ForwardPower.
use_theoretical_swr (bool, default: False) – To insert theoretical SWR defined by MultipactorTest.swr instead of the value taken from SWR VirtualInstrument.
d_cm (float, default: 1.0955) – System gap in $\mathrm{cm}$.
fd_col (str, default: '$f\\\\cdot d~[\\\\mathrm{MHz cm}]') – Name of the column that will hold the $f\cdot d$ product.

Return type:

Returns:

Holds value of ydata instruments at lower and upper thresholds, as well as the $f\cdot d$ values.

determine_thresholds(multipac_detector, instrument_class, power_growth_array_kw=None, threshold_reducer=None, threshold_predicate=None, instrument_predicate=None, **kwargs)

Determine lower and upper multipactor thresholds.

Parameters:

multipac_detector (Callable[[ndarray[tuple[Any, ...], dtype[double]]], ndarray[tuple[Any, ...], dtype[bool]]]) – Function that takes in the data of an Instrument and returns an array, where True means multipactor and False no multipactor.
instrument_class (ABCMeta) – Type of instrument on which multipac_detector should be applied.
power_growth_array_kw (dict[str, Any] | None, default: None) – Keyword arguments passed to PowerSetpoint.growth_array().
threshold_reducer (Literal['any', 'all'] | None, default: None) – If provided, we consider that multipactor appears when one detecting Instrument detected it ("any"), or only when all detecting Instrument measured it ("all").
threshold_predicate (ThresholdFilter | None, default: None) – Function filtering the thresholds. Applied after threshold_reducer.
instrument_predicate (Callable[[ABCMeta | Instrument | str], bool] | None, default: None) – Instrument filtering function.

Return type:

ThresholdSet

Returns:

Object holding all lower and upper thresholds, detected by multipac_detector applied on every instance of instrument_class.

property freq_mhz: float: Frequency in $\mathrm{MHz}$.

get_instrument(instrument_id, raise_missing_error=True, predicate=None, measurement_points_to_exclude=(), instruments_to_ignore=())

Overloads:

self, instrument_id (INSTRUMENT_ID | INSTRUMENTS_ID), raise_missing_error (Literal[False]), predicate (INSTRUMENT_FILTER | None), measurement_points_to_exclude (MEASUREMENT_POINTS_ID), instruments_to_ignore (INSTRUMENTS_ID) → Instrument | None
self, instrument_id (INSTRUMENT_ID | INSTRUMENTS_ID), raise_missing_error (Literal[True]), predicate (INSTRUMENT_FILTER | None), measurement_points_to_exclude (MEASUREMENT_POINTS_ID), instruments_to_ignore (INSTRUMENTS_ID) → Instrument

Get a single instrument matching instrument_id.

Parameters:

instrument_id (ABCMeta | Instrument | str | Sequence[ABCMeta] | Sequence[str] | Sequence[Instrument]) – Identifies one (or several) Instrument. If several Instrument instances can be returned, you must specify predicate to filter all instances but one.
raise_missing_error (bool, default: True) – If an error should be raised when no corresponding Instrument is found.
predicate (Callable[[ABCMeta | Instrument | str], bool] | None, default: None) – Instrument filtering function.
to_exclude – Exclude some measurement points from the filtering. Deprecated, prefer using predicate.
instruments_to_ignore (ABCMeta | Sequence[ABCMeta] | Sequence[str] | Sequence[Instrument], default: ()) – Instruments to exclude from filtering. Deprecated, prefer using predicate.
measurement_points_to_exclude (Collection[IMeasurementPoint] | Collection[str], default: ())

Returns:

A single Instrument instance. If several instances were found, we raise a warning but still return an Instrument (the first one; may change between executions!).

Raises:

MissingInstrumentError – When no matching Instrument was found, if raise_missing_error is set to True.

get_instruments(instruments_id=None, predicate=None, measurement_points_to_exclude=(), instruments_to_ignore=())

Get all instruments matching instrument_id.

Parameters:

instruments_id (ABCMeta | Sequence[ABCMeta] | Sequence[str] | Sequence[Instrument] | None, default: None) – Identifies Instrument. Can be one or several Instrument types (eg CurrentProbe), Instrument instances or Instrument.name.
predicate (Callable[[ABCMeta | Instrument | str], bool] | None, default: None) – Instrument filtering function.
measurement_points_to_exclude (Collection[IMeasurementPoint] | Collection[str], default: ()) – Exclude some measurement points from the filtering. Deprecated, prefer using predicate.
instruments_to_ignore (ABCMeta | Sequence[ABCMeta] | Sequence[str] | Sequence[Instrument], default: ()) – Instruments to exclude from filtering. Deprecated, prefer using predicate.

Return type:

Returns:

List of desired instruments.

get_instruments_at(position, instrument_id=None, tol=1e-10, **kwargs)

Return all instruments located at a given position.

Parameters:

position (float) – The position in meter to match. If it is np.nan, we return global instruments.
instrument_id (ABCMeta | str | Instrument | None, default: None) – Filter instruments by class, name, or instance. If not provided, we look for all stored instruments.
tol (float, default: 1e-10) – Absolute tolerance used when comparing positions.
**kwargs – Passed to MultipactorTest.get_instruments().

Return type:

Sequence[IMeasurementPoint]

Returns:

Matching instruments.

get_measurement_point(name=None, to_exclude=())

Get all or some measurement points. Ensure there is only one.

Parameters:

name (str | None, default: None) – If given, only the IMeasurementPoint which name is in names will be returned.
to_exclude (Sequence[str | IMeasurementPoint], default: ()) – List of objects or objects names to exclude from returned list.

Return type:

IMeasurementPoint

Returns:

The desired object.

get_measurement_points(names=None, to_exclude=())

Get all or some measurement points.

Parameters:

names (Sequence[str] | None, default: None) – If given, only the IMeasurementPoint which name is in names will be returned.
to_exclude (Sequence[str | IMeasurementPoint], default: ()) – List of objects or objects names to exclude from returned list.

Return type:

Returns:

The desired objects.

property info: str: Human-readable label for this test.

property instruments: list[Instrument]: Get all stored instruments.

interactive_sweet_plot(*ydata, xdata=None, **kwargs)

Like sweet_plot, but clicking opens the corresponding PowerStep plot.

Clicking on the figure takes the x-position of the click, resolves the nearest sample_index, and calls PowerStep.sweet_plot() on the associated PowerStep.

Note

Only works when xdata is None (x-axis = Sample index) and when this object was created via PowerStepSet.to_multipactor_test(), which sets power_step_set. Falls back to a plain sweet_plot() otherwise.

Parameters:

*ydata (ABCMeta) – Passed to sweet_plot() and to the per-step PowerStep.sweet_plot() on click.
xdata (ABCMeta | None, default: None) – Passed to sweet_plot(). Must be None for interactivity.
**kwargs – Passed to sweet_plot().

Return type:

tuple[list[Axes], DataFrame]

Returns:

axes – Objects holding the overview plot.
df_to_plot – DataFrame holding the data that is plotted.

output_filepath(out_folder, extension)

Create consistent path for output files.

Parameters:

out_folder (Path | str)
extension (str)

Return type:

Path

plot_thresholds(ydata, threshold_set, xdata=None, title='', same_figure=True, plot_extrema=False, global_instruments=False, global_multipactor=False, png_path=None, png_kwargs=None, csv_path=None, csv_kwargs=None, axes=None, plot_kwargs=None, test_color=None, **kwargs)

Plot ydata instances data at multipactor threshold.

When ydata is ForwardPower or FieldProbe, the figure represents the evolution of the power/voltage multpactor threshold during the test. But this method can be used with any instrument type.

Todo

Add a way to fit exponential (?) law on the thresholds. Will need to change the x-axis.

Parameters:

ydata (ABCMeta) – Class of instrument to plot. Makes most sense with ForwardPower or FieldProbe.
threshold_set (ThresholdSet | dict[MultipactorTest, ThresholdSet]) – Object containing the indexes of thresholds, as well as the position of multipactor.
xdata (ABCMeta | None, default: None) – Class of instrument to use as x-data.
title (str, default: '') – If provided, overrides automatic title.
same_figure (bool, default: True) – If Instrument at different positions should be kept on the same plot.
plot_extrema (bool, default: False) – Add to_plot values at the power minima and maxima. Makes most sense with voltage/power instruments. Resulting plot may be very crowded if same_figure == True.
global_instruments (bool, default: False) – If instruments not position-specific (eg ForwardPower) should be plotted.
global_multipactor (bool, default: False) – If multipactor not position-specific (eg thresholds created by merging several other multipactor arrays) should be plotted.
png_path (Path | None, default: None) – If provided, figure will be saved there.
png_kwargs (dict[str, Any] | None, default: None) – Keyword arguments for the matplotlib.figure.Figure.savefig() method.
csv_path (Path | None, default: None) – If provided, plotted data will be saved there.
csv_kwargs (dict | None, default: None) – Keyword arguments for the pandas.DataFrame.to_csv() method.
axes (Axes | None, default: None) – Axes to re-use. Needs sample_plot=True.
plot_kwargs (dict[str, Any] | None, default: None) – Kwargs passed the plot function.
test_color (str | None, default: None) – Color used by TestCampaign.plot_thresholds() when all_on_same_plot=True. It overrides the Instrument color and is used to discriminate every MultipactorTest from another.

Return type:

tuple[Axes | ndarray[tuple[Any, ...], dtype[Axes]], DataFrame]

Returns:

axes – Hold plotted axes.
df_thresholds – The data used to produce the plot.

reconstruct_voltage_along_line(name, probes_to_ignore=())

Reconstruct the voltage profile from the e field probes.

Parameters:

name (str)
probes_to_ignore (Sequence[str | FieldProbe], default: ())

Return type:

remove_post_treater(post_treater=None, index=None, instrument_class=<class 'multipac_testbench.instruments.instrument.Instrument'>, only_pick_up_which_name_is=())

Remove post-treatment functions from instruments.

Parameters:

only_pick_up_which_name_is (Collection[str], default: ()) – To select only some measurement points by their name.
post_treater (Callable[[ndarray[tuple[Any, ...], dtype[double]]], ndarray[tuple[Any, ...], dtype[double]]] | None, default: None) – Post-treater to remove. Has priority over index.
index (int | None, default: None) – Index of post-treater to remove.
instrument_class (ABCMeta, default: <class 'multipac_testbench.instruments.instrument.Instrument'>) – Type of instruments concerned by removing.

Return type:

scatter_instruments_data(instruments_to_plot, measurement_points_to_exclude=(), thresholds_set=None, png_path=None, **fig_kw)

Plot the data measured by instruments.

This plot results in important amount of points. It becomes interesting when setting different colors for multipactor/no multipactor points and can help see trends.

Todo

Also show from global diagnostic

Todo

User should be able to select: reconstructed or measured electric field.

Todo

Fix this. Or not? This is not the most explicit way to display data…

Parameters:

instruments_to_plot (Sequence[ABCMeta])
measurement_points_to_exclude (Sequence[IMeasurementPoint | str], default: ())
thresholds_set (ThresholdSet | None, default: None)
png_path (Path | None, default: None)

Return type:

tuple[Figure, list[Axes]]

statistics(thresholds_set, instrument_class, global_instruments=False, global_multipactor=False, csv_path=None, csv_kwargs=None, **kwargs)

Compute some statistics on instrument_class at thresholds.

Parameters:

thresholds_set (ThresholdSet) – Calculated multipactor thresholds.
instrument_class (ABCMeta) – Class of instruments under study.
global_instruments (bool, default: False) – If instruments not position-specific (eg ForwardPower) should have their thresholds plotted.
global_multipactor (bool, default: False) – If multipactor not position-specific (eg thresholds created by merging several other multipactor arrays) should have their thresholds plotted.
csv_path (Path | None, default: None) – If specified, save the data used to produce the plot in csv_path.
csv_kwargs (dict[str, Any] | None, default: None) – Keyword arguments passed to plot.save_dataframe().
kwargs – Other keyword arguments passed to ThresholdSet.data_at_thresholds().

Return type:

property swr: float: Expected Standing Wave Ratio.

power_step_set: PowerStepSet | None: PowerStepSet this test was built from, if any. Enables interactive plots.

pick_ups: Where all diagnostics at a specific pick-up are defined (e.g. current probe)

global_diagnostics: Where all diagnostics which are not a specific position are stored (e.g. forward/reflected power)

class PowerStepSet(folder, config, freq_mhz=None, swr=1.0, info='', sep='\\t', index_col='Index', out_index_col='Sample index', file_recognizer=None, comment='#', create_virtual_instruments=True, are_raw=True, **kwargs)[source]

Bases: object

Define all the files constituting a MultipactorTest.

Parameters:

folder (Path)
config (dict[str, Any] | str | Path)
freq_mhz (float | None, default: None)
swr (float, default: 1.0)
info (str, default: '')
sep (str, default: '\\t')
index_col (str, default: 'Index')
out_index_col (str, default: 'Sample index')
file_recognizer (Callable[[Path], bool] | None, default: None)
comment (str, default: '#')
create_virtual_instruments (bool, default: True)
are_raw (bool, default: True)

_config: dict[str, Any]

get_power_step(sample_index)[source]

Return the PowerStep with the given sample_index.

Parameters:: sample_index (int) – The index as stored in PowerStep._sample_index.
Raises:: KeyError – If no PowerStep with that index exists.
Return type:: PowerStep

to_multipactor_test_file(csv_path, reducer=None, index_col='Sample index', special_reducers=None, sep=',', **kwargs)[source]

Create a file that can be loaded by MultipactorTest.

Parameters:

power_steps – All the power steps of the file.
csv_path (Path) – Where the resulting CSV will be stored.
reducer (Callable[[ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]], float] | None, default: None) – Function converting array to float. The default in LabViewer is to take the maximum. If not set, we also use this.
index_col (str, default: 'Sample index') – Name of the column that will contain each power step index.
special_reducers (Mapping[str | type[Instrument], Callable[[ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]], float]] | None, default: None) – Different functions to apply to some specific columns.
sep (str, default: ',') – Column delimiter in the resulting file.
**kwargs – Other keyword arguments passed down to pandas.DataFrame.to_csv().

Return type: