simulation_output_evaluator module

Define an object to evaluate quality of a set of cavity settings.

Note

We do not directly evaluate a SetOfCavitySettings though, but rather a SimulationOutput.

Todo

different factories for evaluation during the fit and evaluation after

Todo

Clean this.

_need_to_resample(value, ref_value)[source]

Determine if we need to resample value or ref_value.

Parameters:

value (ndarray | float)
ref_value (ndarray | float)

Return type:

bool

_return_value_should_be_plotted(partial_function)[source]

Determine if keyword ‘to_plot’ was passed and is True.

This function only works on functions defined by functools.partial. If it is not (lambda function, “classic” function), we consider that the plotting was not desired. We check if the ‘to_plot’ keyword was given in the partial definition, and if it is not we also consider that the plot was not wanted.

Parameters:: partial_function (Callable)
Return type:: bool

_limits_given_in_functoolspartial_args(partial_function)[source]

Extract the limits given to a test function.

Parameters:: partial_function (Callable)
Return type:: Sequence[ndarray | float]

class SimulationOutputEvaluator(value_getter, ref_simulation_output, ref_value_getter=None, post_treaters=(<function do_nothing at 0x73dca29de980>, ), tester=None, descriptor='', markdown='', plt_kwargs=None, raise_error_if_value_getter_returns_none=True)[source]

Bases: ABC

A base class for all the possible types of tests.

Parameters:

value_getter (Callable[[SimulationOutput], value_t]) – A function that takes the simulation output under study as argument, and returns the value to be studied.
ref_simulation_output (SimulationOutput) – The simulation output of a nominal Accelerator. It is up to the user to verify that the BeamCalculator is the same between the reference and the fixed SimulationOutput.
ref_value_getter (Callable[[SimulationOutput, SimulationOutput], ref_value_t] | None, optional) – A function that takes the reference simulation ouput and the simulation output under study as arguments, and returns the reference value. In general, only the first argument will be used. The second argument can be used in specific cases, eg for the mismatch factor. The default is None.
post_treaters (Sequence[post_treater_t], optional) – A tuple of functions that will be called one after each other and applied on value, which is returned by value_getter. First argument must be value, second argument ref_value. They return an update value, which is passed to the next function in post_treaters. The default is a tuple containing only do_nothing().
tester (tester_t | None, optional) – A function that takes post-treated value and test it. It can return a boolean or a float. The default is None.
fignum (int | None, optional) – The Figure number. The default is None, in which case no plot is produced.
descriptor (str, optional) – A sentence or two to describe what the test is about. The default is an empty string.
markdown (str, optional) – A markdown name for this quantity, used in plots y label. The default is an empty string.
plt_kwargs (dict[str, Any] | None, optional) – A dictionary with keyword arguments passed to the plt.Figure. The default is None.
raise_error_if_value_getter_returns_none (bool, default: True)

value_getter: Callable[[SimulationOutput], ndarray | float]

ref_simulation_output: SimulationOutput

ref_value_getter: Callable[[SimulationOutput, SimulationOutput], ndarray | float] | None = None

post_treaters: Sequence[Callable[[ndarray | float, ndarray | float], ndarray | float]] = (<function do_nothing at 0x73dca29de980>,)

tester: Callable[[ndarray | float], float | bool | None] | None = None

descriptor: str = ''

markdown: str = ''

plt_kwargs: dict[str, Any] | None = None

raise_error_if_value_getter_returns_none: bool = True

__post_init__()[source]: Check inputs, create plot if a fignum was provided.

run(simulation_output)[source]

Run the test.

It can return a bool (test passed with success or not), or a float. The former is useful for production purposes, when you want to sort the settings in valid/invalid categories. The latter is useful for development purposes, i.e. to identify the most complex cases in a bunch of configurations.

Parameters:: simulation_output (SimulationOutput)
Return type:: ndarray | bool | float

_get_data(simulation_output)[source]

Get da data.

Parameters:: simulation_output (SimulationOutput)
Return type:: tuple[ndarray, ndarray | float | None]

_get_ref_data(simulation_output)[source]

Get da reference data.

Parameters:: simulation_output (SimulationOutput)
Return type:: ndarray | float | None

_resampled(x_data, y_data, y_ref_data)[source]

Resample data.

Parameters:

x_data (ndarray)
y_data (ndarray | float)
y_ref_data (ndarray | float)

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

_apply_post_treatments(x_data, y_data, y_ref_data, **plot_kw)[source]

Apply all the post_treaters functions.

Can also plot the post-treated data after all or some of the post-treatments have been performed.

Parameters:

x_data (ndarray | float)
y_data (ndarray | float)
y_ref_data (ndarray | float)
plot_kw (str)

Return type:

ndarray | float

_apply_test(x_data, y_data, **plot_kw)[source]

Apply da testing functions.

Can also plot the test results if asked.

Parameters:

x_data (ndarray)
y_data (ndarray | float)
plot_kw (str)

Return type:

bool | float | None

_create_plot(fignum=None, **kwargs)[source]

Prepare the plot.

Parameters:: fignum (int | None, default: None)
Return type:: None

_add_structure_plot(simulation_output)[source]

Add a plot of the structure in the bottom ax.

Parameters:: simulation_output (SimulationOutput)
Return type:: None

_add_a_value_plot(z_data, value, **plot_kw)[source]

Add (treated) data to the plot.

Parameters:

z_data (ndarray)
value (ndarray | float)
plot_kw (str)

Return type:

None

_add_a_limit_plot(z_data, limit, **plot_kw)[source]

Add limits to the plot.

Parameters:

z_data (ndarray)
limit (tuple[ndarray | float, ndarray | float])
plot_kw (str)

Return type:

None

_save_plot(out_path, fignum=None, to_save=False, **kwargs)[source]

Save the figure if asked, and if out_path is defined.

Parameters:

out_path (Path)
fignum (int | None, default: None)
to_save (bool, default: False)

Return type:

None

__init__(value_getter, ref_simulation_output, ref_value_getter=None, post_treaters=(<function do_nothing at 0x73dca29de980>, ), tester=None, descriptor='', markdown='', plt_kwargs=None, raise_error_if_value_getter_returns_none=True)

Parameters:

value_getter (Callable[[SimulationOutput], ndarray | float])
ref_simulation_output (SimulationOutput)
ref_value_getter (Callable[[SimulationOutput, SimulationOutput], ndarray | float] | None, default: None)
post_treaters (Sequence[Callable[[ndarray | float, ndarray | float], ndarray | float]], default: (<function do_nothing at 0x73dca29de980>,))
tester (Callable[[ndarray | float], float | bool | None] | None, default: None)
descriptor (str, default: '')
markdown (str, default: '')
plt_kwargs (dict[str, Any] | None, default: None)
raise_error_if_value_getter_returns_none (bool, default: True)

_abc_impl = <_abc._abc_data object at 0x73dca29aa780>

_descriptor(descriptor)[source]

Clean the given string, raise warning if it is empty.

Parameters:: descriptor (str)
Return type:: str

_post_treaters(post_treaters)[source]

Check that we have a tuple, convert it to tuple if not.

Parameters:: post_treaters (Callable[[ndarray | float, ndarray | float], ndarray | float] | Sequence[Callable[[ndarray | float, ndarray | float], ndarray | float]])
Return type:: Sequence[Callable[[ndarray | float, ndarray | float], ndarray | float]]

kwargs(plt_kwargs)[source]

Test plot kwargs, add some default values.

Parameters:: plt_kwargs (dict[str, Any] | None)
Return type:: dict[str, Any]