Source code for smac.runhistory.runhistory

import collections
from enum import Enum
import json
import typing

import numpy as np

from smac.configspace import Configuration, ConfigurationSpace
from smac.tae import StatusType
from smac.utils.logging import PickableLoggerAdapter

__author__ = "Marius Lindauer"
__copyright__ = "Copyright 2015, ML4AAD"
__license__ = "3-clause BSD"
__maintainer__ = "Marius Lindauer"
__email__ = "lindauer@cs.uni-freiburg.de"
__version__ = "0.0.1"


# NOTE class instead of collection to have a default value for budget in RunKey
[docs]class RunKey(collections.namedtuple('RunKey', ['config_id', 'instance_id', 'seed', 'budget'])): __slots__ = () def __new__( cls, # No type annotation because the 1st argument for a namedtuble is always the class type, # see https://docs.python.org/3/reference/datamodel.html#object.__new__ config_id: int, instance_id: typing.Optional[str], seed: typing.Optional[int], budget: float = 0.0, ) -> 'RunKey': return super().__new__(cls, config_id, instance_id, seed, budget)
# NOTE class instead of collection to have a default value for budget/source_id in RunInfo
[docs]class RunInfo( collections.namedtuple( 'RunInfo', ['config', 'instance', 'instance_specific', 'seed', 'cutoff', 'capped', 'budget', 'source_id'] ) ): __slots__ = () def __new__( cls, # No type annotation because the 1st argument for a namedtuble is always the class type, # see https://docs.python.org/3/reference/datamodel.html#object.__new__ config: Configuration, instance: typing.Optional[str], instance_specific: str, seed: int, cutoff: typing.Optional[float], capped: bool, budget: float = 0.0, # In the context of parallel runs, one will have multiple suppliers of # configurations. source_id is a new mechanism to track what entity launched # this configuration source_id: int = 0, ) -> 'RunInfo': return super().__new__(cls, config, instance, instance_specific, seed, cutoff, capped, budget, source_id)
InstSeedKey = collections.namedtuple( 'InstSeedKey', ['instance', 'seed']) InstSeedBudgetKey = collections.namedtuple( 'InstSeedBudgetKey', ['instance', 'seed', 'budget']) RunValue = collections.namedtuple( 'RunValue', ['cost', 'time', 'status', 'starttime', 'endtime', 'additional_info'])
[docs]class EnumEncoder(json.JSONEncoder): """Custom encoder for enum-serialization (implemented for StatusType from tae). Using encoder implied using object_hook as defined in StatusType to deserialize from json. """
[docs] def default(self, obj: object) -> typing.Any: if isinstance(obj, StatusType): return {"__enum__": str(obj)} return json.JSONEncoder.default(self, obj)
[docs]class DataOrigin(Enum): """ Definition of how data in the runhistory is used. * ``INTERNAL``: internal data which was gathered during the current optimization run. It will be saved to disk, used for building EPMs and during intensify. * ``EXTERNAL_SAME_INSTANCES``: external data, which was gathered by running another program on the same instances as the current optimization run runs on (for example pSMAC). It will not be saved to disk, but used both for EPM building and during intensify. * ``EXTERNAL_DIFFERENT_INSTANCES``: external data, which was gathered on a different instance set as the one currently used, but due to having the same instance features can still provide useful information. Will not be saved to disk and only used for EPM building. """ INTERNAL = 1 EXTERNAL_SAME_INSTANCES = 2 EXTERNAL_DIFFERENT_INSTANCES = 3
[docs]class RunHistory(object): """Container for target algorithm run information. Most importantly, the runhistory contains an efficient mapping from each evaluated configuration to the empirical cost observed on either the full instance set or a subset. The cost is the average over all observed costs for one configuration: * If using budgets for a single instance, only the cost on the highest observed budget is returned. * If using instances as the budget, the average cost over all evaluated instances is returned. * Theoretically, the runhistory object can handle instances and budgets at the same time. This is neither used nor tested. * Capped runs are not included in this cost. Note ---- Guaranteed to be picklable. Attributes ---------- data : collections.OrderedDict() TODO config_ids : dict Maps config -> id ids_config : dict Maps id -> config num_runs_per_config : dict Maps config_id -> number of runs Parameters ---------- overwrite_existing_runs : bool (default=True) If set to ``True`` and a run of a configuration on an instance-budget-seed-pair already exists, it is overwritten. """ def __init__( self, overwrite_existing_runs: bool = False ) -> None: """Constructor Parameters ---------- overwrite_existing_runs: bool allows to overwrites old results if pairs of algorithm-instance-seed were measured multiple times """ self.logger = PickableLoggerAdapter( self.__module__ + "." + self.__class__.__name__ ) # By having the data in a deterministic order we can do useful tests # when we serialize the data and can assume it's still in the same # order as it was added. self.data = collections.OrderedDict() # type: typing.Dict[RunKey, RunValue] # for fast access, we have also an unordered data structure # to get all instance seed pairs of a configuration. # This does not include capped runs. self._configid_to_inst_seed_budget = {} # type: typing.Dict[int, typing.Dict[InstSeedKey, typing.List[float]]] self.config_ids = {} # type: typing.Dict[Configuration, int] self.ids_config = {} # type: typing.Dict[int, Configuration] self._n_id = 0 # Stores cost for each configuration ID self._cost_per_config = {} # type: typing.Dict[int, float] # Stores min cost across all budgets for each configuration ID self._min_cost_per_config = {} # type: typing.Dict[int, float] # runs_per_config maps the configuration ID to the number of runs for that configuration # and is necessary for computing the moving average self.num_runs_per_config = {} # type: typing.Dict[int, int] # Store whether a datapoint is "external", which means it was read from # a JSON file. Can be chosen to not be written to disk self.external = {} # type: typing.Dict[RunKey, DataOrigin] self.overwrite_existing_runs = overwrite_existing_runs
[docs] def add( self, config: Configuration, cost: float, time: float, status: StatusType, instance_id: typing.Optional[str] = None, seed: typing.Optional[int] = None, budget: float = 0.0, starttime: float = 0.0, endtime: float = 0.0, additional_info: typing.Optional[typing.Dict] = None, origin: DataOrigin = DataOrigin.INTERNAL, force_update: bool = False, ) -> None: """Adds a data of a new target algorithm (TA) run; it will update data if the same key values are used (config, instance_id, seed) Parameters ---------- config : dict (or other type -- depending on config space module) Parameter configuration cost: float Cost of TA run (will be minimized) time: float Runtime of TA run status: str Status in {SUCCESS, TIMEOUT, CRASHED, ABORT, MEMOUT} instance_id: str String representing an instance (default: None) seed: int Random seed used by TA (default: None) budget: float budget (cutoff) used in intensifier to limit TA (default: 0) starttime: float starting timestamp of TA evaluation endtime: float ending timestamp of TA evaluation additional_info: dict Additional run infos (could include further returned information from TA or fields such as start time and host_id) origin: DataOrigin Defines how data will be used. force_update: bool (default: False) Forces the addition of a config to the history """ if config is None: raise TypeError('Configuration to add to the runhistory must not be None') elif not isinstance(config, Configuration): raise TypeError( 'Configuration to add to the runhistory is not of type Configuration, but %s' % type(config) ) # Get the config id config_id_tmp = self.config_ids.get(config) if config_id_tmp is None: self._n_id += 1 self.config_ids[config] = self._n_id config_id = typing.cast(int, self.config_ids.get(config)) self.ids_config[self._n_id] = config else: config_id = typing.cast(int, config_id_tmp) # Construct keys and values for the data dictionary k = RunKey(config_id, instance_id, seed, budget) v = RunValue(cost, time, status, starttime, endtime, additional_info) # Each runkey is supposed to be used only once. Repeated tries to add # the same runkey will be ignored silently if not capped. if self.overwrite_existing_runs or force_update or self.data.get(k) is None: self._add(k, v, status, origin) elif status != StatusType.CAPPED and self.data[k].status == StatusType.CAPPED: # overwrite capped runs with uncapped runs self._add(k, v, status, origin) elif status == StatusType.CAPPED and self.data[k].status == StatusType.CAPPED and cost > self.data[k].cost: # overwrite if censored with a larger cutoff self._add(k, v, status, origin)
[docs] def _add(self, k: RunKey, v: RunValue, status: StatusType, origin: DataOrigin) -> None: """Actual function to add new entry to data structures TODO """ self.data[k] = v self.external[k] = origin # Capped data is added above # Do not register the cost until the run has completed if origin in (DataOrigin.INTERNAL, DataOrigin.EXTERNAL_SAME_INSTANCES) \ and status not in [StatusType.CAPPED, StatusType.RUNNING]: # also add to fast data structure is_k = InstSeedKey(k.instance_id, k.seed) self._configid_to_inst_seed_budget[k.config_id] = self._configid_to_inst_seed_budget.get(k.config_id, {}) if is_k not in self._configid_to_inst_seed_budget[k.config_id].keys(): # add new inst-seed-key with budget to main dict self._configid_to_inst_seed_budget[k.config_id][is_k] = [k.budget] elif k.budget not in is_k: # append new budget to existing inst-seed-key dict self._configid_to_inst_seed_budget[k.config_id][is_k].append(k.budget) # if budget is used, then update cost instead of incremental updates if not self.overwrite_existing_runs and k.budget == 0: # assumes an average across runs as cost function aggregation, this is used for algorithm configuration # (incremental updates are used to save time as getting the cost for > 100 instances is high) self.incremental_update_cost(self.ids_config[k.config_id], v.cost) else: # this is when budget > 0 (only successive halving and hyperband so far) self.update_cost(config=self.ids_config[k.config_id]) if k.budget > 0: if self.num_runs_per_config[k.config_id] != 1: # This is updated in update_cost raise ValueError('This should not happen!')
[docs] def update_cost(self, config: Configuration) -> None: """Store the performance of a configuration across the instances in self.cost_per_config and also updates self.runs_per_config; Note ---- This method ignores capped runs. Parameters ---------- config: Configuration configuration to update cost based on all runs in runhistory """ config_id = self.config_ids[config] # removing duplicates while keeping the order inst_seed_budgets = list(dict.fromkeys(self.get_runs_for_config(config, only_max_observed_budget=True))) self._cost_per_config[config_id] = self.average_cost(config, inst_seed_budgets) self.num_runs_per_config[config_id] = len(inst_seed_budgets) all_inst_seed_budgets = list(dict.fromkeys(self.get_runs_for_config(config, only_max_observed_budget=False))) self._min_cost_per_config[config_id] = self.min_cost(config, all_inst_seed_budgets)
[docs] def incremental_update_cost(self, config: Configuration, cost: float) -> None: """Incrementally updates the performance of a configuration by using a moving average; Parameters ---------- config: Configuration configuration to update cost based on all runs in runhistory cost: float cost of new run of config """ config_id = self.config_ids[config] n_runs = self.num_runs_per_config.get(config_id, 0) old_cost = self._cost_per_config.get(config_id, 0.) self._cost_per_config[config_id] = ((old_cost * n_runs) + cost) / (n_runs + 1) self.num_runs_per_config[config_id] = n_runs + 1
[docs] def get_cost(self, config: Configuration) -> float: """Returns empirical cost for a configuration. See the class docstring for how the costs are computed. The costs are not re-computed, but are read from cache. Parameters ---------- config: Configuration Returns ------- cost: float Computed cost for configuration """ config_id = self.config_ids.get(config) return self._cost_per_config.get(config_id, np.nan) # type: ignore[arg-type] # noqa F821
[docs] def get_runs_for_config(self, config: Configuration, only_max_observed_budget: bool) -> typing.List[InstSeedBudgetKey]: """Return all runs (instance seed pairs) for a configuration. Note ---- This method ignores capped runs. Parameters ---------- config : Configuration from ConfigSpace Parameter configuration only_max_observed_budget : bool Select only the maximally observed budget run for this configuration Returns ------- instance_seed_budget_pairs : list<tuples of instance, seed, budget> """ config_id = self.config_ids.get(config) runs = self._configid_to_inst_seed_budget.get(config_id, {}).copy() # type: ignore[arg-type] # noqa F821 # select only the max budget run if specified if only_max_observed_budget: for k, v in runs.items(): runs[k] = [max(v)] # convert to inst-seed-budget key rval = [InstSeedBudgetKey(k.instance, k.seed, budget) for k, v in runs.items() for budget in v] return rval
[docs] def get_all_configs(self) -> typing.List[Configuration]: """Return all configurations in this RunHistory object Returns ------- parameter configurations: list """ return list(self.config_ids.keys())
[docs] def get_all_configs_per_budget( self, budget_subset: typing.Optional[typing.List] = None, ) -> typing.List[Configuration]: """ Return all configs in this RunHistory object that have been run on one of these budgets Parameter --------- budget_subset: list Returns ------- parameter configurations: list """ if budget_subset is None: return self.get_all_configs() configs = [] for c, i, s, b in self.data.keys(): if b in budget_subset: configs.append(self.ids_config[c]) return configs
[docs] def get_min_cost(self, config: Configuration) -> float: """Returns the lowest empirical cost for a configuration, across all runs (budgets) See the class docstring for how the costs are computed. The costs are not re-computed, but are read from cache. Parameters ---------- config: Configuration Returns ------- min_cost: float Computed cost for configuration """ config_id = self.config_ids.get(config) return self._min_cost_per_config.get(config_id, np.nan) # type: ignore[arg-type] # noqa F821
[docs] def empty(self) -> bool: """Check whether or not the RunHistory is empty. Returns ------- emptiness: bool True if runs have been added to the RunHistory, False otherwise """ return len(self.data) == 0
[docs] def save_json(self, fn: str = "runhistory.json", save_external: bool = False) -> None: """ saves runhistory on disk Parameters ---------- fn : str file name save_external : bool Whether to save external data in the runhistory file. """ data = [([int(k.config_id), str(k.instance_id) if k.instance_id is not None else None, int(k.seed), float(k.budget) if k[3] is not None else 0], list(v)) for k, v in self.data.items() if save_external or self.external[k] == DataOrigin.INTERNAL] config_ids_to_serialize = set([entry[0][0] for entry in data]) configs = {id_: conf.get_dictionary() for id_, conf in self.ids_config.items() if id_ in config_ids_to_serialize} config_origins = {id_: conf.origin for id_, conf in self.ids_config.items() if (id_ in config_ids_to_serialize and conf.origin is not None)} with open(fn, "w") as fp: json.dump({"data": data, "config_origins": config_origins, "configs": configs}, fp, cls=EnumEncoder, indent=2)
[docs] def load_json(self, fn: str, cs: ConfigurationSpace) -> None: """Load and runhistory in json representation from disk. Overwrites current runhistory! Parameters ---------- fn : str file name to load from cs : ConfigSpace instance of configuration space """ try: with open(fn) as fp: all_data = json.load(fp, object_hook=StatusType.enum_hook) except Exception as e: self.logger.warning( 'Encountered exception %s while reading runhistory from %s. ' 'Not adding any runs!', e, fn, ) return config_origins = all_data.get("config_origins", {}) self.ids_config = { int(id_): Configuration( cs, values=values, origin=config_origins.get(id_, None) ) for id_, values in all_data["configs"].items() } self.config_ids = {config: id_ for id_, config in self.ids_config.items()} self._n_id = len(self.config_ids) # important to use add method to use all data structure correctly for k, v in all_data["data"]: self.add(config=self.ids_config[int(k[0])], cost=float(v[0]), time=float(v[1]), status=StatusType(v[2]), instance_id=k[1], seed=int(k[2]), budget=float(k[3]) if len(k) == 4 else 0, starttime=v[3], endtime=v[4], additional_info=v[5])
[docs] def update_from_json( self, fn: str, cs: ConfigurationSpace, origin: DataOrigin = DataOrigin.EXTERNAL_SAME_INSTANCES, ) -> None: """Update the current runhistory by adding new runs from a json file. Parameters ---------- fn : str File name to load from. cs : ConfigSpace Instance of configuration space. origin : DataOrigin What to store as data origin. """ new_runhistory = RunHistory() new_runhistory.load_json(fn, cs) self.update(runhistory=new_runhistory, origin=origin)
[docs] def update( self, runhistory: 'RunHistory', origin: DataOrigin = DataOrigin.EXTERNAL_SAME_INSTANCES, ) -> None: """Update the current runhistory by adding new runs from a RunHistory. Parameters ---------- runhistory: RunHistory Runhistory with additional data to be added to self origin: DataOrigin If set to ``INTERNAL`` or ``EXTERNAL_FULL`` the data will be added to the internal data structure self._configid_to_inst_seed_budget and be available :meth:`through get_runs_for_config`. """ # Configurations might be already known, but by a different ID. This # does not matter here because the add() method handles this # correctly by assigning an ID to unknown configurations and re-using # the ID for key, value in runhistory.data.items(): config_id, instance_id, seed, budget = key cost, time, status, start, end, additional_info = value config = runhistory.ids_config[config_id] self.add(config=config, cost=cost, time=time, status=status, instance_id=instance_id, starttime=start, endtime=end, seed=seed, budget=budget, additional_info=additional_info, origin=origin)
[docs] def _cost( self, config: Configuration, instance_seed_budget_keys: typing.Optional[typing.Iterable[InstSeedBudgetKey]] = None, ) -> typing.List[float]: """Return array of all costs for the given config for further calculations. Parameters ---------- config : Configuration Configuration to calculate objective for instance_seed_budget_keys : list, optional (default=None) List of tuples of instance-seeds-budget keys. If None, the run_history is queried for all runs of the given configuration. Returns ------- Costs: list Array of all costs """ try: id_ = self.config_ids[config] except KeyError: # challenger was not running so far return [] if instance_seed_budget_keys is None: instance_seed_budget_keys = self.get_runs_for_config(config, only_max_observed_budget=True) costs = [] for i, r, b in instance_seed_budget_keys: k = RunKey(id_, i, r, b) costs.append(self.data[k].cost) return costs
[docs] def average_cost( self, config: Configuration, instance_seed_budget_keys: typing.Optional[typing.Iterable[InstSeedBudgetKey]] = None, ) -> float: """Return the average cost of a configuration. This is the mean of costs of all instance-seed pairs. Parameters ---------- config : Configuration Configuration to calculate objective for instance_seed_budget_keys : list, optional (default=None) List of tuples of instance-seeds-budget keys. If None, the run_history is queried for all runs of the given configuration. Returns ---------- Cost: float Average cost """ costs = self._cost(config, instance_seed_budget_keys) if costs: return float(np.mean(costs)) return np.nan
[docs] def sum_cost( self, config: Configuration, instance_seed_budget_keys: typing.Optional[typing.Iterable[InstSeedBudgetKey]] = None, ) -> float: """Return the sum of costs of a configuration. This is the sum of costs of all instance-seed pairs. Parameters ---------- config : Configuration Configuration to calculate objective for instance_seed_budget_keys : list, optional (default=None) List of tuples of instance-seeds-budget keys. If None, the run_history is queried for all runs of the given configuration. Returns ---------- sum_cost: float Sum of costs of config """ return float(np.sum(self._cost(config, instance_seed_budget_keys)))
[docs] def min_cost( self, config: Configuration, instance_seed_budget_keys: typing.Optional[typing.Iterable[InstSeedBudgetKey]] = None, ) -> float: """Return the minimum cost of a configuration This is the minimum cost of all instance-seed pairs. Parameters ---------- config : Configuration Configuration to calculate objective for instance_seed_budget_keys : list, optional (default=None) List of tuples of instance-seeds-budget keys. If None, the run_history is queried for all runs of the given configuration. Returns ---------- min_cost: float minimum cost of config """ costs = self._cost(config, instance_seed_budget_keys) if costs: return float(np.min(costs)) return np.nan
[docs] def compute_all_costs(self, instances: typing.Optional[typing.List[str]] = None) -> None: """Computes the cost of all configurations from scratch and overwrites self.cost_perf_config and self.runs_per_config accordingly; Note ---- This method is only used for ``merge_foreign_data`` and should be removed. Parameters ---------- instances: typing.List[str] list of instances; if given, cost is only computed wrt to this instance set """ self._cost_per_config = {} self.num_runs_per_config = {} for config, config_id in self.config_ids.items(): # removing duplicates while keeping the order inst_seed_budgets = list(dict.fromkeys(self.get_runs_for_config(config, only_max_observed_budget=True))) if instances is not None: inst_seed_budgets = list( filter( lambda x: x.instance in typing.cast(typing.List, instances), inst_seed_budgets ) ) if inst_seed_budgets: # can be empty if never saw any runs on <instances> self._cost_per_config[config_id] = self.average_cost(config, inst_seed_budgets) self._min_cost_per_config[config_id] = self.min_cost(config, inst_seed_budgets) self.num_runs_per_config[config_id] = len(inst_seed_budgets)
[docs] def get_instance_costs_for_config(self, config: Configuration) -> typing.Dict[str, typing.List[float]]: """ Returns the average cost per instance (across seeds) for a configuration If the runhistory contains budgets, only the highest budget for a configuration is returned. Note ---- This is used by the pSMAC facade to determine the incumbent after the evaluation. Parameters ---------- config : Configuration from ConfigSpace Parameter configuration Returns ------- cost_per_inst: dict<instance name<str>, cost<float>> """ runs_ = self.get_runs_for_config(config, only_max_observed_budget=True) cost_per_inst = {} # type: typing.Dict[str, typing.List[float]] for inst, seed, budget in runs_: cost_per_inst[inst] = cost_per_inst.get(inst, []) rkey = RunKey(self.config_ids[config], inst, seed, budget) vkey = self.data[rkey] cost_per_inst[inst].append(vkey.cost) cost_per_inst = dict([(inst, np.mean(costs)) for inst, costs in cost_per_inst.items()]) return cost_per_inst