imitation.util.util

Miscellaneous utility methods.

Functions

clear_screen()	Clears the console screen.
docstring_parameter(*args, **kwargs)	Treats the docstring as a format string, substituting in the arguments.
endless_iter(iterable)	Generator that endlessly yields elements from iterable.
get_first_iter_element(iterable)	Get first element of an iterable and a new fresh iterable.
make_seeds()	Generate n random seeds from a random state.
make_unique_timestamp()	Timestamp, with random uuid added to avoid collisions.
make_vec_env(env_name, *, rng[, n_envs, ...])	Makes a vectorized environment.
oric(x)	Optimal rounding under integer constraints.
parse_optional_path(path[, allow_relative, ...])	Parse an optional path to a pathlib.Path object.
parse_path(path[, allow_relative, ...])	Parse a path to a pathlib.Path object.
safe_to_numpy()	Convert torch tensor to numpy.
safe_to_tensor(array, **kwargs)	Converts a NumPy array to a PyTorch tensor.
save_policy(policy, policy_path)	Save policy to a path.
split_in_half(x)	Split an integer in half, rounding up.
tensor_iter_norm(tensor_iter[, ord])	Compute the norm of a big vector that is produced one tensor chunk at a time.

imitation.util.util.clear_screen()

Clears the console screen.

Return type

None

imitation.util.util.docstring_parameter(*args, **kwargs)

Treats the docstring as a format string, substituting in the arguments.

imitation.util.util.endless_iter(iterable)

Generator that endlessly yields elements from iterable.

>>> x = range(2)
>>> it = endless_iter(x)
>>> next(it)
0
>>> next(it)
1
>>> next(it)
0

Parameters

iterable (Iterable[TypeVar(T)]) – The non-iterator iterable object to endlessly iterate over.

Return type

Iterator[TypeVar(T)]

Returns

An iterator that repeats the elements in iterable forever.

Raises

ValueError – if iterable is an iterator – that will be exhausted, so cannot be iterated over endlessly.

imitation.util.util.get_first_iter_element(iterable)

Get first element of an iterable and a new fresh iterable.

The fresh iterable has the first element added back using itertools.chain. If the iterable is not an iterator, this is equivalent to (next(iter(iterable)), iterable).

Parameters

iterable (Iterable[TypeVar(T)]) – The iterable to get the first element of.

Return type

Tuple[TypeVar(T), Iterable[TypeVar(T)]]

Returns

A tuple containing the first element of the iterable, and a fresh iterable with all the elements.

Raises

ValueError – iterable is empty – the first call to it returns no elements.

imitation.util.util.make_seeds(rng: Generator) → int

imitation.util.util.make_seeds(rng: Generator, n: int) → List[int]

Generate n random seeds from a random state.

Parameters

• rng (Generator) – The random state to use to generate seeds.

• n (Optional[int]) – The number of seeds to generate.

Return type

Union[Sequence[int], int]

Returns

A list of n random seeds.

imitation.util.util.make_unique_timestamp()

Timestamp, with random uuid added to avoid collisions.

Return type

str

imitation.util.util.make_vec_env(env_name, *, rng, n_envs=8, parallel=False, log_dir=None, max_episode_steps=None, post_wrappers=None, env_make_kwargs=None)

Makes a vectorized environment.

Parameters

• env_name (str) – The Env’s string id in Gym.

• rng (Generator) – The random state to use to seed the environment.

• n_envs (int) – The number of duplicate environments.

• parallel (bool) – If True, uses SubprocVecEnv; otherwise, DummyVecEnv.

• log_dir (Optional[str]) – If specified, saves Monitor output to this directory.

• max_episode_steps (Optional[int]) – If specified, wraps each env in a TimeLimit wrapper with this episode length. If not specified and max_episode_steps exists for this env_name in the Gym registry, uses the registry max_episode_steps for every TimeLimit wrapper (this automatic wrapper is the default behavior when calling gym.make). Otherwise the environments are passed into the VecEnv unwrapped.

• post_wrappers (Optional[Sequence[Callable[[Env, int], Env]]]) – If specified, iteratively wraps each environment with each of the wrappers specified in the sequence. The argument should be a Callable accepting two arguments, the Env to be wrapped and the environment index, and returning the wrapped Env.

• env_make_kwargs (Optional[Mapping[str, Any]]) – The kwargs passed to spec.make.

