class_docstr: Represents an entry in database/experiments collection.
  
  Attributes
  ----------
  name: str
     Unique identifier for this experiment per ``user``.
  id: object
     id of the experiment in the database if experiment is configured. Value is ``None``
     if the experiment is not configured.
  refers: dict or list of `Experiment` objects, after initialization is done.
     A dictionary pointing to a past `Experiment` id, ``refers[parent_id]``, whose
     trials we want to add in the history of completed trials we want to re-use.
     For the purpose of convenience and database efficiency, all experiments of a common tree
     share a ``refers[root_id]``, with the root experiment referring to itself.
  version: int
      Current version of this experiment.
  metadata: dict
     Contains managerial information about this `Experiment`.
  max_trials: int
     How many trials must be evaluated, before considering this `Experiment` done.
     This attribute can be updated if the rest of the experiment configuration
     is the same. In that case, if trying to set to an already set experiment,
     it will overwrite the previous one.
  max_broken: int
     How many trials must be broken, before considering this `Experiment` broken.
     This attribute can be updated if the rest of the experiment configuration
     is the same. In that case, if trying to set to an already set experiment,
     it will overwrite the previous one.
  space: Space
     Object representing the optimization space.
  algorithm: `BaseAlgorithm` object or a wrapper.
     Complete specification of the optimization and dynamical procedures taking
     place in this `Experiment`.
  
  Notes
  -----
  
  The following list represents possible entries in the metadata dict.
  
  user: str
     System user currently owning this running process, the one who invoked **Oríon**.
  datetime: `datetime.datetime`
     When was this particular configuration submitted to the database.
  orion_version: str
     Version of **Oríon** which suggested this experiment. `user`'s current
     **Oríon** version.
  user_script: str
     Full absolute path to `user`'s executable.
  user_args: list of str
     Contains separate arguments to be passed when invoking `user_script`,
     possibly templated for **Oríon**.
  user_vcs: str, optional
     User's version control system for this executable's code repository.
  user_version: str, optional
     Current user's repository version.
  user_commit_hash: str, optional
     Current `Experiment`'s commit hash for **Oríon**'s invocation.
class_docstr_tok: ["Represents","an","entry","in","database\/experiments","collection",".","Attributes","--","--","--","--","--","name",":","str","Unique","identifier","for","this","experiment","per","``","user","``",".","id",":","object","id","of","the","experiment","in","the","database","if","experiment","is","configured",".","Value","is","``","None","``","if","the","experiment","is","not","configured",".","refers",":","dict","or","list","of","`","Experiment","`","objects",",","after","initialization","is","done",".","A","dictionary","pointing","to","a","past","`","Experiment","`","id",",","``","refers","[","parent_id","]","``",",","whose","trials","we","want","to","add","in","the","history","of","completed","trials","we","want","to","re-use",".","For","the","purpose","of","convenience","and","database","efficiency",",","all","experiments","of","a","common","tree","share","a","``","refers","[","root_id","]","``",",","with","the","root","experiment","referring","to","itself",".","version",":","int","Current","version","of","this","experiment",".","metadata",":","dict","Contains","managerial","information","about","this","`","Experiment","`",".","max_trials",":","int","How","many","trials","must","be","evaluated",",","before","considering","this","`","Experiment","`","done",".","This","attribute","can","be","updated","if","the","rest","of","the","experiment","configuration","is","the","same",".","In","that","case",",","if","trying","to","set","to","an","already","set","experiment",",","it","will","overwrite","the","previous","one",".","max_broken",":","int","How","many","trials","must","be","broken",",","before","considering","this","`","Experiment","`","broken",".","This","attribute","can","be","updated","if","the","rest","of","the","experiment","configuration","is","the","same",".","In","that","case",",","if","trying","to","set","to","an","already","set","experiment",",","it","will","overwrite","the","previous","one",".","space",":","Space","Object","representing","the","optimization","space",".","algorithm",":","`","BaseAlgorithm","`","object","or","a","wrapper",".","Complete","specification","of","the","optimization","and","dynamical","procedures","taking","place","in","this","`","Experiment","`",".","Notes","--","--","-","The","following","list","represents","possible","entries","in","the","metadata","dict",".","user",":","str","System","user","currently","owning","this","running","process",",","the","one","who","invoked","*","*","Or\u00edon","*","*",".","datetime",":","`","datetime.datetime","`","When","was","this","particular","configuration","submitted","to","the","database",".","orion_version",":","str","Version","of","*","*","Or\u00edon","*","*","which","suggested","this","experiment",".","`","user","`","'s","current","*","*","Or\u00edon","*","*","version",".","user_script",":","str","Full","absolute","path","to","`","user","`","'s","executable",".","user_args",":","list","of","str","Contains","separate","arguments","to","be","passed","when","invoking","`","user_script","`",",","possibly","templated","for","*","*","Or\u00edon","*","*",".","user_vcs",":","str",",","optional","User","'s","version","control","system","for","this","executable","'s","code","repository",".","user_version",":","str",",","optional","Current","user","'s","repository","version",".","user_commit_hash",":","str",",","optional","Current","`","Experiment","`","'s","commit","hash","for","*","*","Or\u00edon","*","*","'s","invocation","."]
docstr: Acquire lock on algorithm
  
  This method should be called using a ``with``-clause.
  
  The context manager returns the algorithm object with its state updated
  based on the state loaded from storage.
  
  Upon leaving the context manager, the new state of the algorithm is saved back
  to the storage before releasing the lock.
  
  Parameters
  ----------
  timeout: int, optional
      Timeout for the acquisition of the lock. If the lock is not
      obtained before ``timeout``, then ``LockAcquisitionTimeout`` is raised.
      The timeout is only for the acquisition of the lock.
      Once the lock is obtained, it is valid until the context manager is closed.
      Default: 600.
  retry_interval: int, optional
      Sleep time between each attempts at acquiring the lock. Default: 1
  
  Raises
  ------
  ``RuntimeError``
      The algorithm configuration is different then the one during last execution of that
      same experiment.
  ``orion.storage.base.LockAcquisitionTimeout``
      The lock could not be obtained in less than ``timeout`` seconds.
