Skip to content

patch_cloak

Module for Patch Cloak noise layers.

Classes:

Name Description
PatchCloakNoiseLayer

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d

PatchCloakNoiseLayer1

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d

PatchCloakNoiseLayer2

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d

PatchCloakNoiseLayer2_NoClip

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d

PatchCloakNoiseLayer

Bases: BaseNoiseLayer[Conv2d, CloakStandardDeviationParameterization, BatchwiseChannelwisePatchwisePercentMasker | None]

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d estimators, with standard deviations parameterized by CloakStandardDeviationParameterization, optional standard deviation-based input masking using BatchwiseChannelwisePatchwisePercentMasker, and optional output clamping.

Parameters:

Name Type Description Default

color_channels

int

The number of color channels in the input.

required

patch_size

int | tuple[int, int]

Size of the patches to segment the input into. If an integer is given, a square patch is used.

required

scale

tuple[float, float]

Minimum and maximum values of the range of standard deviations of the generated stochastic transformation.

(0.0001, 2.0)

shallow

float

A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.

1.0

percent_to_mask

float | None

The percentage of the outputs to mask per patch.

None

value_range

tuple[float | None, float | None] | None

Minimum and maximum values of the range to clamp the output into.

None

padding_mode

Literal['constant', 'reflect', 'replicate', 'circular']

Type of padding. One of: constant, reflect, replicate, or circular. Defaults to constant.

'constant'

padding_value

float

Fill value for constant padding.

0.0

learn_locs_weights

bool

Whether to learn the weight parameters for the locs estimator. If True, only the weights will be learned, and the bias remains constant, otherwise weights are initialized to zero and only the bias is learned.

True

freeze_std_estimator

bool

Whether to freeze the weight parameters for the std estimator. If False, this estimator will be trained simultaneously with masking and the locs estimator parameters.

True

seed

int | None

Seed for the random number generator used to generate the stochastic transformation. If None, the global RNG state is used.

None
Note

For estimators where we train the weights, we freeze their biases. We suspect that if both the biases and weights are trained together, the biases will converge faster than the weights, causing the weights to be trivial. This has not been verified experimentally. Our choices for initialization values and conditions subject to change in light of experimental evidence, and you are encouraged to challenge and improve our understanding of the effects of these choices.

Methods:

Name Description
__call__

Transform the input data.

__getstate__

Prepare a JSON-serializable copy of the noise layer's state.

__setstate__

Set the state of the object.

forward

Transform the input data.

get_applied_transform_components_factory

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent

get_transformed_output_factory

Create a function that returns the transformed output from the most recent forward pass.

initial_seed

Return the initial seed of the CPU device's random number generator.

manual_seed

Seed each of the random number generators.

reset_parameters

Reinitialize parameters and buffers.

seed

Seed each of the random number generators using a non-deterministic random number.

set_input_scale

Set the power of two that the input is divided by before it is transformed, and the output multiplied by afterwards.

Attributes:

Name Type Description
patch_size tuple[int, int]

The size of the patches to segment the input into.

post_processor_is_final bool

Whether the post-processor is the last step of this noise layer's forward pass.

patch_size property

patch_size: tuple[int, int]

The size of the patches to segment the input into.

post_processor_is_final class-attribute

post_processor_is_final: bool = False

Whether the post-processor is the last step of this noise layer's forward pass.

Set this to True only in a subclass whose forward pass returns the attached post-processor's output with no further transformation. Leave it False in any subclass that transforms the value returned by BaseNoiseLayer.forward, for example by clamping it. NoisyModel.teacher_and_student_forward requires it to read a post-processed noise layer's output with the post-processor skipped.

__call__

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name Type Description Default

input

Tensor

The input to transform.

required

noise_mask

Tensor | None

An optional mask that selects the elements of input to transform. Where the mask is False, the original input value is returned. Also used to select the elements of the sampled standard deviations to use to mask the input. If None, the entire input is transformed.

None

**kwargs

Any

Additional keyword arguments to the estimator modules.

required

Changed in version v5.1.0: The input is now divided by `input_scale` before it is transformed and the output multiplied by it afterwards. Behavior is unchanged for an input scale of `1`, which is the default.

__getstate__

__getstate__() -> dict[str, Any]

Prepare a JSON-serializable copy of the noise layer's state.

Returns:

Type Description
dict[str, Any]

