Options

The following classes define the configuration options for Pty-chi reconstructions.

Base Options

class ptychi.api.options.base.Options[source]

Bases: object

check(*args, **kwargs) → None[source]: Check if options values are valid.

get_dict() → dict[source]: Get a dictionary representation of the options.

get_field_type(name: str) → type[source]: Get the type of a field.

get_non_data_fields() → dict[source]: Get fields that do not contain large arrays or tensors.

load_from_dict(d: dict) → Options[source]: Load options from a dictionary.

resolve_type(ann_type) → type[source]: Resolve annotation to underlying type (handles Optional, etc.).

class ptychi.api.options.base.TaskOptions[source]: Bases: Options

class ptychi.api.options.base.ObjectOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, slice_spacings_m: numpy.ndarray | None = None, slice_spacing_options: ptychi.api.options.base.SliceSpacingOptions = <factory>, pixel_size_m: float = 1.0, pixel_size_aspect_ratio: float = 1.0, l1_norm_constraint: ptychi.api.options.base.ObjectL1NormConstraintOptions = <factory>, l2_norm_constraint: ptychi.api.options.base.ObjectL2NormConstraintOptions = <factory>, smoothness_constraint: ptychi.api.options.base.ObjectSmoothnessConstraintOptions = <factory>, total_variation: ptychi.api.options.base.ObjectTotalVariationOptions = <factory>, hard_limits_magnitude_phase: ptychi.api.options.base.ObjectHardLimitsMagnitudePhase = <factory>, remove_grid_artifacts: ptychi.api.options.base.RemoveGridArtifactsOptions = <factory>, multislice_regularization: ptychi.api.options.base.ObjectMultisliceRegularizationOptions = <factory>, patch_interpolation_method: ptychi.api.enums.PatchInterpolationMethods = <PatchInterpolationMethods.FOURIER: 'fourier'>, remove_object_probe_ambiguity: ptychi.api.options.base.RemoveObjectProbeAmbiguityOptions = <factory>, build_preconditioner_with_all_modes: bool = False, determine_position_origin_coords_by: ptychi.api.enums.ObjectPosOriginCoordsMethods = <ObjectPosOriginCoordsMethods.SUPPORT: 'support'>, position_origin_coords: numpy.ndarray | None = None)[source]

Bases: ParameterOptions

build_preconditioner_with_all_modes: bool = False: If True, the probe illumination map used for the preconditioner is built using the sum of intensities of all probe modes. This may help address some issues if some probe modes contain highly localized high-intensity anomalies, if the selected reconstructor uses preconditioner to regularize object updates. However, it might lead to slower convergence speed.

check(options: PtychographyTaskOptions)[source]: Check if options values are valid.

determine_position_origin_coords_by: ObjectPosOriginCoordsMethods = 'support'

The method to determine the pixel coordinates of the object that corresponds to the origin of the probe positions.

Probe positions are given as a list of coordinates that can be either positive or negative and have arbitrary offsets, while the object buffer is a discrete tensor where the pixel indices are 0-based and the origin is at the top left corner. The position origin coordinates are used to determine how the given probe positions are mapped to the object buffer: the origin of the probe positions (0, 0) is mapped to the pixel indices given by the position origin coordinates, and as such, the pixel indices of all probe positions are calculated as ` positions_pxind = positions + position_origin_coords `

POSITIONS: the origin coordinates are determined as buffer_center - (positions.max() + positions.min()) / 2. This puts the mid-point of the position range at the center of the buffer. It is more adaptive; however, in the case that one initializes a reconstruction with a previously reconstructed object and corrected probe positions, the center coordinates are not necessarily the same, which can cause the positions to mismatch between both reconstructions.
SUPPORT: the origin coordinates are determined as the center of the support of the object. This is helpful to keep the center coordinates consistent between consecutive reconstructions, but the probe positions given should (at least approximately) zero-centered, i.e., -postitions.min() ~ positions.max() to prevent out-of-bound errors.
SPECIFIED: the origin coordinates are specified by the user. To make this setting effective, position_origin_coords should be specified.

get_non_data_fields() → dict[source]: Get fields that do not contain large arrays or tensors.

hard_limits_magnitude_phase: ObjectHardLimitsMagnitudePhase

initial_guess: ndarray | Tensor = None: A (h, w) complex tensor of the object initial guess.

l1_norm_constraint: ObjectL1NormConstraintOptions

l2_norm_constraint: ObjectL2NormConstraintOptions

multislice_regularization: ObjectMultisliceRegularizationOptions

patch_interpolation_method: PatchInterpolationMethods = 'fourier': Selects the interpolation method used for extracting and updating patches of the object IF patch extraction/placement is done using the object’s methods extract_patches_function or place_patches_function.

pixel_size_aspect_ratio: float = 1.0: The aspect ratio of the pixel size, defined as width (x) / height (y).

pixel_size_m: float = 1.0: The pixel size in meters. When pixel size is non-square, this should be the width (x) of the pixel size.

position_origin_coords: ndarray | None = None

The user-specified origin coordinates of the object. To make this setting effective, determine_position_origin_coords_by should be set to SPECIFIED.

Probe positions are given as a list of coordinates that can be either positive or negative and have arbitrary offsets, while the object buffer is a discrete tensor where the pixel indices are 0-based and the origin is at the top left corner. The position origin coordinates are used to determine how the given probe positions are mapped to the object buffer: the origin of the probe positions (0, 0) is mapped to the pixel indices given by the position origin coordinates, and as such, the pixel indices of all probe positions are calculated as ` positions_pxind = positions + position_origin_coords `

remove_grid_artifacts: RemoveGridArtifactsOptions

remove_object_probe_ambiguity: RemoveObjectProbeAmbiguityOptions

slice_spacing_options: SliceSpacingOptions

slice_spacings_m: ndarray | None = None

Slice spacings in meters. This should be provided if the object is multislice.

If the slice spacings need to be optimized, set slice_spacing_options.optimizable to True. In that case, the slice spacings provided here are supposed to be the initial guess.

smoothness_constraint: ObjectSmoothnessConstraintOptions

total_variation: ObjectTotalVariationOptions

class ptychi.api.options.base.ProbeOptions(optimizable: bool = True, optimization_plan: OptimizationPlan = <factory>, optimizer: Optimizers = Optimizers.SGD, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: ndarray | Tensor = None, power_constraint: ProbePowerConstraintOptions = <factory>, orthogonalize_incoherent_modes: ProbeOrthogonalizeIncoherentModesOptions = <factory>, orthogonalize_opr_modes: ProbeOrthogonalizeOPRModesOptions = <factory>, support_constraint: ProbeSupportConstraintOptions = <factory>, center_constraint: ProbeCenterConstraintOptions = <factory>, eigenmode_update_relaxation: float = 1.0)[source]