docstr_tok: ["Acquire","lock","on","algorithm","This","method","should","be","called","using","a","``","with","``","-clause",".","The","context","manager","returns","the","algorithm","object","with","its","state","updated","based","on","the","state","loaded","from","storage",".","Upon","leaving","the","context","manager",",","the","new","state","of","the","algorithm","is","saved","back","to","the","storage","before","releasing","the","lock",".","Parameters","--","--","--","--","--","timeout",":","int",",","optional","Timeout","for","the","acquisition","of","the","lock",".","If","the","lock","is","not","obtained","before","``","timeout","``",",","then","``","LockAcquisitionTimeout","``","is","raised",".","The","timeout","is","only","for","the","acquisition","of","the","lock",".","Once","the","lock","is","obtained",",","it","is","valid","until","the","context","manager","is","closed",".","Default",":","600.","retry_interval",":","int",",","optional","Sleep","time","between","each","attempts","at","acquiring","the","lock",".","Default",":","1","Raises","--","--","--","``","RuntimeError","``","The","algorithm","configuration","is","different","then","the","one","during","last","execution","of","that","same","experiment",".","``","orion.storage.base.LockAcquisitionTimeout","``","The","lock","could","not","be","obtained","in","less","than","``","timeout","``","seconds","."]
code: def acquire_algorithm_lock(
      self, timeout: int | float = 60, retry_interval: int | float = 1
  ) -> Generator[AlgoT, None, None]:
      """Acquire lock on algorithm
  
      This method should be called using a ``with``-clause.
  
      The context manager returns the algorithm object with its state updated
      based on the state loaded from storage.
  
      Upon leaving the context manager, the new state of the algorithm is saved back
      to the storage before releasing the lock.
  
      Parameters
      ----------
      timeout: int, optional
          Timeout for the acquisition of the lock. If the lock is not
          obtained before ``timeout``, then ``LockAcquisitionTimeout`` is raised.
          The timeout is only for the acquisition of the lock.
          Once the lock is obtained, it is valid until the context manager is closed.
          Default: 600.
      retry_interval: int, optional
          Sleep time between each attempts at acquiring the lock. Default: 1
  
      Raises
      ------
      ``RuntimeError``
          The algorithm configuration is different then the one during last execution of that
          same experiment.
      ``orion.storage.base.LockAcquisitionTimeout``
          The lock could not be obtained in less than ``timeout`` seconds.
      """
  
      self._check_if_writable()
  
      with self._storage.acquire_algorithm_lock(
          experiment=self,
          timeout=timeout,
          retry_interval=retry_interval,
      ) as locked_algorithm_state:
          assert self.algorithm is not None
          if (
              locked_algorithm_state.configuration
              != self.algorithm.configuration
          ):
              log.warning(
                  "Saved configuration: %s",
                  locked_algorithm_state.configuration,
              )
              log.warning(
                  "Current configuration: %s %s",
                  self.algorithm.configuration,
                  self._storage._db,
              )
              raise RuntimeError(
                  "Algorithm configuration changed since last experiment execution. "
                  "Algorithm cannot be resumed with a different configuration. "
              )
  
          if locked_algorithm_state.state:
              self.algorithm.set_state(locked_algorithm_state.state)
  
          yield self.algorithm
  
          locked_algorithm_state.set_state(self.algorithm.state_dict)
  
imports: from __future__ import annotations
  import contextlib
  import copy
  import dataclasses
  import datetime
  import inspect
  import logging
  import math
  import typing
  from collections import Counter
  from dataclasses import dataclass, field
  from typing import Generator, Generic, Literal, TypeVar
  import pandas
  from orion.algo.base import BaseAlgorithm
  from orion.algo.space import Space
  from orion.core.evc.adapters import BaseAdapter
  from orion.core.evc.experiment import ExperimentNode
  from orion.core.io.database import DuplicateKeyError
  from orion.core.utils.exceptions import UnsupportedOperation
  from orion.core.utils.flatten import flatten
  from orion.core.worker.experiment_config import ExperimentConfig
  from orion.storage.base import BaseStorageProtocol, FailedUpdate
label_desc: Use image node_id 17 for calling the Experiment obj's underlying member method code with example usage: obj.acquire_algorithm_lock(timeout, retry_interval) without return types