A dictionary containing the configuration of the noise layer, including its type string, the state dict, and the generator

dict[str, Any]

states if they exist.

Changed in version v3.15.0: Added serialization support for all noise layers.

__setstate__

__setstate__(
    state: dict[str, Any],
    trust_remote_code: bool = False,
    third_party_model_path: str
    | PathLike[str]
    | None = None,
) -> None

Set the state of the object.

state_dict and _generators are both optional keys, and will be restored if they exist in the state.

Parameters:

Name Type Description Default

state

dict[str, Any]

The state to set.

required

trust_remote_code

bool

Whether to trust remote code when loading from HuggingFace Hub.

False

third_party_model_path

str | PathLike[str] | None

The path or huggingface reference to a third-party model to load. This is useful when loading SGTs whose internal structure depends on transformers which are not importable directly through transformers, but are present on the Hugging Face Hub.

None

Changed in version v3.15.0: Added serialization support for all noise layers.

forward

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name Type Description Default

input

Tensor

The input to transform.

required

noise_mask

Tensor | None

An optional mask that selects the elements of input to transform. Where the mask is 0, the original input value is returned. Also used to select the elements of the sampled standard deviations to use to mask the input. If None, the entire input is transformed.

None

**kwargs

Any

Additional keyword arguments to the estimator modules.

required

Returns:

Type Description
torch.Tensor

The transformed input data.

get_applied_transform_components_factory

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened. They are returned at the scale they are applied at: the estimates multiplied by input_scale.

This function is intended to be used to log histograms of the transform components.

Returns:

Type Description
Callable[[], dict[str, torch.Tensor]]

A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

Changed in version v5.1.0: The transform components are now returned at the scale they are applied at, multiplied by `input_scale`. Behavior is unchanged for an input scale of `1`, which is the default.

get_transformed_output_factory

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned. The output is returned at the scale of the noise layer's input, so it is unaffected by input_scale.

Returns:

Type Description
Callable[[], torch.Tensor]

A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

Changed in version v5.1.0: The transformed output is now returned at the scale of the noise layer's input, multiplied by `input_scale`. Behavior is unchanged for an input scale of `1`, which is the default.

initial_seed

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed

manual_seed(
    seed: int | None, rank_dependent: bool = True
) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators, disabling reproducible behavior until the next call with an integer seed. Calling manual_seed again with an integer after a None call fully recreates generators for every currently available device type (CPU, CUDA, MPS) before applying the seed, making the operation safely reversible.

Parameters:

Name Type Description Default

seed

int | None

The seed to set. Pass None to disable reproducible behavior.

required

rank_dependent

bool

Whether to add the distributed rank to the seed to ensure that each process samples different noise.

True

reset_parameters

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

set_input_scale

set_input_scale(scale: float) -> None

Set the power of two that the input is divided by before it is transformed, and the output multiplied by afterwards.

With an input scale s, the noise layer returns s * T(input / s), where T is the transformation it would apply with an input scale of 1. Elements the noise mask leaves untransformed are returned exactly as they were input. The estimators, the post-processor, and every loss computed from activations captured inside the noise layer (for example its estimated means and standard deviations, or its output captured by a hook_loss_wrapper hook) see the scaled-down values. Losses computed from activations outside the noise layer, such as a base model's logits, see the noise layer's full-scale output.

The scale must be a power of two from 2**-14 to 2**14. The scale and its reciprocal are then exact in every floating point dtype, including torch.float16, so casting the noise layer to another dtype preserves the scale, and dividing and multiplying by it is exact wherever the result is a normal number.

Parameters:

Name Type Description Default

scale

float

The input scale, a power of two from 2**-14 to 2**14.

required

Examples:

A noise layer whose initialization suits inputs with a root mean square of about 0.01 can transform inputs with a root mean square of about 0.5 at the scale it was calibrated for:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1(seed=0)
>>> noise_layer.set_input_scale(64.0)
>>> noise_layer.input_scale
tensor(64.)
>>> output = noise_layer(torch.randn(2, 8) * 0.5)

The scale must be a power of two:

>>> noise_layer.set_input_scale(50.0)
Traceback (most recent call last):
...
ValueError: The input scale must be a power of two from 2**-14 to 2**14, but got 50.0.

Added in version v5.1.0.

PatchCloakNoiseLayer1