Bases: ParameterOptions

The probe configuration.

The first OPR mode of all incoherent modes are always optimized aslong as optimizable is True. In addition to thtat, eigenmodes (of the first incoherent mode) are optimized when:

The probe has multiple OPR modes;
OPRModeWeightsConfig is given.

center_constraint: ProbeCenterConstraintOptions

check(options: task_options.PtychographyTaskOptions)[source]: Check if options values are valid.

eigenmode_update_relaxation: float = 1.0: A separate step size for eigenmode update.

get_non_data_fields() → dict[source]: Get fields that do not contain large arrays or tensors.

initial_guess: ndarray | Tensor = None: A (n_opr_modes, n_modes, h, w) complex tensor of the probe initial guess.

orthogonalize_incoherent_modes: ProbeOrthogonalizeIncoherentModesOptions

orthogonalize_opr_modes: ProbeOrthogonalizeOPRModesOptions

power_constraint: ProbePowerConstraintOptions

support_constraint: ProbeSupportConstraintOptions

class ptychi.api.options.base.ProbePositionOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 0.3, optimizer_params: dict = <factory>, position_x_px: Union[numpy.ndarray, torch.Tensor]=None, position_y_px: Union[numpy.ndarray, torch.Tensor]=None, constrain_position_mean: bool = False, correction_options: ptychi.api.options.base.PositionCorrectionOptions = <factory>, affine_transform_constraint: ptychi.api.options.base.PositionAffineTransformConstraintOptions = <factory>)[source]

Bases: ParameterOptions

affine_transform_constraint: PositionAffineTransformConstraintOptions: When enabled, an affine transformation from initial positions to current positions is fit, and positions deviating from the expected positions given by the affine transformation are penalized.

check(options: task_options.PtychographyTaskOptions)[source]: Check if options values are valid.

constrain_position_mean: bool = False: Whether to subtract the mean from positions after updating positions.

correction_options: PositionCorrectionOptions: Detailed options for position correction.

get_non_data_fields() → dict[source]: Get fields that do not contain large arrays or tensors.

optimizable: bool = False: Whether the parameter is optimizable.

position_x_px: ndarray | Tensor = None: The x position in pixel.

position_y_px: ndarray | Tensor = None: The y position in pixel.

step_size: float = 0.3: The step size for probe position update.

class ptychi.api.options.base.OPRModeWeightsOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_weights: numpy.ndarray = None, optimize_eigenmode_weights: bool = True, optimize_intensity_variation: bool = False, smoothing: ptychi.api.options.base.OPRModeWeightsSmoothingOptions = <factory>, update_relaxation: float = 1.0)[source]

Bases: ParameterOptions

check(options: task_options.PtychographyTaskOptions)[source]: Check if options values are valid.

get_non_data_fields() → dict[source]: Get fields that do not contain large arrays or tensors.

initial_weights: ndarray = None

The initial weight(s) of the eigenmode(s). Acceptable values include the following:

a (n_scan_points, n_opr_modes) array of initial weights for every point.
a (n_opr_modes,) array that gives the weights of each OPR mode. These weights will be duplicated for every point.

optimizable: bool = False: The master switch of optimizability of OPR mode weights. This option must be set to True for either optimize_eigenmode_weights or optimize_intensity_variation to take effect.

optimize_eigenmode_weights: bool = True

Whether to optimize eigenmode weights, i.e., the weights of the second and following OPR modes.

At least one of optimize_eigenmode_weights and optimize_intensity_variation should be set to True if optimizable is True.

optimize_intensity_variation: bool = False

Whether to optimize intensity variation, i.e., the weight of the first OPR mode.

At least one of optimize_eigenmode_weights and optimize_intensity_variation should be set to True if optimizable is True.

smoothing: OPRModeWeightsSmoothingOptions

update_relaxation: float = 1.0: A separate step size for eigenmode weight update.

class ptychi.api.options.base.FeatureOptions(enabled: bool, optimization_plan: OptimizationPlan)[source]

Bases: Options

Abstract base class that is inherited by sub-feature dataclasses. This class is used to determining if/when a feature is used.

enabled: bool: Turns execution of the feature on and off.

is_enabled_on_this_epoch(current_epoch: int)[source]

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

class ptychi.api.options.base.SynthesisDictLearnProbeOptions(d_mat: numpy.ndarray | torch.Tensor = None, d_mat_conj_transpose: numpy.ndarray | torch.Tensor = None, d_mat_pinv: numpy.ndarray | torch.Tensor = None, probe_sparse_code: numpy.ndarray | torch.Tensor = None, probe_sparse_code_nnz: float = None, enabled: bool = False)[source]

Bases: Options

d_mat: ndarray | Tensor = None: The synthesis sparse dictionary matrix; contains the basis functions that will be used to represent the probe via the sparse code weights.

d_mat_conj_transpose: ndarray | Tensor = None: Conjugate transpose of the synthesis sparse dictionary matrix.

d_mat_pinv: ndarray | Tensor = None: Moore-Penrose pseudoinverse of the synthesis sparse dictionary matrix.

enabled: bool = False

probe_sparse_code: ndarray | Tensor = None: Sparse code weights vector.

probe_sparse_code_nnz: float = None: Number of non-zeros we will keep when enforcing sparsity constraint on the sparse code weights vector probe_sparse_code.

class ptychi.api.options.base.PositionCorrectionOptions(correction_type: PositionCorrectionTypes = PositionCorrectionTypes.GRADIENT, differentiation_method: ImageGradientMethods = ImageGradientMethods.FOURIER_DIFFERENTIATION, cross_correlation_scale: int = 20000, cross_correlation_real_space_width: float = 0.01, cross_correlation_probe_threshold: float = 0.1, slice_for_correction: int = None, clip_update_magnitude_by_mad: bool = True, update_magnitude_limit: float | None = 0.1)[source]

Bases: Options

Options used for specifying the position correction function.

clip_update_magnitude_by_mad: bool = True: If True, the update magnitude is eventually clipped by 10 times the mean absolute deviation (MAD) of the updates. When update_magnitude_limit is set, the limit will be set to the smaller of them, i.e., min(update_magnitude_limit, 10 * MAD).

correction_type: PositionCorrectionTypes = 'gradient': Type of algorithm used to calculate the position correction update.

cross_correlation_probe_threshold: float = 0.1: The probe intensity threshold used to calculate the probe mask.

cross_correlation_real_space_width: float = 0.01: The width of the cross-correlation in real-space

cross_correlation_scale: int = 20000: The upsampling factor of the cross-correlation in real space.

