class_docstr: ExperimentClient providing all functionalities for the python API
  
  Note that the ExperimentClient is not meant to be instantiated by the user.
  Look at `orion.client.create_experiment` to build an ExperimentClient.
  
  Parameters
  ----------
  experiment: `orion.core.worker.experiment.Experiment`
      Experiment object serving for interaction with storage
class_docstr_tok: ["ExperimentClient","providing","all","functionalities","for","the","python","API","Note","that","the","ExperimentClient","is","not","meant","to","be","instantiated","by","the","user",".","Look","at","`","orion.client.create_experiment","`","to","build","an","ExperimentClient",".","Parameters","--","--","--","--","--","experiment",":","`","orion.core.worker.experiment.Experiment","`","Experiment","object","serving","for","interaction","with","storage"]
docstr: Optimize a given function
  
  Experiment must be in executable ('x') mode.
  
  Parameters
  ----------
  fct: callable
      Function to optimize. Must take arguments provided by trial.params. Additional constant
      parameter can be passed as ``**kwargs`` to `workon`. Function must return the final
      objective.
  n_workers: int, optional
      Number of workers to run in parallel. Defaults to value of global config.
  pool_size: int, optional
      Number of trials to sample at a time. If 0, defaults to `n_workers` or value of global
      config if defined.  Increase it to improve the sampling speed if workers spend too much
      time waiting for algorithms to sample points. An algorithm will try sampling
      `pool_size` trials but may return less.
  max_trials: int, optional
      Maximum number of trials to execute within ``workon``. If the experiment or algorithm
      reach status is_done before, the execution of ``workon`` terminates.
      Defaults to experiment's max trial. If ``max_trials`` is larger than
      ``experiment.max_trials``, the experiment will stop when reaching
      ``experiment.max_trials``.
  max_trials_per_worker: int, optional
      Maximum number of trials to execute within each worker. ``max_trials`` and
      ``experiment.max_trials`` have precedence. Defaults to global config.
  max_broken: int, optional
      Maximum number of broken trials to accept during `workon`. When this threshold is
      reached the function will raise :class:`orion.core.utils.exceptions.BrokenExperiment`.
      Defaults to value of global config.
  trial_arg: str, optional
      The function ``fct`` may support receiving the trial as an argument. This argument name
      can be specified with ``trial_arg``. If not defined (``None``), then only the
      hyperparameters will be passed to `fct`.
  on_error: callable, optional
      Callback that is executed if an error occur during the execution of ``fct``.
      The signature of the callback must be
      ``foo(ExperimentClient, Trial, Error, nb_of_worker_broken_trials)``.
      If the callblack returns False, the error will be ignored, otherwise it is counted
      for the threshold `max_broken`. In case of critical errors, you may also directly
      raise an error and force break out of ``workon``.
  prepare_trial: callable, optional
      Callback that is executed before the trial is submitted to workers for execution.
      Default is `orion.client.runner.prepare_trial_working_dir` which will create working
      directory of trials if necessary.
  idle_timeout: int, optional
      Maximum time (seconds) allowed for idle workers. LazyWorkers will be raised if
      timeout is reached. Such timeout are generally caused when reaching the
      end of the optimization when no new trials can be sampled for the idle workers.
      Defaults to ``orion.core.config.worker.idle_timeout``.
  **kwargs
      Constant argument to pass to `fct` in addition to trial.params. If values in kwargs are
      present in trial.params, the latter takes precedence.
  
  Raises
  ------
  :class:`orion.core.utils.exceptions.LazyWorkers`
       If workers stay idle for too long.
  
  :class:`orion.core.utils.exceptions.InvalidResult`
       If results returned by `fct` have invalid format.
  
  :class:`orion.core.utils.exceptions.WaitingForTrials`
      If the experiment is not completed and algorithm needs to wait for some
      trials to complete before it can suggest new trials.
  
  :class:`orion.core.utils.exceptions.BrokenExperiment`
      If too many trials failed to run and the experiment cannot continue.
      This is determined by ``max_broken`` in the configuration of the experiment.
  
  :class:`orion.core.utils.exceptions.ReservationRaceCondition`
      If a trial could not be reserved right after they were generated.
  
  :class:`orion.core.utils.exceptions.UnsupportedOperation`
      If the experiment was not loaded in executable mode.
