peal.global_utils

Cross-cutting helpers shared by the whole PEAL library.

Collected here are the utilities that do not belong to one subpackage: yaml config loading (including the $PEAL_RUNS/$PEAL_DATA/<PEAL_BASE> placeholders, recursive inclusion of nested yamls and the mapping of a config onto its pydantic model), argparse integration for those configs, seed handling and device moves, small module surgery such as replacing ReLUs or resetting weights, the difference heatmaps and change masks used to visualise counterfactuals, and a DINOv2-based evaluator for FID, Mahalanobis distance and a LPIPS-style perceptual distance.

Functions

add_class_arguments	Add one command line argument per annotated config field.
cprint	Print s only if the tracking level a reaches the threshold b.
dict_to_bar_chart	Creates a bar chart from a dictionary and saves it as a PNG image.
embed_numberstring	Left-pad a number with zeros so that filenames sort lexicographically.
extract_penultima_activation	Return the activation feeding the predictor's last layer.
find_subclasses	Import every module under directory and collect subclasses.
generate_feature_similarity_overlay	Visualizes similarity of intermediate features.
generate_overlay	Blend the change heatmap onto a washed-out copy of the image.
generate_ssim_overlay	Highlight structural, rather than pixelwise, change in red.
get_config_model	Find the pydantic config class that a raw config dict describes.
get_intermediate_output	Runs the model on input x and returns the activation tensor.
get_predictions	Predict a whole dataset and write the labels to a csv file.
get_project_resource_dir	Return the repository root, i.e. the directory containing peal.
high_contrast_heatmap	Colour-code the change from an image to its counterfactual.
integrate_argument	Write one parsed command line value into a (possibly nested) config.
integrate_arguments	Apply all parsed command line arguments to a config.
is_port_in_use	Return True if something is already listening on localhost:port.
load_yaml_config	Load a config file (or dict) into its pydantic model.
move_to_device	Clone a tensor, or a list of tensors, onto device.
onehot	One-hot encode a batch of class indices.
orthogonal_initialization	Orthogonally initialise all weights and zero all biases.
propagate_seed	Copy the top-level seed into every nested config that has one.
replace_relu_with_leakyrelu	Replace every ReLU submodule by a LeakyReLU with slope 0.1.
replace_relu_with_leakysoftplus	Replace every ReLU in the module tree by a LeakySoftplus.
request	Ask on the console whether a value should be changed.
requires_grad_	Set requires_grad on every parameter of model, in place.
reset_weights	Re-initialise a model by calling reset_parameters recursively.
save_yaml_config	This function saves a config to a yaml file.
set_adaptive_batch_size	Scale a reference batch size to the current resolution and GPU.
set_random_seed	Seed every random source PEAL uses and force deterministic cuDNN.
ssim_map	Computes a simplified Structural Similarity Index Measure (SSIM) map between two images locally.

Classes

DINOEvaluator	Distribution metrics computed in a DINOv2 feature space.
LeakySoftplus	Smooth, everywhere non-zero gradient replacement for ReLU.