differentiation_method: ImageGradientMethods = 'fourier_differentiation': The method for calculating the gradient of the object. Only used when correction_type is GRADIENT. “FOURIER_DIFFERENTIATION” is usually the fastest, but it might be less stable when the object is noisy or non-smooth, under which circumstance “GAUSSIAN” or “FOURIER_SHIFT” may offer better stability. “NEAREST” is not recommended.

slice_for_correction: int = None: The object slice for which the position correction is calculated. If None, the middle slice is chosen.

update_magnitude_limit: float | None = 0.1: The maximum allowed magnitude of position update in each axis. Updates larger than this value are clipped. Set to None or inf to disable the constraint. When clip_update_magnitude_by_mad is True, the actual limit will be set to the smaller of update_magnitude_limit and 10 * MAD.

class ptychi.api.options.base.PositionAffineTransformConstraintOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, degrees_of_freedom: Sequence[AffineDegreesOfFreedom] = (AffineDegreesOfFreedom.ROTATION, AffineDegreesOfFreedom.SCALE, AffineDegreesOfFreedom.SHEAR, AffineDegreesOfFreedom.ASYMMETRY), position_weight_update_interval: int = 10, apply_constraint: bool = True, max_expected_error: float = 1.0, override_update_flexibility: float | None = None)[source]

Bases: FeatureOptions

Settings for imposing an affine transformation constraint on the probe positions.

apply_constraint: bool = True: Constraint is applied to probe positions only when this is True. When False, probe position weights and affine transformation matrix are still computed and stored in the ProbePositions object so that they can be logged and analyzed externally, but the positions are not altered.

check(options: task_options.PtychographyTaskOptions)[source]: Check if options values are valid.

degrees_of_freedom: Sequence[AffineDegreesOfFreedom] = (AffineDegreesOfFreedom.ROTATION, AffineDegreesOfFreedom.SCALE, AffineDegreesOfFreedom.SHEAR, AffineDegreesOfFreedom.ASYMMETRY): The degrees of freedom to include in the affine transformation.

enabled: bool = False: Turns execution of the feature on and off.

is_position_weight_update_enabled_on_this_epoch(current_epoch: int)[source]

max_expected_error: float = 1.0: The maximum expected position error, given in pixels. Note that this is different from update_magnitude_limit, and is only used in the estimation of friction in affine transformation constraint.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

override_update_flexibility: float | None = None: If set, the update flexibility will be set to this value instead of being determined by the actual errors and max expected error. The value should be betweem 0 and 1. If affine constraint is causing instability, setting this to a smaller value may help.

position_weight_update_interval: int = 10: The number of epochs between position weight updates.

class ptychi.api.options.base.ForwardModelOptions(low_memory_mode: bool = False, pad_for_shift: int | None = 0, diffraction_pattern_blur_sigma: float | None = None)[source]

Bases: Options

diffraction_pattern_blur_sigma: float | None = None: If not None, simulated diffraction patterns are blurred with a Gaussian kernel of this sigma. This is useful to mitigate the effect of the detector’s point spread function.

low_memory_mode: bool = False: If True, forward propagation of ptychography will be done using less vectorized code. This reduces the speed, but also lowers memory usage.

pad_for_shift: int | None = 0: If not None, the image is padded with border values by this amount before shifting.

class ptychi.api.options.base.ObjectMultisliceRegularizationOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, weight: float = 0, unwrap_phase: bool = True, unwrap_image_grad_method: ImageGradientMethods = ImageGradientMethods.FOURIER_DIFFERENTIATION, unwrap_image_integration_method: ImageIntegrationMethods = ImageIntegrationMethods.FOURIER)[source]

Bases: FeatureOptions

Settings for multislice regularization of the object.

enabled: bool = False: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

unwrap_image_grad_method: ImageGradientMethods = 'fourier_differentiation'

The method for calculating the phase gradient during phase unwrapping.

FOURIER_SHIFT: Use Fourier shift to perform shift.
NEAREST: Use nearest neighbor to perform shift.
FOURIER_DIFFERENTIATION: Use Fourier differentiation.

unwrap_image_integration_method: ImageIntegrationMethods = 'fourier'

The method for integrating the phase gradient during phase unwrapping.

FOURIER: Use Fourier integration as implemented in PtychoShelves.
DECONVOLUTION: Deconvolve a ramp filter.
DISCRETE: Use cumulative sum.

unwrap_phase: bool = True: Whether to unwrap the phase of the object during multislice regularization.

weight: float = 0: The weight for multislice regularization. Disabled if 0, or if type != ObjectTypes.MULTISLICE. When enabled, multislice objects are regularized using cross-slice smoothing.

class ptychi.api.options.base.ObjectL1NormConstraintOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, weight: float = 0)[source]

Bases: FeatureOptions

Settings for the L1 norm constraint.

enabled: bool = False: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

weight: float = 0: The weight of the L1 norm constraint. Disabled if equal or less than 0.

class ptychi.api.options.base.ObjectL2NormConstraintOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, weight: float = 0)[source]

Bases: FeatureOptions

Settings for the L2 norm constraint.

enabled: bool = False: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

weight: float = 0: The weight of the L2 norm constraint. Disabled if equal or less than 0.

class ptychi.api.options.base.ObjectSmoothnessConstraintOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, alpha: float = 0)[source]

Bases: FeatureOptions

Settings for smoothing of the magnitude (but not the phase) of the object

alpha: float = 0

The relaxation smoothing constant. This value should be in the range 0 < alpha <= 1/8.

Smoothing is done by constructing a 3x3 kernel of

alpha, alpha,         alpha
alpha, 1 - 8 * alpha, alpha
alpha, alpha,         alpha

and convolve it with the object magnitude. When alpha == 1 / 8, the smoothing power is maximal. The value of alpha should not be larger than 1 / 8.

enabled: bool = False: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

class ptychi.api.options.base.ObjectTotalVariationOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, weight: float = 0)[source]

Bases: FeatureOptions

Settings for total variation constraint on the object.

enabled: bool = False: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

weight: float = 0: The weight of the total variation constraint. Disabled if equal or less than 0.

class ptychi.api.options.base.RemoveGridArtifactsOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, period_x_m: float = 1e-07, period_y_m: float = 1e-07, window_size: int = 5, direction: Directions = Directions.XY, component: MagPhaseComponents = MagPhaseComponents.PHASE)[source]

Bases: FeatureOptions

Settings for grid artifact removal in the object’s phase, applied at the end of an epoch

component: MagPhaseComponents = 'phase': The component of the object to remove grid artifacts from.

direction: Directions = 'xy': The direction of grid artifact removal.

enabled: bool = False: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

period_x_m: float = 1e-07: The horizontal period of grid artifacts in meters.

period_y_m: float = 1e-07: The vertical period of grid artifacts in meters.

window_size: int = 5: The window size for grid artifact removal in pixels.

