evaluator.simulation_output.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

class SimulationOutputEvaluator(value_getter: ~typing.Callable[[~beam_calculation.simulation_output.simulation_output.SimulationOutput], ~numpy.ndarray | float], ref_simulation_output: ~beam_calculation.simulation_output.simulation_output.SimulationOutput, ref_value_getter: ~typing.Callable[[~beam_calculation.simulation_output.simulation_output.SimulationOutput, ~beam_calculation.simulation_output.simulation_output.SimulationOutput], ~numpy.ndarray | float] | None = None, post_treaters: ~collections.abc.Sequence[~typing.Callable[[~numpy.ndarray | float, ~numpy.ndarray | float], ~numpy.ndarray | float]] = (<function do_nothing>,), tester: ~typing.Callable[[~numpy.ndarray | float], float | bool | None] | None = None, descriptor: str = '', markdown: str = '', plt_kwargs: dict[str, ~typing.Any] | None = None, raise_error_if_value_getter_returns_none: bool = True)

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 = None) – A dictionary with keyword arguments passed to the plt.Figure. The default is None.

__init__(value_getter: ~typing.Callable[[~beam_calculation.simulation_output.simulation_output.SimulationOutput], ~numpy.ndarray | float], ref_simulation_output: ~beam_calculation.simulation_output.simulation_output.SimulationOutput, ref_value_getter: ~typing.Callable[[~beam_calculation.simulation_output.simulation_output.SimulationOutput, ~beam_calculation.simulation_output.simulation_output.SimulationOutput], ~numpy.ndarray | float] | None = None, post_treaters: ~collections.abc.Sequence[~typing.Callable[[~numpy.ndarray | float, ~numpy.ndarray | float], ~numpy.ndarray | float]] = (<function do_nothing>,), tester: ~typing.Callable[[~numpy.ndarray | float], float | bool | None] | None = None, descriptor: str = '', markdown: str = '', plt_kwargs: dict[str, ~typing.Any] | None = None, raise_error_if_value_getter_returns_none: bool = True) → None

__post_init__()

Check inputs, create plot if a fignum was provided.

_abc_impl = <_abc._abc_data object>

_add_a_limit_plot(z_data: ndarray, limit: tuple[ndarray | float, ndarray | float], **plot_kw: str) → None

Add limits to the plot.

_add_a_value_plot(z_data: ndarray, value: ndarray | float, **plot_kw: str) → None

Add (treated) data to the plot.

_add_structure_plot(simulation_output: SimulationOutput) → None

Add a plot of the structure in the bottom ax.

_apply_post_treatments(x_data: ndarray | float, y_data: ndarray | float, y_ref_data: ndarray | float, **plot_kw: str) → ndarray | float

Apply all the post_treaters functions.

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

_apply_test(x_data: ndarray, y_data: ndarray | float, **plot_kw: str) → bool | float | None

Apply da testing functions.

Can also plot the test results if asked.

_create_plot(fignum: int | None = None, **kwargs) → None

Prepare the plot.

_get_data(simulation_output: SimulationOutput) → tuple[ndarray, ndarray | float | None]

Get da data.

_get_ref_data(simulation_output: SimulationOutput) → ndarray | float | None

Get da reference data.

_resampled(x_data: ndarray, y_data: ndarray | float, y_ref_data: ndarray | float) → tuple[ndarray, ndarray, ndarray, ndarray]

Resample data.

_save_plot(out_path: Path, fignum: int | None = None, savefig: bool = False, **kwargs) → None

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

descriptor: str = ''

markdown: str = ''

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

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

raise_error_if_value_getter_returns_none: bool = True

ref_simulation_output: SimulationOutput

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

run(simulation_output: SimulationOutput) → ndarray | bool | float

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.

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

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

_descriptor(descriptor: str) → str

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

_limits_given_in_functoolspartial_args(partial_function: Callable) → Sequence[ndarray | float]

Extract the limits given to a test function.

_need_to_resample(value: ndarray | float, ref_value: ndarray | float) → bool

Determine if we need to resample value or ref_value.

_post_treaters(post_treaters: Callable[[ndarray | float, ndarray | float], ndarray | float] | Sequence[Callable[[ndarray | float, ndarray | float], ndarray | float]]) → Sequence[Callable[[ndarray | float, ndarray | float], ndarray | float]]

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

_return_value_should_be_plotted(partial_function: Callable) → bool

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.

kwargs(plt_kwargs: dict[str, Any] | None) → dict[str, Any]

Test plot kwargs, add some default values.