Wrapper Utility Tools#

Utility tools for to ease model wrapping.

Overview Information Here: boa.wrappers

boa.wrappers.wrapper_utils.cd_and_cd_back(path: PathLike = None)[source]#

Context manager that will return to the starting directory when the context manager exits, regardless of what directory changes happen between start and end.

Parameters: path (PathLike) – If supplied, will change directory to this path at the start of the context manager (it will “cd” to this path before “cd” back to the original directory)

Examples

>>> starting_dir = os.getcwd()
>>> with cd_and_cd_back():
...     # with do some things that change the directory
...     os.chdir("..")
... # When we exit the context manager (dedent) we go back to the starting directory
>>> ending_dir = os.getcwd()
>>> assert starting_dir == ending_dir

>>> starting_dir = os.getcwd()
>>> path_to_change_to = ".."
>>> with cd_and_cd_back(path=path_to_change_to):
...     # with do some things inside the context manager
...     pass
... # When we exit the context manager (dedent) we go back to the starting directory
>>> ending_dir = os.getcwd()
>>> assert starting_dir == ending_dir

boa.wrappers.wrapper_utils.cd_and_cd_back_dec(path: Optional[PathLike] = None)[source]#

Same as cd_and_cd_back() except as a function decorator instead of a context manager.

Parameters: path (Optional[PathLike]) – If supplied, will change directory to this path at the start of the function run (it will “cd” to this path before “cd” back to the original directory)

Examples

>>> @cd_and_cd_back_dec()
... def foo():
...     os.chdir("..")

>>> starting_dir = os.getcwd()
>>> foo()
>>> ending_dir = os.getcwd()
>>> assert starting_dir == ending_dir

>>> @cd_and_cd_back_dec(path="..")
... def bar():
...     os.chdir("..")

>>> starting_dir = os.getcwd()
>>> bar()
>>> ending_dir = os.getcwd()
>>> assert starting_dir == ending_dir

boa.wrappers.wrapper_utils.initialize_wrapper(wrapper: Type[BaseWrapper] | PathLike, append_timestamp: bool = None, experiment_dir: PathLike = None, wrapper_name: str = 'Wrapper', post_init_attrs: dict = None, **kwargs)[source]#

Parameters

wrapper (Type[BaseWrapper] | PathLike) –
append_timestamp (bool) –
experiment_dir (PathLike) –
wrapper_name (str) –
post_init_attrs (dict) –

boa.wrappers.wrapper_utils.split_shell_command(cmd: str)[source]#

split shell command for passing to python subproccess. This should correctly split commands like “echo ‘Hello, World!’” to [‘echo’, ‘Hello, World!’] (2 items) and not [‘echo’, “‘Hello,”, “World!’”] (3 items)

It also works for posix and windows systems appropriately

Parameters: cmd (str) –

boa.wrappers.wrapper_utils.load_json(file: PathLike, **kwargs) → dict[source]#

Read experiment configuration file for setting up the optimization. The configuration file contains the list of parameters, and whether each parameter is a fixed parameter or a range parameter. Fixed parameters have a value specified, and range parameters have a range specified.

Parameters

file (PathLike) – File path for the experiment configuration file
kwargs – variables to pass to boa.template.render_template_from_path() for rendering in your loaded file

Return type

dict

Examples

config_path = Path(“path/to/your/config.json_or_yaml”) config = load_jsonlike(config_path)

Returns: loaded_configs
Return type: dict
Parameters: file (PathLike) –

boa.wrappers.wrapper_utils.load_json_from_str(string: str, render_jinja: bool = True, **kwargs)[source]#

Load json from a string with optional jinja2 templating

Parameters

string (str) –
render_jinja (bool) –

boa.wrappers.wrapper_utils.load_yaml(file: PathLike, **kwargs) → dict[source]#

Parameters

file (PathLike) – File path for the experiment configuration file
kwargs – variables to pass to boa.template.render_template_from_path() for rendering in your loaded file

Return type

dict

Examples

config_path = Path(“path/to/your/config.json_or_yaml”) config = load_jsonlike(config_path)