class ptychi.api.options.base.RemoveObjectProbeAmbiguityOptions(enabled: bool = True, optimization_plan: OptimizationPlan = <factory>)[source]

Bases: FeatureOptions

Settings for removing the object-probe ambiguity, where the object is scaled by its norm so that the mean transmission is kept around 1, and the probe is scaled accordingly.

enabled: bool = True: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

class ptychi.api.options.base.SliceSpacingOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1e-10, optimizer_params: dict = <factory>)[source]

Bases: ParameterOptions

check(options: task_options.PtychographyTaskOptions)[source]: Check if options values are valid.

optimizable: bool = False

Whether the slice spacings are optimizable.

Known issue: slice spacing optimization only works with AutodiffPtychography, and we have to use loss.backward(retain_graph=True) to make it work with AD. This might result in growing per-epoch walltime and memory usage. We are working on a better solution.

optimization_plan: OptimizationPlan: Optimization plan for the parameter.

optimizer: Optimizers = 'sgd': The optimizer to use for optimizing the slice spacings.

step_size: float = 1e-10: The step size for the optimizer. As a recommendation, start with 1e-10 for SGD optimizer, and 1e-7 for ADAM optimizer.

class ptychi.api.options.base.ProbePowerConstraintOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, probe_power: float = 0.0, scale_object: bool = True)[source]

Bases: FeatureOptions

Settings for scaling the probe and object intensity.

enabled: bool = False: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

probe_power: float = 0.0: The target probe power. The intensity of the probe and optionally the object will be scaled such that the power of the probe itself is probe_power.

scale_object: bool = True: If True, scale the object inversely when the probe power is constrained. If False, only the probe is rescaled.

class ptychi.api.options.base.ProbeOrthogonalizeIncoherentModesOptions(enabled: bool = True, optimization_plan: OptimizationPlan = <factory>, method: OrthogonalizationMethods = OrthogonalizationMethods.SVD, sort_by_occupancy: bool = False)[source]

Bases: FeatureOptions

Settings for orthogonalizing incoherent probe modes.

enabled: bool = True: Turns execution of the feature on and off.

method: OrthogonalizationMethods = 'svd': The method to use for incoherent_mode orthogonalization.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

sort_by_occupancy: bool = False: If True, keep the probes sorted so that mode with highest occupancy is the 0th shared mode.

class ptychi.api.options.base.ProbeOrthogonalizeOPRModesOptions(enabled: bool = True, optimization_plan: OptimizationPlan = <factory>)[source]

Bases: FeatureOptions

Settings for orthogonalizing OPR modes.

enabled: bool = True: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

class ptychi.api.options.base.ProbeSupportConstraintOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, fixed_probe_support: str = ProbeSupportMethods.NONE, fixed_probe_support_params: ndarray | Tensor = None, threshold: float = 0.005)[source]

Bases: FeatureOptions

Settings for probe support constraint. The constraint applies shrinkwrapping, where small values below a threshold are set to 0. It can also optionally apply a probe support mask before shrinkwrapping.

enabled: bool = False: Turns execution of the feature on and off.

fixed_probe_support: str = 'none': If not NONE, a fixed probe support mask is generated and applied before shrinkwrapping. The mask is applied to each incoherent probe mode. Choices are: ELLIPSE, RECTANGLE.

fixed_probe_support_params: ndarray | Tensor = None: If using the use_fixed_probe_support option, define the center, widths, and heights for the ellipse/rectangle, format is: [center (rows), center (columns), side length (rows), side length (columns)]

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

threshold: float = 0.005: The threshold for shrinkwrapping. The value of a pixel (x, y) is set to 0 if p(x, y) < [max(blur(p)) * `threshold](x, y)`.

class ptychi.api.options.base.ProbeCenterConstraintOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, use_total_intensity_for_com: bool = False, use_intensity_for_com: bool = False, center_modes_individually: bool = False)[source]

Bases: FeatureOptions

Settings for constraining the probe’s center of mass to the center of the probe array.

center_modes_individually: bool = False: If True, each mode is shifted individually based on their own center of mass.

check(options: task_options.PtychographyTaskOptions)[source]: Check if options values are valid.

enabled: bool = False: Turns execution of the feature on and off.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

use_intensity_for_com: bool = False: Deprecated alias for use_total_intensity_for_com.

use_total_intensity_for_com: bool = False: Whether to use the magnitude of the dominant shared probe mode for computing the center of mass of the probe in order to keep it centered, or to use the total probe intensity.

class ptychi.api.options.base.OPRModeWeightsSmoothingOptions(enabled: bool = False, optimization_plan: OptimizationPlan = <factory>, method: OPRWeightSmoothingMethods = OPRWeightSmoothingMethods.MEDIAN, polynomial_degree: int = 4)[source]

Bases: FeatureOptions

Settings for smoothing OPR mode weights.

enabled: bool = False: Turns execution of the feature on and off.

method: OPRWeightSmoothingMethods = 'median'

The method for smoothing OPR mode weights.

MEDIAN: applying a median filter to the weights of each mode.

POLYNOMIAL: fit the weights of each mode with a polynomial of selected degree.

optimization_plan: OptimizationPlan: Schedules when the feature is executed.

polynomial_degree: int = 4: The degree of the polynomial used for smoothing OPR mode weights.

Data Options

class ptychi.api.options.data.PtychographyDataOptions(data: numpy.ndarray | torch.Tensor = None, free_space_propagation_distance_m: float = inf, wavelength_m: float = 1e-09, fft_shift: bool = True, detector_pixel_size_m: float = 1e-08, valid_pixel_mask: numpy.ndarray | torch.Tensor | NoneType = None, save_data_on_device: bool = False)[source]

Bases: Options

data: ndarray | Tensor = None: The intensity data. Use collected data as they are; data should NOT be FFT-shifted or square-rooted.

detector_pixel_size_m: float = 1e-08: The detector pixel size in meters.

fft_shift: bool = True: Whether to FFT-shift the diffraction data.

free_space_propagation_distance_m: float = inf: The free-space propagation distance in meters, or inf for far-field.

get_non_data_fields() → dict[source]: Get fields that do not contain large arrays or tensors.

save_data_on_device: bool = False: Whether to save the diffraction data on acceleration devices like GPU.

valid_pixel_mask: ndarray | Tensor | None = None: A 2D boolean mask where valid pixels are True.

wavelength_m: float = 1e-09: The wavelength in meters.

Difference Map (DM) Options