docstr_tok: ["Optimize","a","given","function","Experiment","must","be","in","executable","(","'","x","'",")","mode",".","Parameters","--","--","--","--","--","fct",":","callable","Function","to","optimize",".","Must","take","arguments","provided","by","trial.params",".","Additional","constant","parameter","can","be","passed","as","``","*","*","kwargs","``","to","`","workon","`",".","Function","must","return","the","final","objective",".","n_workers",":","int",",","optional","Number","of","workers","to","run","in","parallel",".","Defaults","to","value","of","global","config",".","pool_size",":","int",",","optional","Number","of","trials","to","sample","at","a","time",".","If","0",",","defaults","to","`","n_workers","`","or","value","of","global","config","if","defined",".","Increase","it","to","improve","the","sampling","speed","if","workers","spend","too","much","time","waiting","for","algorithms","to","sample","points",".","An","algorithm","will","try","sampling","`","pool_size","`","trials","but","may","return","less",".","max_trials",":","int",",","optional","Maximum","number","of","trials","to","execute","within","``","workon","``",".","If","the","experiment","or","algorithm","reach","status","is_done","before",",","the","execution","of","``","workon","``","terminates",".","Defaults","to","experiment","'s","max","trial",".","If","``","max_trials","``","is","larger","than","``","experiment.max_trials","``",",","the","experiment","will","stop","when","reaching","``","experiment.max_trials","``",".","max_trials_per_worker",":","int",",","optional","Maximum","number","of","trials","to","execute","within","each","worker",".","``","max_trials","``","and","``","experiment.max_trials","``","have","precedence",".","Defaults","to","global","config",".","max_broken",":","int",",","optional","Maximum","number","of","broken","trials","to","accept","during","`","workon","`",".","When","this","threshold","is","reached","the","function","will","raise",":","class",":","`","orion.core.utils.exceptions.BrokenExperiment","`",".","Defaults","to","value","of","global","config",".","trial_arg",":","str",",","optional","The","function","``","fct","``","may","support","receiving","the","trial","as","an","argument",".","This","argument","name","can","be","specified","with","``","trial_arg","``",".","If","not","defined","(","``","None","``",")",",","then","only","the","hyperparameters","will","be","passed","to","`","fct","`",".","on_error",":","callable",",","optional","Callback","that","is","executed","if","an","error","occur","during","the","execution","of","``","fct","``",".","The","signature","of","the","callback","must","be","``","foo","(","ExperimentClient",",","Trial",",","Error",",","nb_of_worker_broken_trials",")","``",".","If","the","callblack","returns","False",",","the","error","will","be","ignored",",","otherwise","it","is","counted","for","the","threshold","`","max_broken","`",".","In","case","of","critical","errors",",","you","may","also","directly","raise","an","error","and","force","break","out","of","``","workon","``",".","prepare_trial",":","callable",",","optional","Callback","that","is","executed","before","the","trial","is","submitted","to","workers","for","execution",".","Default","is","`","orion.client.runner.prepare_trial_working_dir","`","which","will","create","working","directory","of","trials","if","necessary",".","idle_timeout",":","int",",","optional","Maximum","time","(","seconds",")","allowed","for","idle","workers",".","LazyWorkers","will","be","raised","if","timeout","is","reached",".","Such","timeout","are","generally","caused","when","reaching","the","end","of","the","optimization","when","no","new","trials","can","be","sampled","for","the","idle","workers",".","Defaults","to","``","orion.core.config.worker.idle_timeout","``",".","*","*","kwargs","Constant","argument","to","pass","to","`","fct","`","in","addition","to","trial.params",".","If","values","in","kwargs","are","present","in","trial.params",",","the","latter","takes","precedence",".","Raises","--","--","--",":","class",":","`","orion.core.utils.exceptions.LazyWorkers","`","If","workers","stay","idle","for","too","long",".",":","class",":","`","orion.core.utils.exceptions.InvalidResult","`","If","results","returned","by","`","fct","`","have","invalid","format",".",":","class",":","`","orion.core.utils.exceptions.WaitingForTrials","`","If","the","experiment","is","not","completed","and","algorithm","needs","to","wait","for","some","trials","to","complete","before","it","can","suggest","new","trials",".",":","class",":","`","orion.core.utils.exceptions.BrokenExperiment","`","If","too","many","trials","failed","to","run","and","the","experiment","can","not","continue",".","This","is","determined","by","``","max_broken","``","in","the","configuration","of","the","experiment",".",":","class",":","`","orion.core.utils.exceptions.ReservationRaceCondition","`","If","a","trial","could","not","be","reserved","right","after","they","were","generated",".",":","class",":","`","orion.core.utils.exceptions.UnsupportedOperation","`","If","the","experiment","was","not","loaded","in","executable","mode","."]
code: def workon(
      self,
      fct: Callable,
      n_workers: int | None = None,
      pool_size: int = 0,
      max_trials: int | None = None,
      max_trials_per_worker: int | None = None,
      max_broken: int | None = None,
      trial_arg: str | None = None,
      on_error: Callable[[ExperimentClient, Exception, int], bool]
      | None = None,
      prepare_trial: Callable[
          [ExperimentClient, Trial], None
      ] = prepare_trial_working_dir,
      idle_timeout: int | None = None,
      **kwargs,
  ) -> int:
      """Optimize a given function
  
      Experiment must be in executable ('x') mode.
  
      Parameters
      ----------
      fct: callable
          Function to optimize. Must take arguments provided by trial.params. Additional constant
          parameter can be passed as ``**kwargs`` to `workon`. Function must return the final
          objective.
      n_workers: int, optional
          Number of workers to run in parallel. Defaults to value of global config.
      pool_size: int, optional
          Number of trials to sample at a time. If 0, defaults to `n_workers` or value of global
          config if defined.  Increase it to improve the sampling speed if workers spend too much
          time waiting for algorithms to sample points. An algorithm will try sampling
          `pool_size` trials but may return less.
      max_trials: int, optional
          Maximum number of trials to execute within ``workon``. If the experiment or algorithm
          reach status is_done before, the execution of ``workon`` terminates.
          Defaults to experiment's max trial. If ``max_trials`` is larger than
          ``experiment.max_trials``, the experiment will stop when reaching
          ``experiment.max_trials``.
      max_trials_per_worker: int, optional
          Maximum number of trials to execute within each worker. ``max_trials`` and
          ``experiment.max_trials`` have precedence. Defaults to global config.
      max_broken: int, optional
          Maximum number of broken trials to accept during `workon`. When this threshold is
          reached the function will raise :class:`orion.core.utils.exceptions.BrokenExperiment`.
          Defaults to value of global config.
      trial_arg: str, optional
          The function ``fct`` may support receiving the trial as an argument. This argument name
          can be specified with ``trial_arg``. If not defined (``None``), then only the
          hyperparameters will be passed to `fct`.
      on_error: callable, optional
          Callback that is executed if an error occur during the execution of ``fct``.
          The signature of the callback must be
          ``foo(ExperimentClient, Trial, Error, nb_of_worker_broken_trials)``.
          If the callblack returns False, the error will be ignored, otherwise it is counted
          for the threshold `max_broken`. In case of critical errors, you may also directly
          raise an error and force break out of ``workon``.
      prepare_trial: callable, optional
          Callback that is executed before the trial is submitted to workers for execution.
          Default is `orion.client.runner.prepare_trial_working_dir` which will create working
          directory of trials if necessary.
      idle_timeout: int, optional
          Maximum time (seconds) allowed for idle workers. LazyWorkers will be raised if
          timeout is reached. Such timeout are generally caused when reaching the
          end of the optimization when no new trials can be sampled for the idle workers.
          Defaults to ``orion.core.config.worker.idle_timeout``.
      **kwargs
          Constant argument to pass to `fct` in addition to trial.params. If values in kwargs are
          present in trial.params, the latter takes precedence.
  
      Raises
      ------
      :class:`orion.core.utils.exceptions.LazyWorkers`
           If workers stay idle for too long.
  
      :class:`orion.core.utils.exceptions.InvalidResult`
           If results returned by `fct` have invalid format.
  
      :class:`orion.core.utils.exceptions.WaitingForTrials`
          If the experiment is not completed and algorithm needs to wait for some
          trials to complete before it can suggest new trials.
  
      :class:`orion.core.utils.exceptions.BrokenExperiment`
          If too many trials failed to run and the experiment cannot continue.
          This is determined by ``max_broken`` in the configuration of the experiment.
  
      :class:`orion.core.utils.exceptions.ReservationRaceCondition`
          If a trial could not be reserved right after they were generated.
  
      :class:`orion.core.utils.exceptions.UnsupportedOperation`
          If the experiment was not loaded in executable mode.
  
      """
      self._check_if_executable()
  
      if n_workers is None:
          n_workers = self.executor.n_workers
      else:
          if n_workers > self.executor.n_workers:
              log.warning(
                  "The required number of workers %s is bigger than executor configuration %s",
                  str(n_workers),
                  str(self.executor.n_workers),
              )
  
      if not pool_size:
          pool_size = orion.core.config.worker.pool_size
      if not pool_size:
          pool_size = n_workers
  
      if not idle_timeout:
          idle_timeout = orion.core.config.worker.idle_timeout
  
      if max_trials is None:
          max_trials = self.max_trials
  
      if max_trials_per_worker is None:
          max_trials_per_worker = orion.core.config.worker.max_trials
  
      if max_broken is None:
          max_broken = orion.core.config.worker.max_broken
  
      # Use worker's max_trials inside `exp.is_done` to reduce chance of
      # race condition for trials creation
      assert self.max_trials is not None
      assert max_trials is not None
  
      if self.max_trials > max_trials:
          self._experiment.max_trials = max_trials
          assert self._experiment.algorithm is not None
          self._experiment.algorithm.max_trials = max_trials
  
      with SetupWorkingDir(self):
          runner = Runner(
              self,
              fct,
              pool_size=pool_size,
              idle_timeout=idle_timeout,
              max_trials_per_worker=max_trials_per_worker,
              max_broken=max_broken,
              trial_arg=trial_arg,
              on_error=on_error,
              prepare_trial=prepare_trial,
              n_workers=n_workers,
              **kwargs,
          )
  
          rval = runner.run()
  
      return rval
  
imports: from __future__ import annotations
  import inspect
  import logging
  import numbers
  import typing
  from contextlib import contextmanager
  from typing import Callable
  import orion.core
  from orion.algo.space import Space
  from orion.client.runner import Runner, prepare_trial_working_dir
  from orion.core.io.database import DuplicateKeyError
  from orion.core.utils.exceptions import BrokenExperiment, CompletedExperiment, ReservationRaceCondition, UnsupportedOperation, WaitingForTrials
  from orion.core.utils.format_trials import dict_to_trial
  from orion.core.utils.working_dir import SetupWorkingDir
  from orion.core.worker.experiment import AlgoT
  from orion.core.worker.producer import Producer
  from orion.core.worker.trial import AlreadyReleased, Trial, TrialCM
  from orion.core.worker.trial_pacemaker import TrialPacemaker
  from orion.executor.base import BaseExecutor, executor_factory
  from orion.plotting.base import PlotAccessor
  from orion.storage.base import FailedUpdate
label_desc: Use image node_id 35 for calling the ExperimentClient obj's underlying member method code with example usage: obj.workon(fct, n_workers, pool_size, max_trials, max_trials_per_worker, max_broken, trial_arg, on_error, prepare_trial, idle_timeout) and returns: rval