Returns: loaded_configs
Return type: dict
Parameters: file (PathLike) –

boa.wrappers.wrapper_utils.load_yaml_from_str(string: str, render_jinja: bool = True, **kwargs)[source]#

Load yaml from a string with jinja2 optional templating

Parameters

string (str) –
render_jinja (bool) –

boa.wrappers.wrapper_utils.load_jsonlike(file: PathLike, **kwargs) → dict[source]#

Parameters

file (PathLike) – File path for the experiment configuration file
kwargs – variables to pass to boa.template.render_template_from_path() for rendering in your loaded file

Return type

dict

Examples

config_path = Path(“path/to/your/config.json_or_yaml”) config = load_jsonlike(config_path)

Returns: loaded_configs
Return type: dict
Parameters: file (PathLike) –

boa.wrappers.wrapper_utils.get_dt_now_as_str(fmt: str = '%Y%m%dT%H%M%S') → str[source]#

get the datetime as now as a str.

fmtstr: Default format is file friendly. See strftime documentation for more information on choices.

Parameters: fmt (str) –
Return type: str

boa.wrappers.wrapper_utils.make_experiment_dir(output_dir: Optional[PathLike] = None, experiment_dir: Optional[PathLike] = None, experiment_name: str = '', append_timestamp: bool = True, exist_ok: bool = False, **kwargs)[source]#

Creates directory for the experiment and returns the path. The directory is named with the experiment name and the current datetime.

Parameters

output_dir (Optional[PathLike]) – Output directory, the parent directory where the experiment directory will be written. Specify either an output directory and an experiment name or an experiment_dir
experiment_dir (Optional[PathLike]) – The exact dir the experiment directory boa will use to write the runs to. Specify either a output directory and an experiment name or an experiment_dir
experiment_name (str) – Name of the experiment
append_timestamp (bool) – Whether to append a timestamp to the end of the experiment directory to ensure uniqueness
exist_ok (bool) – Whether it is ok if the directory already exists or not (will throw an error if set to False and it already exists)

Returns

Path to the directory for the experiment

Return type

pathlib.Path

boa.wrappers.wrapper_utils.zfilled_trial_index(trial_index: int, fill_size: int = 6) → str[source]#

Return trial index left passed with zeros of length fill_size

Parameters

trial_index (int) –
fill_size (int) –

Return type

str

boa.wrappers.wrapper_utils.get_trial_dir(experiment_dir: PathLike, trial_index: int, **kwargs)[source]#

Return a directory for a trial, Trial directory is named with the trial index (0 padded to 6 decimal)

Parameters

experiment_dir (PathLike) – Directory for the experiment
trial_index (int) – Trial index from the Ax client
**kwargs – keyword args passed to zfilled_trial_index

Returns

Directory for the trial

Return type

pathlib.Path

boa.wrappers.wrapper_utils.make_trial_dir(experiment_dir: PathLike, trial_index: int, exist_ok=True, **kwargs)[source]#

Create a directory for a trial, and return the path to the directory. Trial directory is created inside the experiment directory, and named with the trial index (0 padded to 6 decimal). Model configs and outputs for each trial will be written here.

Parameters

experiment_dir (PathLike) – Directory for the experiment
trial_index (int) – Trial index from the Ax client
exist_ok – Whether it is ok if the directory already exists. Errors if set to False and the directory already exists. Sometimes the directory already exists if reusing experiment directory of continueing stopped experiments that were interrupted and have to restart trials
**kwargs – keyword args passed to get_trial_dir

Returns

Directory for the trial

Return type

pathlib.Path

boa.wrappers.wrapper_utils.save_trial_data(trial: BaseTrial, trial_dir: Optional[Path] = None, experiment_dir: Optional[PathLike] = None, param_names: Optional[dict[str, list]] = None, **kwargs)[source]#

Save trial data (trial.json, parameters.json and data.json) to either: supplied trial_dir or supplied experiment_dir / trial.index

Parameters

trial (BaseTrial) –
trial_dir (Optional[Path]) –
experiment_dir (Optional[PathLike]) –
param_names (Optional[dict[str, list]]) –