class ptychi.api.options.dm.DMOptions(data_options: ptychi.api.options.data.PtychographyDataOptions = <factory>, reconstructor_options: ptychi.api.options.dm.DMReconstructorOptions = <factory>, object_options: ptychi.api.options.dm.DMObjectOptions = <factory>, probe_options: ptychi.api.options.dm.DMProbeOptions = <factory>, probe_position_options: ptychi.api.options.dm.DMProbePositionOptions = <factory>, opr_mode_weight_options: ptychi.api.options.dm.DMOPRModeWeightsOptions = <factory>)[source]

Bases: PtychographyTaskOptions

object_options: DMObjectOptions

opr_mode_weight_options: DMOPRModeWeightsOptions

probe_options: DMProbeOptions

probe_position_options: DMProbePositionOptions

reconstructor_options: DMReconstructorOptions

class ptychi.api.options.dm.DMReconstructorOptions(num_epochs: int = 100, batch_size: int = 100, batching_mode: ptychi.api.enums.BatchingModes = <BatchingModes.RANDOM: 'random'>, compact_mode_update_clustering: bool = False, compact_mode_update_clustering_stride: int = 1, default_device: ptychi.api.enums.Devices = <Devices.GPU: 'gpu'>, default_dtype: ptychi.api.enums.Dtypes = <Dtypes.FLOAT32: 'float32'>, use_double_precision_for_fft: bool = False, allow_nondeterministic_algorithms: bool = True, random_seed: int | None = None, displayed_loss_function: ptychi.api.enums.LossFunctions | None = <LossFunctions.MSE_SQRT: 'mse_sqrt'>, exclude_measured_pixels_below: float | None = None, forward_model_options: ptychi.api.options.base.ForwardModelOptions = <factory>, exit_wave_update_relaxation: float = 1, chunk_length: int = 1)[source]

Bases: ReconstructorOptions

chunk_length: int = 1: Number of scan points used in each chunk of the difference map exit wave update loop. Smaller values are more memory efficient, but can be slower.

exit_wave_update_relaxation: float = 1: Relaxation multiplier for the exit wave update.

get_reconstructor_type() → Reconstructors[source]

class ptychi.api.options.dm.DMObjectOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, slice_spacings_m: numpy.ndarray | None = None, slice_spacing_options: ptychi.api.options.base.SliceSpacingOptions = <factory>, pixel_size_m: float = 1.0, pixel_size_aspect_ratio: float = 1.0, l1_norm_constraint: ptychi.api.options.base.ObjectL1NormConstraintOptions = <factory>, l2_norm_constraint: ptychi.api.options.base.ObjectL2NormConstraintOptions = <factory>, smoothness_constraint: ptychi.api.options.base.ObjectSmoothnessConstraintOptions = <factory>, total_variation: ptychi.api.options.base.ObjectTotalVariationOptions = <factory>, hard_limits_magnitude_phase: ptychi.api.options.base.ObjectHardLimitsMagnitudePhase = <factory>, remove_grid_artifacts: ptychi.api.options.base.RemoveGridArtifactsOptions = <factory>, multislice_regularization: ptychi.api.options.base.ObjectMultisliceRegularizationOptions = <factory>, patch_interpolation_method: ptychi.api.enums.PatchInterpolationMethods = <PatchInterpolationMethods.FOURIER: 'fourier'>, remove_object_probe_ambiguity: ptychi.api.options.base.RemoveObjectProbeAmbiguityOptions = <factory>, build_preconditioner_with_all_modes: bool = False, determine_position_origin_coords_by: ptychi.api.enums.ObjectPosOriginCoordsMethods = <ObjectPosOriginCoordsMethods.SUPPORT: 'support'>, position_origin_coords: numpy.ndarray | None = None, amplitude_clamp_limit: float = 1000, inertia: float = 0)[source]

Bases: ObjectOptions

amplitude_clamp_limit: float = 1000: Maximum allowed amplitude for the object reconstruction. Values above this will be clamped to this value.

inertia: float = 0: Inertia of the object update. Should be between 0 and 1.

class ptychi.api.options.dm.DMProbeOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, power_constraint: ptychi.api.options.base.ProbePowerConstraintOptions = <factory>, orthogonalize_incoherent_modes: ptychi.api.options.base.ProbeOrthogonalizeIncoherentModesOptions = <factory>, orthogonalize_opr_modes: ptychi.api.options.base.ProbeOrthogonalizeOPRModesOptions = <factory>, support_constraint: ptychi.api.options.base.ProbeSupportConstraintOptions = <factory>, center_constraint: ptychi.api.options.base.ProbeCenterConstraintOptions = <factory>, eigenmode_update_relaxation: float = 1.0, inertia: float = 0)[source]

Bases: ProbeOptions

inertia: float = 0: Inertia of the probe update. Should be between 0 and 1.

class ptychi.api.options.dm.DMProbePositionOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 0.3, optimizer_params: dict = <factory>, position_x_px: Union[numpy.ndarray, torch.Tensor]=None, position_y_px: Union[numpy.ndarray, torch.Tensor]=None, constrain_position_mean: bool = False, correction_options: ptychi.api.options.base.PositionCorrectionOptions = <factory>, affine_transform_constraint: ptychi.api.options.base.PositionAffineTransformConstraintOptions = <factory>)[source]: Bases: ProbePositionOptions

class ptychi.api.options.dm.DMOPRModeWeightsOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_weights: numpy.ndarray = None, optimize_eigenmode_weights: bool = True, optimize_intensity_variation: bool = False, smoothing: ptychi.api.options.base.OPRModeWeightsSmoothingOptions = <factory>, update_relaxation: float = 1.0)[source]: Bases: OPRModeWeightsOptions

PIE Options

class ptychi.api.options.pie.PIEOptions(data_options: ptychi.api.options.data.PtychographyDataOptions = <factory>, reconstructor_options: ptychi.api.options.pie.PIEReconstructorOptions = <factory>, object_options: ptychi.api.options.pie.PIEObjectOptions = <factory>, probe_options: ptychi.api.options.pie.PIEProbeOptions = <factory>, probe_position_options: ptychi.api.options.pie.PIEProbePositionOptions = <factory>, opr_mode_weight_options: ptychi.api.options.pie.PIEOPRModeWeightsOptions = <factory>)[source]

Bases: PtychographyTaskOptions

object_options: PIEObjectOptions

opr_mode_weight_options: PIEOPRModeWeightsOptions

probe_options: PIEProbeOptions

probe_position_options: PIEProbePositionOptions

reconstructor_options: PIEReconstructorOptions