Bases: PatchCloakNoiseLayer

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d estimators and with standard deviations parameterized by CloakStandardDeviationParameterization.

Parameters:

Name Type Description Default

color_channels

int

The number of color channels in the input.

required

patch_size

int | tuple[int, int]

The size of the patches over which the stochastic transformation is estimated.

required

scale

tuple[float, float]

The range of standard deviations of the stochastic transformation.

required

shallow

float

A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.

1.0

padding_mode

Literal['constant', 'reflect', 'replicate', 'circular']

The padding mode to use when extracting patches.

'constant'

padding_value

float

The value to use when padding the input.

0.0

learn_locs_weights

bool

Whether to only learn the locs estimator weights or else to only learn the locs estimator bias.

True

seed

int | None

Seed for the random number generator used to generate the stochastic transformation. If None, the global RNG state is used.

None
Note

For maximum privacy preservation, Stained Glass Patch Transform Step 1 should only be used to pre-train a Stained Glass Transform Patch Step 2 (see PatchCloakNoiseLayer1_NoClip). First training a Step 1, then fine-tuning that transform with step 2 is a common recipe.

Methods:

Name Description
__call__

Transform the input data.

__getstate__

Prepare a JSON-serializable copy of the noise layer's state.

__setstate__

Set the state of the object.

forward

Transform the input data.

get_applied_transform_components_factory

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent

get_transformed_output_factory

Create a function that returns the transformed output from the most recent forward pass.

initial_seed

Return the initial seed of the CPU device's random number generator.

manual_seed

Seed each of the random number generators.

reset_parameters

Reinitialize parameters and buffers.

seed

Seed each of the random number generators using a non-deterministic random number.

set_input_scale

Set the power of two that the input is divided by before it is transformed, and the output multiplied by afterwards.

Attributes:

Name Type Description
patch_size tuple[int, int]

The size of the patches to segment the input into.

post_processor_is_final bool

Whether the post-processor is the last step of this noise layer's forward pass.

patch_size property

patch_size: tuple[int, int]

The size of the patches to segment the input into.

post_processor_is_final class-attribute

post_processor_is_final: bool = False

Whether the post-processor is the last step of this noise layer's forward pass.

Set this to True only in a subclass whose forward pass returns the attached post-processor's output with no further transformation. Leave it False in any subclass that transforms the value returned by BaseNoiseLayer.forward, for example by clamping it. NoisyModel.teacher_and_student_forward requires it to read a post-processed noise layer's output with the post-processor skipped.

__call__

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name Type Description Default

input

Tensor

The input to transform.

required

noise_mask

Tensor | None

An optional mask that selects the elements of input to transform. Where the mask is False, the original input value is returned. Also used to select the elements of the sampled standard deviations to use to mask the input. If None, the entire input is transformed.

None

**kwargs

Any

Additional keyword arguments to the estimator modules.

required

Changed in version v5.1.0: The input is now divided by `input_scale` before it is transformed and the output multiplied by it afterwards. Behavior is unchanged for an input scale of `1`, which is the default.

__getstate__

__getstate__() -> dict[str, Any]

Prepare a JSON-serializable copy of the noise layer's state.

Returns:

Type Description
dict[str, Any]

A dictionary containing the configuration of the noise layer, including its type string, the state dict, and the generator

dict[str, Any]

states if they exist.

Changed in version v3.15.0: Added serialization support for all noise layers.

__setstate__

__setstate__(
    state: dict[str, Any],
    trust_remote_code: bool = False,
    third_party_model_path: str
    | PathLike[str]
    | None = None,
) -> None

Set the state of the object.

state_dict and _generators are both optional keys, and will be restored if they exist in the state.

Parameters:

Name Type Description Default

state

dict[str, Any]

The state to set.

required

trust_remote_code

bool

Whether to trust remote code when loading from HuggingFace Hub.

False

third_party_model_path

str | PathLike[str] | None

The path or huggingface reference to a third-party model to load. This is useful when loading SGTs whose internal structure depends on transformers which are not importable directly through transformers, but are present on the Hugging Face Hub.

None

Changed in version v3.15.0: Added serialization support for all noise layers.

forward

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name Type Description Default

input

Tensor

The input to transform.

required

noise_mask

Tensor | None

An optional mask that selects the elements of input to transform. Where the mask is 0, the original input value is returned. Also used to select the elements of the sampled standard deviations to use to mask the input. If None, the entire input is transformed.

