Ctrl+K
Ctrl+K
Ctrl+K

nifty8.minimization.optimize_kl module#

optimize_kl(likelihood_energy, total_iterations, n_samples, kl_minimizer, sampling_iteration_controller, nonlinear_sampling_minimizer, constants=[], point_estimates=[], transitions=None, export_operator_outputs={}, output_directory=None, initial_position=None, initial_index=0, comm=None, inspect_callback=None, terminate_callback=None, plot_energy_history=True, plot_minisanity_history=True, save_strategy='last', return_final_position=False, resume=False, sanity_checks=True, dry_run=False)[source]#

Provide potentially useful interface for standard KL minimization.

The parameters likelihood_energy, kl_minimizer, sampling_iteration_controller, nonlinear_sampling_minimizer, constants, point_estimates and comm also accept a function as input that takes the index of the global iteration as input and returns the respective value that should be used for that iteration.

High-level pseudo code of the algorithm, that is implemented by optimize_kl:

for ii in range(initial_index, total_iterations):
    samples = Draw `n_samples` approximate samples(position,
                                                   likelihood_energy
                                                   sampling_iteration_controller,
                                                   nonlinear_sampling_minimizer,
                                                   point_estimates)
    position, samples = Optimize approximate KL(likelihood_energy, samples) with `kl_minimizer`(constants)
    Save intermediate results(samples)
Parameters:

  • likelihood_energy (Operator or callable) – Likelihood energy shall be used for inference. It is assumed that the definition space of this energy contains parameters that are a-priori standard normal distributed. It needs to have a MultiDomain as Domain.

  • total_iterations (int) – Number of resampling loops.

  • n_samples (int or callable) – Number of samples used to sample Kullback-Leibler divergence. 0 corresponds to maximum-a-posteriori.

  • kl_minimizer (Minimizer or callable) – Controls the minimizer for the KL optimization.

  • sampling_iteration_controller (IterationController or None or callable) – Controls the conjugate gradient for inverting the posterior metric. If None, approximate posterior samples cannot be drawn. It is only suited for maximum-a-posteriori solutions.

  • nonlinear_sampling_minimizer (Minimizer or None or callable) – Controls the minimizer for the non-linear geometric sampling to approximate the KL. Can be either None (then the MGVI algorithm is used instead of geoVI) or a Minimizer.

  • constants (list or callable) – List of parameter keys that are kept constant during optimization. Default is no constants.

  • point_estimates (list or callable) – List of parameter keys for which no samples are drawn, but that are (possibly) optimized for, corresponding to point estimates of these. Default is to draw samples for the complete domain.

  • transitions (callable or None) – Function that takes the global iteration index and returns a function that is applied at the beginning of each iteration to the current ResidualSampleList. This can be used if parts of the likelihood_energy are replaced and thereby have a different domain. If None is passed or returned in one iteration, no transition will be applied. Default is None.

  • export_operator_outputs (dict) – Dictionary of operators that are exported during the minimization. The key contains a string that serves as identifier. The value of the dictionary is an operator.

  • output_directory (str or None) – Directory in which all output files are saved. If None, no output is stored. Default: None.

  • initial_position (nifty8.field.Field, nifty8.multi_field.MultiField or None) – Position in the definition space of likelihood_energy from which the optimization is started. If None, it starts at a random, normal distributed position with standard deviation 0.1. Default: None.

  • initial_index (int) – Initial index that is used to enumerate the output files. May be used if optimize_kl is called multiple times. Default: 0.

  • comm (MPI communicator or None) – MPI communicator for distributing samples over MPI tasks. If None, the samples are not distributed. Default: None.

  • inspect_callback (callable or None) – Function that is called after every global iteration. It can be either a function with one argument (then the latest sample list is passed), a function with two arguments (in which case the latest sample list and the global iteration index are passed). Default: None.

  • terminate_callback (callable or None) – Function that is called after every global iteration and after inspect_callback if present. It can be either None or a function that takes the global iteration index as input and returns a boolean. If the return value is true, the global loop in optimize_kl is terminated. Default: None.

  • plot_energy_history (bool) – Determine if the KLEnergy values shall be plotted or not. Default: True.

  • plot_minisanity_history (bool) – Determine if the reduced chi-square values computed by minisanity shall be plotted or not. Default: True.

  • save_strategy (str) – If “last”, the samples are saved after each global iteration and overwrite older saved samples so that only the latest ones are kept. If “all”, all intermediate samples are written to disk and the filename contains the global_iteration so that nothing is overwritten. save_strategy is only applicable if output_directory is not None. Default: “last”.

  • return_final_position (bool) – Determine if the final position of the minimization shall be return. May be useful to feed it as initial_position into another optimize_kl call. Default: False.

  • resume (bool) – Resume partially run optimization. If True and output_directory contains last_finished_iteration, initial_index and initial_position are ignored and read from the output directory instead. If last_finished_iteration is not a file, the value of initial_position is used instead. Default: False.

  • sanity_checks (bool) – Some sanity checks that are evaluated at the beginning. They are potentially expensive because all likelihoods have to be instantiated multiple times. Default: True.

  • dry_run (bool) – Skips all expensive optimizations. Can be used to check that all domains fit together. Default: False.

Returns:

Note

If h5py is available, the output of all plotted operators is saved as hdf5 file as well. If astropy is available, the mean and standard deviation of all plotted operators, that have a single 2d-RGSpace as target, are exported as FITS files.

Note

This function comes with some MPI support. Generally, with the help of MPI samples are distributed over tasks.

On this page
Show Source