class ptychi.api.options.pie.PIEReconstructorOptions(num_epochs: int = 100, batch_size: int = 100, batching_mode: ptychi.api.enums.BatchingModes = <BatchingModes.RANDOM: 'random'>, compact_mode_update_clustering: bool = False, compact_mode_update_clustering_stride: int = 1, default_device: ptychi.api.enums.Devices = <Devices.GPU: 'gpu'>, default_dtype: ptychi.api.enums.Dtypes = <Dtypes.FLOAT32: 'float32'>, use_double_precision_for_fft: bool = False, allow_nondeterministic_algorithms: bool = True, random_seed: int | None = None, displayed_loss_function: ptychi.api.enums.LossFunctions | None = <LossFunctions.MSE_SQRT: 'mse_sqrt'>, exclude_measured_pixels_below: float | None = None, forward_model_options: ptychi.api.options.base.ForwardModelOptions = <factory>)[source]

Bases: ReconstructorOptions

get_reconstructor_type() → Reconstructors[source]

class ptychi.api.options.pie.PIEObjectOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, slice_spacings_m: numpy.ndarray | None = None, slice_spacing_options: ptychi.api.options.base.SliceSpacingOptions = <factory>, pixel_size_m: float = 1.0, pixel_size_aspect_ratio: float = 1.0, l1_norm_constraint: ptychi.api.options.base.ObjectL1NormConstraintOptions = <factory>, l2_norm_constraint: ptychi.api.options.base.ObjectL2NormConstraintOptions = <factory>, smoothness_constraint: ptychi.api.options.base.ObjectSmoothnessConstraintOptions = <factory>, total_variation: ptychi.api.options.base.ObjectTotalVariationOptions = <factory>, hard_limits_magnitude_phase: ptychi.api.options.base.ObjectHardLimitsMagnitudePhase = <factory>, remove_grid_artifacts: ptychi.api.options.base.RemoveGridArtifactsOptions = <factory>, multislice_regularization: ptychi.api.options.base.ObjectMultisliceRegularizationOptions = <factory>, patch_interpolation_method: ptychi.api.enums.PatchInterpolationMethods = <PatchInterpolationMethods.FOURIER: 'fourier'>, remove_object_probe_ambiguity: ptychi.api.options.base.RemoveObjectProbeAmbiguityOptions = <factory>, build_preconditioner_with_all_modes: bool = False, determine_position_origin_coords_by: ptychi.api.enums.ObjectPosOriginCoordsMethods = <ObjectPosOriginCoordsMethods.SUPPORT: 'support'>, position_origin_coords: numpy.ndarray | None = None, alpha: float = 0.1)[source]

Bases: ObjectOptions

alpha: float = 0.1: Multiplier for the update to the object, as defined in table 1 of Maiden (2017).

class ptychi.api.options.pie.PIEProbeOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, power_constraint: ptychi.api.options.base.ProbePowerConstraintOptions = <factory>, orthogonalize_incoherent_modes: ptychi.api.options.base.ProbeOrthogonalizeIncoherentModesOptions = <factory>, orthogonalize_opr_modes: ptychi.api.options.base.ProbeOrthogonalizeOPRModesOptions = <factory>, support_constraint: ptychi.api.options.base.ProbeSupportConstraintOptions = <factory>, center_constraint: ptychi.api.options.base.ProbeCenterConstraintOptions = <factory>, eigenmode_update_relaxation: float = 1.0, alpha: float = 0.1, experimental: ptychi.api.options.pie.PIEProbeExperimentalOptions = <factory>)[source]

Bases: ProbeOptions

alpha: float = 0.1: Multiplier for the update to the probe, as defined in table 1 of Maiden (2017).

experimental: PIEProbeExperimentalOptions

class ptychi.api.options.pie.PIEProbePositionOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 0.3, optimizer_params: dict = <factory>, position_x_px: Union[numpy.ndarray, torch.Tensor]=None, position_y_px: Union[numpy.ndarray, torch.Tensor]=None, constrain_position_mean: bool = False, correction_options: ptychi.api.options.base.PositionCorrectionOptions = <factory>, affine_transform_constraint: ptychi.api.options.base.PositionAffineTransformConstraintOptions = <factory>)[source]: Bases: ProbePositionOptions

class ptychi.api.options.pie.PIEOPRModeWeightsOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_weights: numpy.ndarray = None, optimize_eigenmode_weights: bool = True, optimize_intensity_variation: bool = False, smoothing: ptychi.api.options.base.OPRModeWeightsSmoothingOptions = <factory>, update_relaxation: float = 1.0)[source]: Bases: OPRModeWeightsOptions

LSQML Options

class ptychi.api.options.lsqml.LSQMLOptions(data_options: ptychi.api.options.data.PtychographyDataOptions = <factory>, reconstructor_options: ptychi.api.options.lsqml.LSQMLReconstructorOptions = <factory>, object_options: ptychi.api.options.lsqml.LSQMLObjectOptions = <factory>, probe_options: ptychi.api.options.lsqml.LSQMLProbeOptions = <factory>, probe_position_options: ptychi.api.options.lsqml.LSQMLProbePositionOptions = <factory>, opr_mode_weight_options: ptychi.api.options.lsqml.LSQMLOPRModeWeightsOptions = <factory>)[source]

Bases: PtychographyTaskOptions

object_options: LSQMLObjectOptions

opr_mode_weight_options: LSQMLOPRModeWeightsOptions

probe_options: LSQMLProbeOptions

probe_position_options: LSQMLProbePositionOptions

reconstructor_options: LSQMLReconstructorOptions

class ptychi.api.options.lsqml.LSQMLReconstructorOptions(num_epochs: int = 100, batch_size: int = 100, batching_mode: ptychi.api.enums.BatchingModes = <BatchingModes.RANDOM: 'random'>, compact_mode_update_clustering: bool = False, compact_mode_update_clustering_stride: int = 1, default_device: ptychi.api.enums.Devices = <Devices.GPU: 'gpu'>, default_dtype: ptychi.api.enums.Dtypes = <Dtypes.FLOAT32: 'float32'>, use_double_precision_for_fft: bool = False, allow_nondeterministic_algorithms: bool = True, random_seed: int | None = None, displayed_loss_function: ptychi.api.enums.LossFunctions | None = <LossFunctions.MSE_SQRT: 'mse_sqrt'>, exclude_measured_pixels_below: float | None = None, forward_model_options: ptychi.api.options.base.ForwardModelOptions = <factory>, noise_model: ptychi.api.enums.NoiseModels = <NoiseModels.GAUSSIAN: 'gaussian'>, gaussian_noise_std: float = 0.5, single_slice_solve_obj_prb_step_size_jointly: bool = True, multislice_solve_obj_prb_step_size_jointly: bool = False, solve_step_sizes_only_using_first_probe_mode: bool = True, momentum_acceleration_gain: float = 0.0, momentum_acceleration_gradient_mixing_factor: float | None = 1, rescale_probe_intensity_in_first_epoch: bool = True, preconditioning_damping_factor: float = 0.1)[source]

Bases: ReconstructorOptions

check(options: LSQMLOptions)[source]: Check if options values are valid.

