colosseum.config

  1import os
  2import shutil
  3from glob import glob
  4from typing import Type, TYPE_CHECKING, List
  5
  6from colosseum.benchmark import BENCHMARKS_DIRECTORY
  7from colosseum.utils import ensure_folder
  8
  9if TYPE_CHECKING:
 10    from colosseum.agent.agents.base import BaseAgent
 11
 12
 13# EXPERIMENT VARIABLES
 14EXPERIMENT_SEPARATOR_PRMS = "-"
 15EXPERIMENT_SEPARATOR_MDP_AGENT = "____"
 16
 17
 18# MULTIPROCESSING
 19_AVAILABLE_CORES = 1
 20
 21
 22def enable_multiprocessing():
 23    """
 24    sets the number of cores available to the number of cores in the machine minus two.
 25    """
 26    set_available_cores(os.cpu_count() - 2)
 27
 28
 29def disable_multiprocessing():
 30    """
 31    disables multiprocessing. Note that multiprocessing is disabled by default.
 32    """
 33    set_available_cores(1)
 34
 35
 36def set_available_cores(n: int):
 37    """
 38    sets the available core to n.
 39    """
 40    assert os.cpu_count() >= n >= 1, (
 41        f"The input value for the number of cores should be larger than zero and less than the number of cores in the "
 42        f"machine, {n} received."
 43    )
 44
 45    global _AVAILABLE_CORES
 46    n = (os.cpu_count() - 2) if n is None else n
 47    _AVAILABLE_CORES = n
 48
 49
 50def get_available_cores() -> int:
 51    """
 52    Returns
 53    -------
 54    int
 55        The number of cores available to the package.
 56    """
 57    return _AVAILABLE_CORES
 58
 59
 60# VERBOSITY
 61VERBOSE_LEVEL = 0
 62"""The level of verbose output."""
 63
 64
 65def enable_verbose_logging():
 66    """
 67    enables verbose loggings.
 68    """
 69    global VERBOSE_LEVEL
 70    VERBOSE_LEVEL = 1
 71
 72
 73def set_verbose_logs_file(file_path: str):
 74    """
 75    redirects verbose logging to the file in input.
 76    """
 77    _check_log_file_path(file_path)
 78    global VERBOSE_LEVEL
 79    VERBOSE_LEVEL = file_path
 80
 81
 82def disable_verbose_logging():
 83    """
 84    disables verbosity.
 85    """
 86    global VERBOSE_LEVEL
 87    VERBOSE_LEVEL = 0
 88
 89
 90# NUMERICAL VARIABLES
 91_N_FLOATING_SAMPLING_HYPERPARAMETERS = 4
 92_SIZE_NOISE_CACHE = 5000
 93_MIN_LINEAR_FEATURE_DIMENSIONALITY = 10
 94
 95
 96def set_n_floating_sampling_hyperparameters(n: int):
 97    """
 98    sets the number of floating points to keep when rounding float samples from the tune.ray hyperparameter spaces.
 99    By default, it is set to 4.
100    """
101    assert 1 < n < 10
102    global _N_FLOATING_SAMPLING_HYPERPARAMETERS
103    _N_FLOATING_SAMPLING_HYPERPARAMETERS = n
104
105
106def get_n_floating_sampling_hyperparameters() -> int:
107    """
108    Returns
109    -------
110    int
111        The number of floating points to keep when rounding float samples from the tune.ray hyperparameter spaces.
112    """
113    return _N_FLOATING_SAMPLING_HYPERPARAMETERS
114
115
116def set_size_cache_noise(x: int):
117    """
118    sets the size of the cached for the `Noise` objects. This reduces the computational burden of the noise sampling
119    procedure. By default, it is set to 5000.
120    """
121    global _SIZE_NOISE_CACHE
122    assert type(x) == int and x > 0
123    _SIZE_NOISE_CACHE = x
124
125
126def get_size_cache_noise() -> int:
127    """
128    Returns
129    -------
130    int
131        The size of the cached for the `Noise` objects.
132    """
133    return _SIZE_NOISE_CACHE
134
135
136def set_min_linear_feature_dim(x: int):
137    """
138    sets the minimum dimension for the `StateLinear` emission maps. By default, it is set to two.
139    """
140    global _MIN_LINEAR_FEATURE_DIMENSIONALITY
141    assert type(x) == int and x > 0
142    _MIN_LINEAR_FEATURE_DIMENSIONALITY = x
143
144
145def get_min_linear_feature_dim() -> int:
146    """
147    Returns
148    -------
149    int
150        The minimum dimension for the `StateLinear` emission maps.
151    """
152    return _MIN_LINEAR_FEATURE_DIMENSIONALITY
153
154
155# PATHS
156_HYPEROPT_FOLDER = "default_hyperopt" + os.sep + "hyperopt_experiments" + os.sep
157_EXPERIMENTS_FOLDER = "experiments" + os.sep
158_HARDNESS_MEASURES_CACHE_FOLDER = os.path.join("cached_hardness_measures", "")
159
160_HARDNESS_MEASURES_CACHE_FOLDER_COLOSSEUM = os.path.join(
161    BENCHMARKS_DIRECTORY, "cached_hardness_measures", ""
162)
163_HARDNESS_MDPS_CACHE_FOLDER_COLOSSEUM = os.path.join(
164    BENCHMARKS_DIRECTORY, "cached_mdps", ""
165)
166
167
168def get_cached_hardness_benchmark_folder() -> str:
169    """
170    Returns
171    -------
172    str
173        The folder where hardness of measures are cached.
174    """
175    return _HARDNESS_MEASURES_CACHE_FOLDER_COLOSSEUM
176
177
178def get_cached_mdps_benchmark_folder() -> str:
179    """
180    Returns
181    -------
182    str
183        The folder where the benchmark environments have been cached.
184    """
185    return _HARDNESS_MDPS_CACHE_FOLDER_COLOSSEUM
186
187
188def set_hyperopt_folder(experiment_folder: str, experiment_name: str):
189    """
190    sets the folder for the hyperparameters optimization procedure. The resulting folder has the following structure,
191    `experiment_folder/hyperopt/experiment_name`.
192
193    Parameters
194    ----------
195    experiment_folder : str
196        The folder for the results of the hyperparameters optimization procedure.
197    experiment_name : str
198        The name of the experiment related to the hyperparameter optimization procedure.
199    """
200    global _HYPEROPT_FOLDER
201    _HYPEROPT_FOLDER = (
202        ensure_folder(experiment_folder)
203        + "hyperopt"
204        + os.sep
205        + ensure_folder(experiment_name)
206    )
207    os.makedirs(_HYPEROPT_FOLDER, exist_ok=True)
208
209
210def get_hyperopt_folder() -> str:
211    """
212    Returns
213    -------
214    str
215        The folder for the hyperparameters optimization procedure.
216    """
217    return _HYPEROPT_FOLDER
218
219
220def set_experiments_folder(experiment_folder: str, experiment_name: str):
221    """
222    sets the folder for the results of the benchmarking procedure. The resulting folder has the following structure,
223    `experiment_folder/benchmarking/experiment_name`.
224
225    Parameters
226    ----------
227    experiment_folder : str
228        The folder for the results of the benchmarking procedure.
229    experiment_name : str
230        The name of the experiment related to the benchmarking procedure.
231    """
232    global _EXPERIMENTS_FOLDER
233    _EXPERIMENTS_FOLDER = (
234        ensure_folder(experiment_folder)
235        + "benchmarking"
236        + os.sep
237        + ensure_folder(experiment_name)
238    )
239    os.makedirs(_EXPERIMENTS_FOLDER, exist_ok=True)
240
241
242def get_experiments_folder() -> str:
243    """
244    Returns
245    -------
246    str
247        The folder for the results of the benchmarking procedure.
248    """
249    return _EXPERIMENTS_FOLDER
250
251
252def set_up_hardness_measures_cache_folder():
253    """
254    copies the cached measures of hardness from the colosseum package to the local hardness measures cache folder.
255    """
256
257    os.makedirs(_HARDNESS_MEASURES_CACHE_FOLDER, exist_ok=True)
258
259    # Copy the Colosseum cached hardness reports
260    SRC_DIR = BENCHMARKS_DIRECTORY + "cached_hardness_measures"
261    TARG_DIR = _HARDNESS_MEASURES_CACHE_FOLDER
262
263    for mdp_dir in os.listdir(SRC_DIR):
264        os.makedirs(TARG_DIR + os.sep + mdp_dir, exist_ok=True)
265        for file in glob(SRC_DIR + os.sep + mdp_dir + os.sep + "*"):
266            if os.path.basename(file) not in map(
267                os.path.basename, glob(os.path.join(TARG_DIR, mdp_dir + os.sep + "*"))
268            ):
269                shutil.copy(file, TARG_DIR + os.sep + mdp_dir)
270
271
272def set_hardness_measures_cache_folder(path: str):
273    """
274    sets the hardness measures cache folder to the path in input.
275    """
276    global _HARDNESS_MEASURES_CACHE_FOLDER
277    _HARDNESS_MEASURES_CACHE_FOLDER = ensure_folder(path)
278
279
280def get_hardness_measures_cache_folder() -> str:
281    """
282    Returns
283    -------
284    str
285        The hardness measures cache folder. Note that if the folder does not exist, it is created and filled with the
286        cached measures from the package.
287    """
288    if not os.path.isdir(_HARDNESS_MEASURES_CACHE_FOLDER):
289        set_up_hardness_measures_cache_folder()
290    return _HARDNESS_MEASURES_CACHE_FOLDER
291
292
293# AGENTS
294_REGISTERED_EXTERNAL_AGENT_CLASSES = list()
295
296
297def register_agent_class(agent_class: Type["BaseAgent"]):
298    """
299    makes the package knows that the agent class in input can be used for hyperparameters optimization and benchmarking.
300    """
301    _REGISTERED_EXTERNAL_AGENT_CLASSES.append(agent_class)
302
303
304def get_external_agent_classes() -> List[Type["BaseAgent"]]:
305    """
306    Returns
307    -------
308    List[Type["BaseAgent"]]
309        The agent classes that have been registered to the package.
310    """
311    return _REGISTERED_EXTERNAL_AGENT_CLASSES
312
313
314def _check_log_file_path(file_path: str):
315    assert ".txt", "The file extension should be txt."
316    if not os.path.isfile(file_path):
317        with open(file_path, "w") as f:
318            pass
319
320
321#### Work in progress
322
323_DEBUG_LEVEL = 0
324_DEBUG_FILE = None
325
326
327def process_debug_output(debug_output):
328    """
329    work in progress.
330    """
331    if _DEBUG_FILE:
332        with open(_DEBUG_FILE, "a") as f:
333            f.write(debug_output + "\n")
334    else:
335        if _DEBUG_LEVEL > 0:
336            print(debug_output)
337
338
339def set_debug_logs_file(file_path: str):
340    """
341    work in progress.
342    """
343    _check_log_file_path(file_path)
344    global _DEBUG_FILE, _DEBUG_LEVEL
345    _DEBUG_FILE = file_path
346    _DEBUG_LEVEL = 1
347
348
349def activate_debug():
350    """
351    work in progress.
352    """
353    set_debug_level(1)
354
355
356def set_debug_level(n: int):
357    """
358    work in progress.
359    """
360    global _DEBUG_LEVEL
361    _DEBUG_LEVEL = n
362
363
364def deactivate_debugs():
365    """
366    work in progress.
367    """
368    global _DEBUG_LEVEL, _DEBUG_FILE
369    if type(_DEBUG_FILE) == str and os.path.isfile(_DEBUG_FILE):
370        os.rmdir(_DEBUG_FILE)
371    _DEBUG_FILE = None
372    _DEBUG_LEVEL = 0