bencher.optuna_conversions
==========================

.. py:module:: bencher.optuna_conversions


Functions
---------

.. autoapisummary::

   bencher.optuna_conversions.optuna_grid_search
   bencher.optuna_conversions.param_importance
   bencher.optuna_conversions.summarise_trial
   bencher.optuna_conversions.sweep_var_to_optuna_dist
   bencher.optuna_conversions.sweep_var_to_suggest
   bencher.optuna_conversions.cfg_from_optuna_trial
   bencher.optuna_conversions._append_safe
   bencher.optuna_conversions._append_safe_sized


Module Contents
---------------

.. py:function:: optuna_grid_search(bench_cfg: bencher.bench_cfg.BenchCfg, trial_vars: list | None = None) -> optuna.Study

   use optuna to perform a grid search

   :param bench_cfg: setting for grid search
   :type bench_cfg: BenchCfg
   :param trial_vars: If provided, use these variables for the search space.
                      Otherwise, filter bench_cfg.all_vars by optimize=True.
   :type trial_vars: list | None

   :returns: results of grid search
   :rtype: optuna.Study


.. py:function:: param_importance(bench_cfg: bencher.bench_cfg.BenchCfg, study: optuna.Study, plot_width: int | None = None) -> panel.Column

.. py:function:: summarise_trial(trial: optuna.trial, bench_cfg: bencher.bench_cfg.BenchCfg) -> list[str]

   Given a trial produce a string summary of the best results

   :param trial: trial to summarise
   :type trial: optuna.trial
   :param bench_cfg: info about the trial
   :type bench_cfg: BenchCfg

   :returns: Summary of trial
   :rtype: list[str]


.. py:function:: sweep_var_to_optuna_dist(var: param.Parameter) -> optuna.distributions.BaseDistribution

   Convert a sweep var to an optuna distribution

   :param var: A sweep var
   :type var: param.Parameter

   :raises ValueError: Unsupported var type

   :returns: Optuna representation of a sweep var
   :rtype: optuna.distributions.BaseDistribution


.. py:function:: sweep_var_to_suggest(iv: bencher.variables.parametrised_sweep.ParametrizedSweep, trial: optuna.trial) -> object

   Converts from a sweep var to an optuna

   :param iv: A parametrized sweep input variable
   :type iv: ParametrizedSweep
   :param trial: Optuna trial used to define the sample
   :type trial: optuna.trial

   :raises ValueError: Unsupported var type

   :returns: A sampled variable (can be any type)
   :rtype: Any


.. py:function:: cfg_from_optuna_trial(trial: optuna.trial, bench_cfg: bencher.bench_cfg.BenchCfg, cfg_type: bencher.variables.parametrised_sweep.ParametrizedSweep) -> bencher.variables.parametrised_sweep.ParametrizedSweep

.. py:function:: _append_safe(row, plot_fn, *args, **kwargs)

   Append a plot to *row*, logging any exception instead of propagating.


.. py:function:: _append_safe_sized(row, plot_fn, width, *args, **kwargs)

   Like _append_safe but sets a consistent width on the resulting plotly figure.