gaussian_noise_std: float = 0.5: The standard deviation of the gaussian noise. Only used when noise_model == enums.NoiseModels.GAUSSIAN.

get_reconstructor_type() → Reconstructors[source]

momentum_acceleration_gain: float = 0.0: The gain of momentum acceleration for object and probe. If 0, momentum acceleration is not used.

momentum_acceleration_gradient_mixing_factor: float | None = 1

Controls how the current gradient is mixed with the accumulated velocity in LSQML momentum acceleration:

velocity = (1 - friction) * velocity + momentum_acceleration_gradient_mixing_factor * delta_o

If None, this mixing factor is automatically chosen to be friction:

velocity = (1 - friction) * velocity + friction * delta_o

Using None usually provides better stability. However, it may cause the speed of convergence to be too slow in some cases. Set this parameter to 1 to reproduce the behavior in PtychoShelves.

multislice_solve_obj_prb_step_size_jointly: bool = False: Whether to solve the object/probe step size jointly for multislice objects at the first slice. Slices other than the first are always solved independently. For single-slice objects, use single_slice_solve_obj_prb_step_size_jointly instead.

noise_model: NoiseModels = 'gaussian': The noise model to use.

preconditioning_damping_factor: float = 0.1

The damping factor for applying preconditioning to the object update, which is calculated as:

delta_o_hat = delta_o_hat / torch.sqrt(preconditioner ** 2 + (preconditioner.max() * mixing_factor) ** 2)

rescale_probe_intensity_in_first_epoch: bool = True: If True, probe intensity is rescaled in the first epoch using the average intensity of all diffraction patterns. Set this to False if you want the probe intensity to stay constant. You may also want to check ObjectOptions.remove_object_probe_ambiguity.

single_slice_solve_obj_prb_step_size_jointly: bool = True: Whether to solve the object/probe step size jointly for single-slice objects. For multislice objects, use multislice_solve_obj_prb_step_size_jointly instead.

solve_step_sizes_only_using_first_probe_mode: bool = True: If True, object and probe step sizes will only be calculated using the first probe mode. This is how it is done in PtychoShelves.

class ptychi.api.options.lsqml.LSQMLObjectOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, slice_spacings_m: numpy.ndarray | None = None, slice_spacing_options: ptychi.api.options.base.SliceSpacingOptions = <factory>, pixel_size_m: float = 1.0, pixel_size_aspect_ratio: float = 1.0, l1_norm_constraint: ptychi.api.options.base.ObjectL1NormConstraintOptions = <factory>, l2_norm_constraint: ptychi.api.options.base.ObjectL2NormConstraintOptions = <factory>, smoothness_constraint: ptychi.api.options.base.ObjectSmoothnessConstraintOptions = <factory>, total_variation: ptychi.api.options.base.ObjectTotalVariationOptions = <factory>, hard_limits_magnitude_phase: ptychi.api.options.base.ObjectHardLimitsMagnitudePhase = <factory>, remove_grid_artifacts: ptychi.api.options.base.RemoveGridArtifactsOptions = <factory>, multislice_regularization: ptychi.api.options.base.ObjectMultisliceRegularizationOptions = <factory>, patch_interpolation_method: ptychi.api.enums.PatchInterpolationMethods = <PatchInterpolationMethods.FOURIER: 'fourier'>, remove_object_probe_ambiguity: ptychi.api.options.base.RemoveObjectProbeAmbiguityOptions = <factory>, build_preconditioner_with_all_modes: bool = False, determine_position_origin_coords_by: ptychi.api.enums.ObjectPosOriginCoordsMethods = <ObjectPosOriginCoordsMethods.SUPPORT: 'support'>, position_origin_coords: numpy.ndarray | None = None, optimal_step_size_scaler: float = 0.9, multimodal_update: bool = True)[source]

Bases: ObjectOptions

multimodal_update: bool = True: If True, object update direction is calculated and summed over all probe modes. Otherwise, only the first mode will be used for object update. However, forward propagation always uses all probe modes regardless of this option.

optimal_step_size_scaler: float = 0.9: A scaler for the solved optimal step size (beta_LSQ in PtychoShelves).

class ptychi.api.options.lsqml.LSQMLProbeOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, power_constraint: ptychi.api.options.base.ProbePowerConstraintOptions = <factory>, orthogonalize_incoherent_modes: ptychi.api.options.base.ProbeOrthogonalizeIncoherentModesOptions = <factory>, orthogonalize_opr_modes: ptychi.api.options.base.ProbeOrthogonalizeOPRModesOptions = <factory>, support_constraint: ptychi.api.options.base.ProbeSupportConstraintOptions = <factory>, center_constraint: ptychi.api.options.base.ProbeCenterConstraintOptions = <factory>, eigenmode_update_relaxation: float = 1.0, optimal_step_size_scaler: float = 0.9)[source]

Bases: ProbeOptions

optimal_step_size_scaler: float = 0.9: A scaler for the solved optimal step size (beta_LSQ in PtychoShelves).

class ptychi.api.options.lsqml.LSQMLProbePositionOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 0.3, optimizer_params: dict = <factory>, position_x_px: Union[numpy.ndarray, torch.Tensor]=None, position_y_px: Union[numpy.ndarray, torch.Tensor]=None, constrain_position_mean: bool = False, correction_options: ptychi.api.options.base.PositionCorrectionOptions = <factory>, affine_transform_constraint: ptychi.api.options.base.PositionAffineTransformConstraintOptions = <factory>, momentum_acceleration_gain: float = 0.0, momentum_acceleration_gradient_mixing_factor: float | None = 1, momentum_acceleration_memory: int = 3)[source]

Bases: ProbePositionOptions

check(options: LSQMLOptions)[source]: Check if options values are valid.

momentum_acceleration_gain: float = 0.0: The gain of momentum acceleration for probe positions. If 0, momentum acceleration is not used.

momentum_acceleration_gradient_mixing_factor: float | None = 1

Controls how the current position update is mixed with the accumulated velocity in probe-position momentum acceleration:

velocity = (1 - friction) * velocity + momentum_acceleration_gradient_mixing_factor * delta_pos

If None, this mixing factor is automatically chosen to be friction. Set this parameter to 1 to reproduce the behavior in foldslice.

momentum_acceleration_memory: int = 3: Number of previous epochs used to estimate the friction of probe-position momentum acceleration.

class ptychi.api.options.lsqml.LSQMLOPRModeWeightsOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_weights: numpy.ndarray = None, optimize_eigenmode_weights: bool = True, optimize_intensity_variation: bool = False, smoothing: ptychi.api.options.base.OPRModeWeightsSmoothingOptions = <factory>, update_relaxation: float = 1.0)[source]: Bases: OPRModeWeightsOptions