None

**kwargs

Any

Additional keyword arguments to the estimator modules.

required

Returns:

Type Description
torch.Tensor

The transformed input data.

get_applied_transform_components_factory

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened. They are returned at the scale they are applied at: the estimates multiplied by input_scale.

This function is intended to be used to log histograms of the transform components.

Returns:

Type Description
Callable[[], dict[str, torch.Tensor]]

A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

Changed in version v5.1.0: The transform components are now returned at the scale they are applied at, multiplied by `input_scale`. Behavior is unchanged for an input scale of `1`, which is the default.

get_transformed_output_factory

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned. The output is returned at the scale of the noise layer's input, so it is unaffected by input_scale.

Returns:

Type Description
Callable[[], torch.Tensor]

A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

Changed in version v5.1.0: The transformed output is now returned at the scale of the noise layer's input, multiplied by `input_scale`. Behavior is unchanged for an input scale of `1`, which is the default.

initial_seed

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed

manual_seed(
    seed: int | None, rank_dependent: bool = True
) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators, disabling reproducible behavior until the next call with an integer seed. Calling manual_seed again with an integer after a None call fully recreates generators for every currently available device type (CPU, CUDA, MPS) before applying the seed, making the operation safely reversible.

Parameters:

Name Type Description Default

seed

int | None

The seed to set. Pass None to disable reproducible behavior.

required

rank_dependent

bool

Whether to add the distributed rank to the seed to ensure that each process samples different noise.

True

reset_parameters

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

set_input_scale

set_input_scale(scale: float) -> None

Set the power of two that the input is divided by before it is transformed, and the output multiplied by afterwards.

With an input scale s, the noise layer returns s * T(input / s), where T is the transformation it would apply with an input scale of 1. Elements the noise mask leaves untransformed are returned exactly as they were input. The estimators, the post-processor, and every loss computed from activations captured inside the noise layer (for example its estimated means and standard deviations, or its output captured by a hook_loss_wrapper hook) see the scaled-down values. Losses computed from activations outside the noise layer, such as a base model's logits, see the noise layer's full-scale output.

The scale must be a power of two from 2**-14 to 2**14. The scale and its reciprocal are then exact in every floating point dtype, including torch.float16, so casting the noise layer to another dtype preserves the scale, and dividing and multiplying by it is exact wherever the result is a normal number.

Parameters:

Name Type Description Default

scale

float

The input scale, a power of two from 2**-14 to 2**14.

required

Examples:

A noise layer whose initialization suits inputs with a root mean square of about 0.01 can transform inputs with a root mean square of about 0.5 at the scale it was calibrated for:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1(seed=0)
>>> noise_layer.set_input_scale(64.0)
>>> noise_layer.input_scale
tensor(64.)
>>> output = noise_layer(torch.randn(2, 8) * 0.5)

The scale must be a power of two:

>>> noise_layer.set_input_scale(50.0)
Traceback (most recent call last):
...
ValueError: The input scale must be a power of two from 2**-14 to 2**14, but got 50.0.

Added in version v5.1.0.

PatchCloakNoiseLayer2

Bases: PatchCloakNoiseLayer

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d estimators, with standard deviations parameterized by CloakStandardDeviationParameterization, standard deviation-based input masking using BatchwiseChannelwisePatchwisePercentMasker, and output clamping.

Parameters:

Name Type Description Default

color_channels

int

The number of color channels in the input.

required

patch_size

int | tuple[int, int]

Size of the patches to segment the input into. If an integer is given, a square patch is used.

required

scale

tuple[float, float]

Minimum and maximum values of the range of standard deviations of the generated stochastic transformation.

required

percent_to_mask

float

The percentage of the outputs to mask per patch.

required

shallow

float

A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.

1.0

value_range

tuple[float | None, float | None]

Minimum and maximum values of the range to clamp the output into.

(-1.0, 1.0)

padding_mode

Literal['constant', 'reflect', 'replicate', 'circular']

Type of padding. One of: constant, reflect, replicate, or circular. Defaults to constant.

'constant'

padding_value

float

Fill value for constant padding.

0.0

learn_locs_weights

bool

Whether to learn the weight parameters for the locs estimator. If True, only the weights will be learned, and the bias remains constant, otherwise weights are initialized to zero and only the bias is learned.

True

freeze_std_estimator

