ptyrad.io.save

ptyrad.io.save#

PtyRAD-specific saving functions

Functions

expand_presets(input_list, presets)

Expands a list of tags by replacing preset keys with their corresponding lists.

make_output_folder(output_dir, indices, ...)

Generates a highly descriptive output folder name based on runtime configurations.

make_save_dict(output_path, model, params, ...)

Compiles the model state, parameters, and optimizer data into a dictionary.

safe_filename(filepath)

Ensures a filepath is safe and valid across different operating systems.

save_dict_to_hdf5(d, output_path[, ...])

Saves a nested Python dictionary to an HDF5 file.

save_results(output_path, model, params, ...)

Exports the reconstruction model state and renders image outputs.
ptyrad.io.save.expand_presets(input_list, presets)[source]#

Expands a list of tags by replacing preset keys with their corresponding lists.

If a tag in the input_list exists as a key in the presets dictionary, it is replaced by the list of tags associated with that preset. Duplicates are removed while preserving the original order of the tags.

Parameters:

  • input_list (list of str) – The initial list of tags or preset names.

  • presets (dict) – A dictionary mapping a preset string to a list of strings.

Returns:

The expanded list of tags with duplicates removed.

Return type:

list of str

ptyrad.io.save.safe_filename(filepath)[source]#

Ensures a filepath is safe and valid across different operating systems.

This function prevents path-related crashes by: 1. Converting relative paths to absolute paths. 2. Truncating individual directory or file components to 255 characters. 3. Handling the Windows 260-character total path limit by applying the “\?" extended-length path prefix if necessary.

Parameters:

filepath (str) – The original filepath to sanitize.

Returns:

A modified, cross-platform-safe absolute filepath.

Return type:

str

ptyrad.io.save.make_save_dict(output_path, model, params, optimizer, scheduler, niter, indices, batch_losses)[source]#

Compiles the model state, parameters, and optimizer data into a dictionary.

This explicitly extracts and formats the current runtime attributes from the model (e.g., actual grid sizes, learning rates) rather than relying solely on the initial parameter file, as values may have changed during initialization (e.g., cropping, resampling) or interactive walkthroughs.

Parameters:

  • output_path (str) – The directory path where results will be saved.

  • model (PtychoModel) – The current reconstruction model object.

  • params (dict) – The initial configuration dictionary.

  • optimizer (torch.optim.Optimizer) – The PyTorch optimizer.

  • niter (int) – The current iteration number.

  • indices (list or numpy.ndarray) – The batch indices used in the current iteration.

  • batch_losses (dict) – A dictionary mapping loss names to lists of batch loss values.

Returns:

A comprehensive dictionary ready for HDF5 serialization.

Return type:

dict

ptyrad.io.save.save_dict_to_hdf5(d, output_path, none_sentinel='__NONE__', **kwargs)[source]#

Saves a nested Python dictionary to an HDF5 file.

Recursively parses the dictionary and converts common Python, NumPy, and PyTorch types into HDF5-compatible formats. Non-compatible types (e.g., lists of tuples, None) are converted to safe string representations or sentinels. Integer keys (common in optimizer state dicts) are coerced to strings.

Parameters:

  • d (dict) – The nested dictionary to serialize.

  • output_path (str) – The target file path for the .hdf5 file.

  • none_sentinel (str, optional) – The string used to represent None values in the HDF5 file. Defaults to “__NONE__”.

  • **kwargs – Additional keyword arguments passed to h5py.File.create_dataset() (e.g., compression=”gzip”).

Return type:

None

ptyrad.io.save.make_output_folder(output_dir, indices, init_params, recon_params, model, constraint_params, loss_params, recon_dir_affixes=['default'])[source]#

Generates a highly descriptive output folder name based on runtime configurations.

Constructs a detailed directory name by concatenating abbreviations of the active reconstruction parameters, model attributes, constraints, and losses. This allows users to identify the exact settings of a run just by looking at the folder name.

Parameters:

  • output_dir (str) – The base directory where the output folder will be created.

  • indices (list) – The list of indices used in the reconstruction.

  • init_params (dict) – Initialization parameters.

  • recon_params (dict) – Reconstruction parameters containing naming prefixes/postfixes.

  • model (PtychoModel) – The model containing current spatial and optimization attributes.

  • constraint_params (dict) – Dictionary of active constraints and filters.

  • loss_params (dict) – Dictionary of active loss functions and weights.

  • recon_dir_affixes (list of str, optional) – A list of tags or preset keys dictating which parameters to include in the folder name. Defaults to [“default”].

Returns:

The sanitized absolute path to the newly generated output folder.

Return type:

str

ptyrad.io.save.save_results(output_path, model, params, optimizer, scheduler, niter, indices, batch_losses, collate_str='')[source]#

Exports the reconstruction model state and renders image outputs.

This function acts as the main saving hub. Depending on the save_result and result_modes specifications in params, it saves the full state to an HDF5 file (including provenance) and renders the complex object and probe arrays out to .tif images with appropriate bit-depth scaling and dimensional slicing (e.g., z-stacks, sums, or cropped fields of view).

Parameters:

  • output_path (str) – The directory where files will be written.

  • model (PtychoModel) – The reconstruction model.

  • params (dict) – The configuration dictionary dictating save preferences.

  • optimizer (torch.optim.Optimizer) – The active optimizer.

  • scheduler (torch.optim.lr_scheduler.LRScheduler or None) – The active LR scheduler, or None if not used.

  • niter (int) – The current iteration number.

  • indices (list or numpy.ndarray) – The batch indices.

  • batch_losses (dict) – The recorded loss values.

  • collate_str (str, optional) – An optional string injected into the filenames (useful for distinguishing multiple concurrent outputs). Defaults to ‘’.

Contents