Return type

VecEnv

Returns

A VecEnv initialized with n_envs environments.

imitation.util.util.oric(x)

Optimal rounding under integer constraints.

Given a vector of real numbers such that the sum is an integer, returns a vector of rounded integers that preserves the sum and which minimizes the Lp-norm of the difference between the rounded and original vectors for all p >= 1. Algorithm from https://arxiv.org/abs/1501.00014. Runs in O(n log n) time.

Parameters

x (ndarray) – A 1D vector of real numbers that sum to an integer.

Return type

ndarray

Returns

A 1D vector of rounded integers, preserving the sum.

imitation.util.util.parse_optional_path(path, allow_relative=True, base_directory=None)

Parse an optional path to a pathlib.Path object.

All resulting paths are resolved, absolute paths. If allow_relative is True, then relative paths are allowed as input, and are resolved relative to the current working directory, or relative to base_directory if it is specified.

Parameters

• path (Union[str, bytes, PathLike, None]) – The path to parse. Can be a string, bytes, or os.PathLike.

• allow_relative (bool) – If True, then relative paths are allowed as input, and are resolved relative to the current working directory. If False, an error is raised if the path is not absolute.

• base_directory (Optional[Path]) – If specified, then relative paths are resolved relative to this directory, instead of the current working directory.

Return type

Optional[Path]

Returns

A pathlib.Path object, or None if path is None.

imitation.util.util.parse_path(path, allow_relative=True, base_directory=None)

Parse a path to a pathlib.Path object.

All resulting paths are resolved, absolute paths. If allow_relative is True, then relative paths are allowed as input, and are resolved relative to the current working directory, or relative to base_directory if it is specified.

Parameters

• path (Union[str, bytes, PathLike]) – The path to parse. Can be a string, bytes, or os.PathLike.

• allow_relative (bool) – If True, then relative paths are allowed as input, and are resolved relative to the current working directory. If False, an error is raised if the path is not absolute.

• base_directory (Optional[Path]) – If specified, then relative paths are resolved relative to this directory, instead of the current working directory.

Return type

Path

Returns

A pathlib.Path object.

Raises

• ValueError – If allow_relative is False and the path is not absolute.

• ValueError – If base_directory is specified and allow_relative is False.

imitation.util.util.safe_to_numpy(obj: Union[ndarray, Tensor], warn: bool = False) → ndarray

imitation.util.util.safe_to_numpy(obj: None, warn: bool = False) → None

Convert torch tensor to numpy.

If the object is already a numpy array, return it as is. If the object is none, returns none.

Parameters

• obj (Union[ndarray, Tensor, None]) – torch tensor object to convert to numpy array

• warn (bool) – if True, warn if the object is not already a numpy array. Useful for warning the user of a potential performance hit if a torch tensor is not the expected input type.

Return type

Optional[ndarray]

Returns

Object converted to numpy array

imitation.util.util.safe_to_tensor(array, **kwargs)

Converts a NumPy array to a PyTorch tensor.

The data is copied in the case where the array is non-writable. Unfortunately if you just use th.as_tensor for this, an ugly warning is logged and there’s undefined behavior if you try to write to the tensor.

Parameters

• array (Union[ndarray, Tensor]) – The array to convert to a PyTorch tensor.

• kwargs – Additional keyword arguments to pass to th.as_tensor.

Return type

Tensor

Returns

A PyTorch tensor with the same content as array.

imitation.util.util.save_policy(policy, policy_path)

Save policy to a path.

Parameters

• policy (BasePolicy) – policy to save.

• policy_path (Union[str, bytes, PathLike]) – path to save policy to.

Return type

None

imitation.util.util.split_in_half(x)

Split an integer in half, rounding up.

This is to ensure that the two halves sum to the original integer.

Parameters

x (int) – The integer to split.

Return type

Tuple[int, int]

Returns

A tuple containing the two halves of x.

imitation.util.util.tensor_iter_norm(tensor_iter, ord=2)

Compute the norm of a big vector that is produced one tensor chunk at a time.

Parameters

• tensor_iter (Iterable[Tensor]) – an iterable that yields tensors.

• ord (Union[int, float]) – order of the p-norm (can be any int or float except 0 and NaN).

Return type

Tensor

Returns

Norm of the concatenated tensors.

Raises

ValueError – ord is 0 (unsupported).