bool

Whether to freeze the weight parameters for the std estimator. If False, this estimator will be trained simultaneously with masking and the locs estimator parameters.

True

seed

int | None

Seed for the random number generator used to generate the stochastic transformation. If None, the global RNG state is used.

None
Note

For maximum privacy preservation, Stained Glass Transform Patch Step 2 should be pre-trained from a Stained Glass Transform Patch Step 1.

Methods:

Name Description
__call__

Transform the input data.

__getstate__

Prepare a JSON-serializable copy of the noise layer's state.

__setstate__

Set the state of the object.

forward

Transform the input data.

get_applied_transform_components_factory

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent

get_transformed_output_factory

Create a function that returns the transformed output from the most recent forward pass.

initial_seed

Return the initial seed of the CPU device's random number generator.

manual_seed

Seed each of the random number generators.

reset_parameters

Reinitialize parameters and buffers.

seed

Seed each of the random number generators using a non-deterministic random number.

set_input_scale

Set the power of two that the input is divided by before it is transformed, and the output multiplied by afterwards.

Attributes:

Name Type Description
patch_size tuple[int, int]

The size of the patches to segment the input into.

post_processor_is_final bool

Whether the post-processor is the last step of this noise layer's forward pass.

patch_size property

patch_size: tuple[int, int]

The size of the patches to segment the input into.

post_processor_is_final class-attribute

post_processor_is_final: bool = False

Whether the post-processor is the last step of this noise layer's forward pass.

Set this to True only in a subclass whose forward pass returns the attached post-processor's output with no further transformation. Leave it False in any subclass that transforms the value returned by BaseNoiseLayer.forward, for example by clamping it. NoisyModel.teacher_and_student_forward requires it to read a post-processed noise layer's output with the post-processor skipped.

__call__

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name Type Description Default

input

Tensor

The input to transform.

required

noise_mask

Tensor | None

An optional mask that selects the elements of input to transform. Where the mask is False, the original input value is returned. Also used to select the elements of the sampled standard deviations to use to mask the input. If None, the entire input is transformed.

None

**kwargs

Any

Additional keyword arguments to the estimator modules.

required

Changed in version v5.1.0: The input is now divided by `input_scale` before it is transformed and the output multiplied by it afterwards. Behavior is unchanged for an input scale of `1`, which is the default.

__getstate__

__getstate__() -> dict[str, Any]

Prepare a JSON-serializable copy of the noise layer's state.

Returns:

Type Description
dict[str, Any]

A dictionary containing the configuration of the noise layer, including its type string, the state dict, and the generator

dict[str, Any]

states if they exist.

Changed in version v3.15.0: Added serialization support for all noise layers.

__setstate__

__setstate__(
    state: dict[str, Any],
    trust_remote_code: bool = False,
    third_party_model_path: str
    | PathLike[str]
    | None = None,
) -> None

Set the state of the object.

state_dict and _generators are both optional keys, and will be restored if they exist in the state.

Parameters:

Name Type Description Default

state

dict[str, Any]

The state to set.

required

trust_remote_code

bool

Whether to trust remote code when loading from HuggingFace Hub.

False

third_party_model_path

str | PathLike[str] | None

The path or huggingface reference to a third-party model to load. This is useful when loading SGTs whose internal structure depends on transformers which are not importable directly through transformers, but are present on the Hugging Face Hub.

None

Changed in version v3.15.0: Added serialization support for all noise layers.

forward

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name Type Description Default

input

Tensor

The input to transform.

required

noise_mask

Tensor | None

An optional mask that selects the elements of input to transform. Where the mask is 0, the original input value is returned. Also used to select the elements of the sampled standard deviations to use to mask the input. If None, the entire input is transformed.

None

**kwargs

Any

Additional keyword arguments to the estimator modules.

required

Returns:

Type Description
torch.Tensor

The transformed input data.

get_applied_transform_components_factory

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened. They are returned at the scale they are applied at: the estimates multiplied by input_scale.

This function is intended to be used to log histograms of the transform components.

Returns:

Type Description
Callable[[], dict[str, torch.Tensor]]

A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

Changed in version v5.1.0: The transform components are now returned at the scale they are applied at, multiplied by `input_scale`. Behavior is unchanged for an input scale of `1`, which is the default.

get_transformed_output_factory

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned. The output is returned at the scale of the noise layer's input, so it is unaffected by input_scale.

