Task

PtychographyTask

Bases: Task

Build and run a ptychography reconstruction from settings and input arrays.

Initialization validates the inputs and builds the dataset, reconstruction parameters, and reconstructor. Call run() to start reconstruction and get_data() to retrieve reconstructed parameters.

Parameters:

options (ptychi.api.options.task.PtychographyTaskOptions) – Algorithm-specific reconstruction settings.
diffraction_data (array-like) – Measured intensities with shape (n_positions, H, W). The dataset FFT-shifts the patterns when options.data_options.fft_shift is True.
object_data (array-like) – Initial complex object with shape (n_slices, height, width). A single-slice object retains the leading dimension of size 1.
probe_data (array-like) – Initial complex probe with shape (n_opr_modes, n_incoherent_modes, height, width).
probe_position_x_px (array-like) – Initial horizontal probe positions in object pixels, with shape (n_positions,).
probe_position_y_px (array-like) – Initial vertical probe positions in object pixels, with shape (n_positions,). Positions are stored internally in (y, x) order.
opr_mode_weights_data (array-like, optional) – Initial OPR weights with shape (n_positions, n_opr_modes) or (n_opr_modes,) for weights shared by all positions. Required when the probe has multiple OPR modes; otherwise omitted weights default to 1.
valid_pixel_mask (array-like, optional) – Boolean mask with shape (H, W), shared by all diffraction patterns, where True marks valid pixels. All pixels are valid by default.
detector_response_map (tuple of numpy.ndarray or torch.Tensor, optional) – Shared (gain, offset) pair, each with shape (H, W). Both maps must be real and finite in the reconstruction dtype, including at masked pixels. Gains must be strictly positive in the reconstruction dtype. Use valid_pixel_mask to exclude invalid detector pixels. After detector cropping and blur, predicted intensities are transformed as intensity * gain + offset. The gain is dimensionless; the offset uses measured-intensity units. None initializes an identity response. Refinement is disabled by default; configure options.reconstructor_options.forward_model_options.detector_response_options to enable it. Retrieve the live (2, H, W) tensor with get_data("detector_response"). With options.data_options.fft_shift=True (the default), supply response maps in the original detector coordinates, aligned with the centered far-field patterns, without manually FFT-shifting them. The task applies torch.fft.fftshift to both maps and patterns along the last two axes. With fft_shift=False, maps are used as supplied: align them with the already-shifted patterns when the far-field DC pixel is at the top left, or with the unshifted detector images for near-field data.

Notes

Input arrays are keyword-only. The mask and detector-response components must use the same pixel ordering as the input diffraction patterns.

Legacy option-held data fields remain supported with a deprecation warning. Explicit data arguments take precedence over those fields.

build()[source]

build_data()[source]

build_default_device()[source]

build_default_dtype()[source]

build_detector_response()[source]

build_logger()[source]

build_object()[source]

build_opr_mode_weights()[source]

build_probe()[source]

build_probe_positions()[source]

build_random_seed()[source]

build_reconstructor()[source]

check_options()[source]

check_task_data()[source]

copy_data_from_task(task: PtychographyTask, params_to_copy: tuple[str, ...] = ('object', 'probe', 'probe_positions', 'opr_mode_weights')) → None[source]

Copy data of reconstruction parameters from another task object.

Parameters:

task (PtychographyTask) – The task object to copy from.
params_to_copy (tuple[str, ...], optional) – The parameters to copy. By default, copy all parameters.

get_data(name: Literal['object', 'probe', 'probe_positions', 'opr_mode_weights', 'detector_response']) → Tensor[source]

Get a detached copy of the data of the given name.

Parameters:: name (Literal["object", "probe", "probe_positions", "opr_mode_weights", "detector_response"]) – The name of the data to get.
Returns:: The data of the given name. Detector response has shape (2, H, W) with gain first and offset second, in the internal diffraction-data ordering (after the configured FFT shift).
Return type:: Tensor

get_data_to_cpu(name: Literal['object', 'probe', 'probe_positions', 'opr_mode_weights', 'detector_response'], as_numpy: bool = False) → Tensor | ndarray[source]

get_options_as_dict() → dict[source]

get_probe_positions_x(as_numpy: bool = False) → Tensor | ndarray[source]

get_probe_positions_y(as_numpy: bool = False) → Tensor | ndarray[source]

load_options_from_dict(d: dict) → None[source]

print_user_announcement()[source]

run(n_epochs: int = None, reset_timer_globals: bool = True)[source]

Run reconstruction either for n_epochs (if given), or for the number of epochs given in the options. The internal states of the Task object persists when this function finishes. To run more epochs continuing from the last run, call this function again.

Parameters:

n_epochs (int, optional) – The number of epochs to run. If None, use the number of epochs specified in the option object.
reset_timer_globals (bool, optional) – When True (default) the global timing accumulators are cleared before the run. Set to False to continue accumulating timing data across successive calls.

set_large_tensor_device(device: Literal['cpu', 'cuda'] | device | None = None) → None[source]

Move task tensors and reconstruction state between devices.

This helper is aimed at multi-task workflows where only one task is active on the accelerator at a time. Call it with device="cpu" to offload task tensors and optimizer/reconstructor state to system memory, and call it again before resuming the task to restore that state to the accelerator. The forward model’s intermediate variables are discarded rather than moved: every forward pass rewrites them before they are read.

Parameters:: device (str | torch.device | None, optional) – Target device for task state. If None, tensors are moved back to the current default device. If a string is given, it must be either “cpu” or “cuda”.