Autodiff Ptychography Options

class ptychi.api.options.ad_ptychography.AutodiffPtychographyOptions(data_options: ptychi.api.options.data.PtychographyDataOptions = <factory>, reconstructor_options: ptychi.api.options.ad_ptychography.AutodiffPtychographyReconstructorOptions = <factory>, object_options: ptychi.api.options.ad_ptychography.AutodiffPtychographyObjectOptions = <factory>, probe_options: ptychi.api.options.ad_ptychography.AutodiffPtychographyProbeOptions = <factory>, probe_position_options: ptychi.api.options.ad_ptychography.AutodiffPtychographyProbePositionOptions = <factory>, opr_mode_weight_options: ptychi.api.options.ad_ptychography.AutodiffPtychographyOPRModeWeightsOptions = <factory>)[source]

Bases: PtychographyTaskOptions

object_options: AutodiffPtychographyObjectOptions

opr_mode_weight_options: AutodiffPtychographyOPRModeWeightsOptions

probe_options: AutodiffPtychographyProbeOptions

probe_position_options: AutodiffPtychographyProbePositionOptions

reconstructor_options: AutodiffPtychographyReconstructorOptions

class ptychi.api.options.ad_ptychography.AutodiffPtychographyReconstructorOptions(num_epochs: int = 100, batch_size: int = 100, batching_mode: ptychi.api.enums.BatchingModes = <BatchingModes.RANDOM: 'random'>, compact_mode_update_clustering: bool = False, compact_mode_update_clustering_stride: int = 1, default_device: ptychi.api.enums.Devices = <Devices.GPU: 'gpu'>, default_dtype: ptychi.api.enums.Dtypes = <Dtypes.FLOAT32: 'float32'>, use_double_precision_for_fft: bool = False, allow_nondeterministic_algorithms: bool = True, random_seed: int | None = None, displayed_loss_function: ptychi.api.enums.LossFunctions | None = <LossFunctions.MSE_SQRT: 'mse_sqrt'>, exclude_measured_pixels_below: float | None = None, forward_model_options: ptychi.api.options.base.ForwardModelOptions = <factory>, loss_function: ptychi.api.enums.LossFunctions = <LossFunctions.MSE_SQRT: 'mse_sqrt'>, forward_model_class: Union[ForwardRef('enums.ForwardModels'), Type[ForwardRef('fm.ForwardModel')]]=<ForwardModels.PLANAR_PTYCHOGRAPHY: 'planar_ptychography'>, forward_model_params: dict | None = None)[source]

Bases: AutodiffReconstructorOptions

forward_model_class: ForwardModels | Type[ForwardModel] = 'planar_ptychography': The forward model class.

get_reconstructor_type() → Reconstructors[source]

class ptychi.api.options.ad_ptychography.AutodiffPtychographyObjectOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, slice_spacings_m: numpy.ndarray | None = None, slice_spacing_options: ptychi.api.options.base.SliceSpacingOptions = <factory>, pixel_size_m: float = 1.0, pixel_size_aspect_ratio: float = 1.0, l1_norm_constraint: ptychi.api.options.base.ObjectL1NormConstraintOptions = <factory>, l2_norm_constraint: ptychi.api.options.base.ObjectL2NormConstraintOptions = <factory>, smoothness_constraint: ptychi.api.options.base.ObjectSmoothnessConstraintOptions = <factory>, total_variation: ptychi.api.options.base.ObjectTotalVariationOptions = <factory>, hard_limits_magnitude_phase: ptychi.api.options.base.ObjectHardLimitsMagnitudePhase = <factory>, remove_grid_artifacts: ptychi.api.options.base.RemoveGridArtifactsOptions = <factory>, multislice_regularization: ptychi.api.options.base.ObjectMultisliceRegularizationOptions = <factory>, patch_interpolation_method: ptychi.api.enums.PatchInterpolationMethods = <PatchInterpolationMethods.FOURIER: 'fourier'>, remove_object_probe_ambiguity: ptychi.api.options.base.RemoveObjectProbeAmbiguityOptions = <factory>, build_preconditioner_with_all_modes: bool = False, determine_position_origin_coords_by: ptychi.api.enums.ObjectPosOriginCoordsMethods = <ObjectPosOriginCoordsMethods.SUPPORT: 'support'>, position_origin_coords: numpy.ndarray | None = None, experimental: ptychi.api.options.ad_ptychography.AutodiffPtychographyObjectExperimentalOptions = <factory>)[source]

Bases: ObjectOptions

experimental: AutodiffPtychographyObjectExperimentalOptions

class ptychi.api.options.ad_ptychography.AutodiffPtychographyProbeOptions(optimizable: bool = True, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_guess: Union[numpy.ndarray, torch.Tensor]=None, power_constraint: ptychi.api.options.base.ProbePowerConstraintOptions = <factory>, orthogonalize_incoherent_modes: ptychi.api.options.base.ProbeOrthogonalizeIncoherentModesOptions = <factory>, orthogonalize_opr_modes: ptychi.api.options.base.ProbeOrthogonalizeOPRModesOptions = <factory>, support_constraint: ptychi.api.options.base.ProbeSupportConstraintOptions = <factory>, center_constraint: ptychi.api.options.base.ProbeCenterConstraintOptions = <factory>, eigenmode_update_relaxation: float = 1.0, experimental: ptychi.api.options.ad_ptychography.AutodiffPtychographyProbeExperimentalOptions = <factory>)[source]

Bases: ProbeOptions

experimental: AutodiffPtychographyProbeExperimentalOptions

class ptychi.api.options.ad_ptychography.AutodiffPtychographyProbePositionOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 0.3, optimizer_params: dict = <factory>, position_x_px: Union[numpy.ndarray, torch.Tensor]=None, position_y_px: Union[numpy.ndarray, torch.Tensor]=None, constrain_position_mean: bool = False, correction_options: ptychi.api.options.base.PositionCorrectionOptions = <factory>, affine_transform_constraint: ptychi.api.options.base.PositionAffineTransformConstraintOptions = <factory>)[source]: Bases: ProbePositionOptions

class ptychi.api.options.ad_ptychography.AutodiffPtychographyOPRModeWeightsOptions(optimizable: bool = False, optimization_plan: ptychi.api.options.base.OptimizationPlan = <factory>, optimizer: ptychi.api.enums.Optimizers = <Optimizers.SGD: 'sgd'>, step_size: float = 1, optimizer_params: dict = <factory>, initial_weights: numpy.ndarray = None, optimize_eigenmode_weights: bool = True, optimize_intensity_variation: bool = False, smoothing: ptychi.api.options.base.OPRModeWeightsSmoothingOptions = <factory>, update_relaxation: float = 1.0)[source]: Bases: OPRModeWeightsOptions