Returns:

Type Description
Callable[[], torch.Tensor]

A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

Changed in version v5.1.0: The transformed output is now returned at the scale of the noise layer's input, multiplied by `input_scale`. Behavior is unchanged for an input scale of `1`, which is the default.

initial_seed

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed

manual_seed(
    seed: int | None, rank_dependent: bool = True
) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators, disabling reproducible behavior until the next call with an integer seed. Calling manual_seed again with an integer after a None call fully recreates generators for every currently available device type (CPU, CUDA, MPS) before applying the seed, making the operation safely reversible.

Parameters:

Name Type Description Default

seed

int | None

The seed to set. Pass None to disable reproducible behavior.

required

rank_dependent

bool

Whether to add the distributed rank to the seed to ensure that each process samples different noise.

True

reset_parameters

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

set_input_scale

set_input_scale(scale: float) -> None

Set the power of two that the input is divided by before it is transformed, and the output multiplied by afterwards.

With an input scale s, the noise layer returns s * T(input / s), where T is the transformation it would apply with an input scale of 1. Elements the noise mask leaves untransformed are returned exactly as they were input. The estimators, the post-processor, and every loss computed from activations captured inside the noise layer (for example its estimated means and standard deviations, or its output captured by a hook_loss_wrapper hook) see the scaled-down values. Losses computed from activations outside the noise layer, such as a base model's logits, see the noise layer's full-scale output.

The scale must be a power of two from 2**-14 to 2**14. The scale and its reciprocal are then exact in every floating point dtype, including torch.float16, so casting the noise layer to another dtype preserves the scale, and dividing and multiplying by it is exact wherever the result is a normal number.

Parameters:

Name Type Description Default

scale

float

The input scale, a power of two from 2**-14 to 2**14.

required

Examples:

A noise layer whose initialization suits inputs with a root mean square of about 0.01 can transform inputs with a root mean square of about 0.5 at the scale it was calibrated for:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1(seed=0)
>>> noise_layer.set_input_scale(64.0)
>>> noise_layer.input_scale
tensor(64.)
>>> output = noise_layer(torch.randn(2, 8) * 0.5)

The scale must be a power of two:

>>> noise_layer.set_input_scale(50.0)
Traceback (most recent call last):
...
ValueError: The input scale must be a power of two from 2**-14 to 2**14, but got 50.0.

Added in version v5.1.0.

PatchCloakNoiseLayer2_NoClip

Bases: PatchCloakNoiseLayer

Applies an input-dependent stochastic transformation to an image in non-overlapping patches using Conv2d estimators, with standard deviations parameterized by CloakStandardDeviationParameterization, and standard deviation-based input masking using BatchwiseChannelwisePatchwisePercentMasker.

Parameters:

Name Type Description Default

color_channels

int

The number of color channels in the input.

required

patch_size

int | tuple[int, int]

Size of the patches to segment the input into. If an integer is given, a square patch is used.

required

scale

tuple[float, float]

Minimum and maximum values of the range of standard deviations of the generated stochastic transformation.

required

percent_to_mask

float

The percentage of the outputs to mask per patch.

required

shallow

float

A temperature-like parameter which controls the spread of the parameterization function. Controls both the magnitude of parameterized standard deviations and their rate of change with respect to rhos.

1.0

padding_mode

Literal['constant', 'reflect', 'replicate', 'circular']

Type of padding. One of: constant, reflect, replicate, or circular. Defaults to constant.

'constant'

padding_value

float

Fill value for constant padding.

0.0

learn_locs_weights

bool

Whether to learn the weight parameters for the locs estimator. If True, only the weights will be learned, and the bias remains constant, otherwise weights are initialized to zero and only the bias is learned.

True

freeze_std_estimator

bool

Whether to freeze the weight parameters for the std estimator. If True, this estimator will be trained simultaneously with masking and the locs estimator parameters.

True

seed

int | None

Seed for the random number generator used to generate the stochastic transformation. If None, the global RNG state is used.

None
Note

For maximum privacy preservation, Stained Glass Transform Patch Step 2 should be pre-trained from a Stained Glass Transform Patch Step 1.

Methods:

Name Description
__call__

Transform the input data.

__getstate__

Prepare a JSON-serializable copy of the noise layer's state.

__setstate__

Set the state of the object.

forward

Transform the input data.

get_applied_transform_components_factory

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent

get_transformed_output_factory

Create a function that returns the transformed output from the most recent forward pass.

initial_seed

Return the initial seed of the CPU device's random number generator.

manual_seed

Seed each of the random number generators.

reset_parameters

Reinitialize parameters and buffers.

seed

Seed each of the random number generators using a non-deterministic random number.

set_input_scale

Set the power of two that the input is divided by before it is transformed, and the output multiplied by afterwards.

Attributes:

Name Type Description
patch_size tuple[int, int]

The size of the patches to segment the input into.

post_processor_is_final bool

Whether the post-processor is the last step of this noise layer's forward pass.

patch_size property

patch_size: tuple[int, int]

The size of the patches to segment the input into.

post_processor_is_final class-attribute

post_processor_is_final: bool = False

Whether the post-processor is the last step of this noise layer's forward pass.

Set this to True only in a subclass whose forward pass returns the attached post-processor's output with no further transformation. Leave it False in any subclass that transforms the value returned by BaseNoiseLayer.forward, for example by clamping it. NoisyModel.teacher_and_student_forward requires it to read a post-processed noise layer's output with the post-processor skipped.

__call__

__call__(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name Type Description Default

input

Tensor

The input to transform.

required

noise_mask

Tensor | None

An optional mask that selects the elements of input to transform. Where the mask is False, the original input value is returned. Also used to select the elements of the sampled standard deviations to use to mask the input. If None, the entire input is transformed.

None

**kwargs

Any

Additional keyword arguments to the estimator modules.

required

Changed in version v5.1.0: The input is now divided by `input_scale` before it is transformed and the output multiplied by it afterwards. Behavior is unchanged for an input scale of `1`, which is the default.

__getstate__

__getstate__() -> dict[str, Any]

Prepare a JSON-serializable copy of the noise layer's state.

Returns:

Type Description
dict[str, Any]

A dictionary containing the configuration of the noise layer, including its type string, the state dict, and the generator

dict[str, Any]

states if they exist.

Changed in version v3.15.0: Added serialization support for all noise layers.

__setstate__

__setstate__(
    state: dict[str, Any],
    trust_remote_code: bool = False,
    third_party_model_path: str
    | PathLike[str]
    | None = None,
) -> None

Set the state of the object.

state_dict and _generators are both optional keys, and will be restored if they exist in the state.

Parameters:

Name Type Description Default

state

dict[str, Any]

The state to set.

required

trust_remote_code

bool

Whether to trust remote code when loading from HuggingFace Hub.

False

third_party_model_path

str | PathLike[str] | None

The path or huggingface reference to a third-party model to load. This is useful when loading SGTs whose internal structure depends on transformers which are not importable directly through transformers, but are present on the Hugging Face Hub.

None

Changed in version v3.15.0: Added serialization support for all noise layers.

forward

forward(
    input: Tensor,
    noise_mask: Tensor | None = None,
    **kwargs: Any,
) -> torch.Tensor

Transform the input data.

Parameters:

Name Type Description Default

input

Tensor

The input to transform.

required

noise_mask

Tensor | None

An optional mask that selects the elements of input to transform. Where the mask is 0, the original input value is returned. Also used to select the elements of the sampled standard deviations to use to mask the input. If None, the entire input is transformed.

None

**kwargs

Any

Additional keyword arguments to the estimator modules.

required

Returns:

Type Description
torch.Tensor

The transformed input data.

get_applied_transform_components_factory

get_applied_transform_components_factory() -> Callable[
    [], dict[str, torch.Tensor]
]

Create a function that returns the elements of the transform components ('mean' and 'std') applied during the most recent forward pass.

Specifically, the applied elements are those selected by the noise mask (if supplied) and standard deviation mask (if std_estimator.masker is not None). If no masks are used, all elements are returned.

The applied transform components are returned flattened. They are returned at the scale they are applied at: the estimates multiplied by input_scale.

This function is intended to be used to log histograms of the transform components.

Returns:

Type Description
Callable[[], dict[str, torch.Tensor]]

A function that returns the the elements of the transform components applied during the most recent forward pass.

Examples:

>>> from torch import nn
>>> from stainedglass_core import model as sg_model, noise_layer as sg_noise_layer
>>> base_model = nn.Linear(20, 2)
>>> noisy_model = sg_model.NoisyModel(
...     sg_noise_layer.CloakNoiseLayer1,
...     base_model,
...     target_parameter="input",
... )
>>> get_applied_transform_components = (
...     noisy_model.noise_layer.get_applied_transform_components_factory()
... )
>>> input = torch.ones(1, 20)
>>> noise_mask = torch.tensor(5 * [False] + 15 * [True])
>>> output = noisy_model(input, noise_mask=noise_mask)
>>> applied_transform_components = get_applied_transform_components()
>>> applied_transform_components
{'mean': tensor(...), 'std': tensor(...)}
>>> {
...     component_name: component.shape
...     for component_name, component in applied_transform_components.items()
... }
{'mean': torch.Size([15]), 'std': torch.Size([15])}

Changed in version v5.1.0: The transform components are now returned at the scale they are applied at, multiplied by `input_scale`. Behavior is unchanged for an input scale of `1`, which is the default.

get_transformed_output_factory

get_transformed_output_factory() -> Callable[
    [], torch.Tensor
]

Create a function that returns the transformed output from the most recent forward pass.

If super batching is active, only the transformed half of the super batch output is returned. The output is returned at the scale of the noise layer's input, so it is unaffected by input_scale.

Returns:

Type Description
Callable[[], torch.Tensor]

A function that returns the transformed output from the most recent forward pass.

Examples:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1()
>>> get_transformed_output = noise_layer.get_transformed_output_factory()
>>> input = torch.ones(2, 3, 32, 32)
>>> output = noise_layer(input)
>>> transformed_output = get_transformed_output()
>>> assert output.equal(transformed_output)

Changed in version v5.1.0: The transformed output is now returned at the scale of the noise layer's input, multiplied by `input_scale`. Behavior is unchanged for an input scale of `1`, which is the default.

initial_seed

initial_seed() -> int

Return the initial seed of the CPU device's random number generator.

manual_seed

manual_seed(
    seed: int | None, rank_dependent: bool = True
) -> None

Seed each of the random number generators.

Setting seed to None will destroy any existing generators, disabling reproducible behavior until the next call with an integer seed. Calling manual_seed again with an integer after a None call fully recreates generators for every currently available device type (CPU, CUDA, MPS) before applying the seed, making the operation safely reversible.

Parameters:

Name Type Description Default

seed

int | None

The seed to set. Pass None to disable reproducible behavior.

required

rank_dependent

bool

Whether to add the distributed rank to the seed to ensure that each process samples different noise.

True

reset_parameters

reset_parameters() -> None

Reinitialize parameters and buffers.

This method is useful for initializing tensors created on the meta device.

seed

seed() -> None

Seed each of the random number generators using a non-deterministic random number.

set_input_scale

set_input_scale(scale: float) -> None

Set the power of two that the input is divided by before it is transformed, and the output multiplied by afterwards.

With an input scale s, the noise layer returns s * T(input / s), where T is the transformation it would apply with an input scale of 1. Elements the noise mask leaves untransformed are returned exactly as they were input. The estimators, the post-processor, and every loss computed from activations captured inside the noise layer (for example its estimated means and standard deviations, or its output captured by a hook_loss_wrapper hook) see the scaled-down values. Losses computed from activations outside the noise layer, such as a base model's logits, see the noise layer's full-scale output.

The scale must be a power of two from 2**-14 to 2**14. The scale and its reciprocal are then exact in every floating point dtype, including torch.float16, so casting the noise layer to another dtype preserves the scale, and dividing and multiplying by it is exact wherever the result is a normal number.

Parameters:

Name Type Description Default

scale

float

The input scale, a power of two from 2**-14 to 2**14.

required

Examples:

A noise layer whose initialization suits inputs with a root mean square of about 0.01 can transform inputs with a root mean square of about 0.5 at the scale it was calibrated for:

>>> from stainedglass_core import noise_layer as sg_noise_layer
>>> noise_layer = sg_noise_layer.CloakNoiseLayer1(seed=0)
>>> noise_layer.set_input_scale(64.0)
>>> noise_layer.input_scale
tensor(64.)
>>> output = noise_layer(torch.randn(2, 8) * 0.5)

The scale must be a power of two:

>>> noise_layer.set_input_scale(50.0)
Traceback (most recent call last):
...
ValueError: The input scale must be a power of two from 2**-14 to 2**14, but got 50.0.

Added in version v5.1.0.