Simulation

Simulation runner for batch evaluations.

Pure data generation for eye tracking simulation.

pyetsimul.simulation.AngleKappaVariation(alpha_range_deg, beta_range_deg, num_steps)[source]

Angle kappa variation affecting both horizontal (alpha) and vertical (beta) components.

Return type:

ComposedVariation

Parameters:
class pyetsimul.simulation.ComposedVariation(variations, param_name='composed')[source]

Bases: ParameterVariation

Combines multiple parameter variations into a single experiment.

Parameters:
__init__(variations, param_name='composed')[source]

Initialize composed variation.

Parameters:

  • variations (list[ParameterVariation]) – List of parameter variations to combine

  • param_name (str) – Name for the composed parameter

Return type:

None

property description: str

Get a description of the composed variation.

generate_values()[source]

Generate Cartesian product of all variation values using a generator.

Return type:

Iterable[dict[str, Any]]

describe()[source]

Return a human-readable description of the composed variations.

Return type:

str

class pyetsimul.simulation.CorneaRadiusVariation(radius_range_mm, num_steps)[source]

Bases: GenericEyeVariation

Corneal anterior radius variation with proper unit display.

Parameters:
__init__(radius_range_mm, num_steps)[source]

Initialize corneal radius variation.

Parameters:

  • radius_range_mm (list[float]) – Range of anterior radii in mm

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return a human-readable description of the corneal radius variation.

Return type:

str

class pyetsimul.simulation.CorneaThicknessVariation(thickness_range_mm, num_steps)[source]

Bases: GenericEyeVariation

Corneal thickness variation that works with both SphericalCornea and ConicCornea.

Parameters:
__init__(thickness_range_mm, num_steps)[source]

Initialize corneal thickness variation.

Parameters:

  • thickness_range_mm (list[float]) – [min_thickness, max_thickness] in mm

  • num_steps (int) – Number of thickness steps

Return type:

None

describe()[source]

Return a human-readable description of the corneal thickness variation.

Return type:

str

apply_to_eye(eye, value)[source]

Apply thickness value by setting appropriate cornea parameter.

Return type:

None

Parameters:
class pyetsimul.simulation.DataGenerationStrategy(eyes, cameras, lights, experiment_name, gaze_target=None, output_dir='output', save_to_file=True, use_legacy_look_at=False, use_refraction=True, pupil_center_method='ellipse')[source]

Bases: VariationStrategy

Generates eye tracking data across parameter variations.

This class encapsulates a complete experimental setup (eyes + hardware) and can generate datasets by applying different parameter variations to the same setup.

Design Philosophy: - Eyes are part of the experimental setup (biological configuration) - Cameras/lights define the hardware configuration - Variations are the experimental parameters to test - The same setup can be reused to test multiple variations efficiently

Example Usage:

# Create strategy with complete setup
strategy = DataGenerationStrategy(
    eyes=[eye],
    cameras=[camera],
    lights=[light],
    gaze_target=Position3D(0, 0, 200)
)

# Test multiple parameter variations on same setup
pupil_data = strategy.execute(PupilSizeVariation([3, 7], 10))
kappa_data = strategy.execute(AngleKappaVariation([4, 8], [1, 3], 10))
radius_data = strategy.execute(CorneaRadiusVariation([7.5, 8.5], 10))
Parameters:
__init__(eyes, cameras, lights, experiment_name, gaze_target=None, output_dir='output', save_to_file=True, use_legacy_look_at=False, use_refraction=True, pupil_center_method='ellipse')[source]

Initialize data generation strategy with complete experimental setup.

Parameters:

  • eyes (list) – List of Eye objects to use in experiments

  • cameras (list) – List of Camera objects for data capture

  • lights (list) – List of Light objects for corneal reflections

  • gaze_target (Position3D | None) – Fixed target position (None allows variation-specific targets)

  • output_dir (str) – Directory to save generated datasets

  • experiment_name (str) – Base name for experiment files

  • save_to_file (bool) – Whether to save datasets to disk

  • use_legacy_look_at (bool) – Use legacy eye rotation method for compatibility

  • use_refraction (bool) – Enable corneal refraction in image capture

  • pupil_center_method (str) – Method for pupil center calculation (“ellipse” or “center_of_mass”)

Return type:

None

set_experiment_name(experiment_name)[source]

Update the experiment name for subsequent operations.

Parameters:

experiment_name (str) – New experiment name for metadata and file operations

Return type:

None

execute(variation)[source]

Generate eye tracking data using the configured setup and given variation.

Parameters:

variation (ParameterVariation) – Parameter variation to apply across the experimental setup

Return type:

dict[str, Any]

Returns:

Dictionary containing generated dataset with measurements and metadata

generate_single_measurement(eye, camera, param_value, index, gaze_target=None)[source]

Generate measurement data for single camera-eye-parameter combination.

Return type:

dict[str, Any]

Parameters:
apply_parameter_variation(eye_copy, variation, value)[source]

Apply parameter variation to eye copy and return gaze target.

Parameters:

  • eye_copy (Eye) – Eye object to modify

  • variation (ParameterVariation) – Parameter variation to apply

  • value (Any) – Variation value to apply

Return type:

Position3D | None

Returns:

Current gaze target position after applying variation

class pyetsimul.simulation.ExperimentConfig(experiment_name, eyes, cameras, lights, gaze_target=None, output_dir=<factory>)[source]

Bases: object

Generic configuration for any parameter variation experiment.

Parameters:
experiment_name: str
eyes: list[Eye]
cameras: list[Camera]
lights: list[Light]
gaze_target: Position3D | None = None
output_dir: Path
get_gaze_target()[source]

Get the gaze target if specified.

Return type:

Position3D | None

class pyetsimul.simulation.EyeParameterVariation(param_name)[source]

Bases: ParameterVariation

Base class for variations that modify eye objects.

Parameters:

param_name (str)

abstractmethod apply_to_eye(eye, value)[source]

Apply variation value to Eye object.

Return type:

None

Parameters:
class pyetsimul.simulation.EyePositionVariation(center, dx, dy, dz, grid_size)[source]

Bases: EyeParameterVariation

Varies eye position in space using grid generation.

Parameters:
__init__(center, dx, dy, dz, grid_size)[source]

Initialize eye position variation.

Parameters:

  • center (Position3D) – Center position for grid

  • dx (list[float]) – X-axis displacement ranges

  • dy (list[float]) – Y-axis displacement ranges

  • dz (list[float]) – Z-axis displacement ranges

  • grid_size (list[int]) – Number of steps in each dimension

Return type:

None

generate_values()[source]

Generate all eye positions using the grid system.

Return type:

Iterable[Position3D]

describe()[source]

Return a human-readable description of eye position variation.

Return type:

str

apply_to_eye(eye, value)[source]

Set eye position to the specified location.

Return type:

None

Parameters:
class pyetsimul.simulation.GenericEyeVariation(parameter_name, value_range, num_steps, description=None)[source]

Bases: EyeParameterVariation

Generic parameter variation for any eye model parameter.

Supports direct property assignment, method calls, and nested object parameters through string-based parameter paths.

Parameters:
__init__(parameter_name, value_range, num_steps, description=None)[source]

Initialize generic parameter variation.

Parameters:

  • parameter_name (str) – Parameter path (e.g., “fovea_alpha_deg”, “cornea.anterior_radius”)

  • value_range (list[float]) – [min_value, max_value] range

  • num_steps (int) – Number of steps to generate

  • description (str | None) – Optional human-readable description

Return type:

None

describe()[source]

Return human-readable description of the parameter variation.

Return type:

str

generate_values()[source]

Generate parameter values using numpy linspace.

Return type:

Iterable[float]

apply_to_eye(eye, value)[source]

Apply parameter value to eye using parameter path resolution.

Return type:

None

Parameters:
class pyetsimul.simulation.GridGenerator[source]

Bases: ABC

Abstract base for 3D grid generation.

abstractmethod generate_positions()[source]

Generate list of 3D positions.

Return type:

Iterable[Position3D]

class pyetsimul.simulation.ParameterVariation(param_name)[source]

Bases: ABC

Base class for all parameter variations - pure data generation only.

Parameters:

param_name (str)

__init__(param_name)[source]

Initialize parameter variation.

Parameters:

param_name (str) – Name of the parameter to vary

Return type:

None

abstractmethod generate_values()[source]

Generate all values for this parameter variation.

Return type:

Iterable[Any]

abstractmethod describe()[source]

Return a human-readable description of this variation.

Return type:

str

class pyetsimul.simulation.PupilDecentrationVariation(dx_range=None, dy_range=None, dz_range=None, num_steps=10)[source]

Bases: GenericEyeVariation

Pupil decentration variation without changing pupil size.

Uses move_pupil_position to apply offsets in x, y, and/or z directions.

Parameters:
__init__(dx_range=None, dy_range=None, dz_range=None, num_steps=10)[source]

Initialize pupil decentration variation.

Parameters:

  • dx_range (list[float] | None) – [min_dx, max_dx] range for x offset in mm

  • dy_range (list[float] | None) – [min_dy, max_dy] range for y offset in mm

  • dz_range (list[float] | None) – [min_dz, max_dz] range for z offset in mm

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return description of pupil decentration variation.

Return type:

str

apply_to_eye(eye, value)[source]

Apply pupil decentration by moving pupil position.

Return type:

None

Parameters:
class pyetsimul.simulation.PupilSizeVariation(diameter_range, num_steps=10)[source]

Bases: GenericEyeVariation

Pupil diameter variation with proper unit display.

Parameters:
__init__(diameter_range, num_steps=10)[source]

Initialize pupil diameter variation.

Parameters:

  • diameter_range (list[float]) – Range of pupil diameters in mm

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return a human-readable description of the pupil diameter variation.

Return type:

str

class pyetsimul.simulation.PupilSizeWithDecentrationVariation(diameter_range, decentration_config, num_steps=10)[source]

Bases: GenericEyeVariation

Pupil size variation with decentration effects enabled.

Parameters:

  • diameter_range (list[float])

  • decentration_config (PupilDecentrationConfig)

  • num_steps (int)

__init__(diameter_range, decentration_config, num_steps=10)[source]

Initialize pupil size variation with decentration.

Parameters:

  • diameter_range (list[float]) – Range of pupil diameters in mm

  • decentration_config (PupilDecentrationConfig) – PupilDecentrationConfig to apply

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return description of pupil size variation with decentration.

Return type:

str

apply_to_eye(eye, value)[source]

Apply decentration config and set pupil diameter.

Return type:

None

Parameters:
class pyetsimul.simulation.RandomGrid(center, dx, dy, dz, num_points, seed=None)[source]

Bases: GridGenerator

Random 3D positions within bounds.

Parameters:
__init__(center, dx, dy, dz, num_points, seed=None)[source]

Initialize random grid.

Parameters:

  • center (Position3D) – Grid center position

  • dx (list[float]) – [min_offset, max_offset] in x direction

  • dy (list[float]) – [min_offset, max_offset] in y direction

  • dz (list[float]) – [min_offset, max_offset] in z direction

  • num_points (int) – Number of random points to generate

  • seed (int | None) – Random seed for reproducibility

Return type:

None

generate_positions()[source]

Generate random positions.

Return type:

Iterable[Position3D]

class pyetsimul.simulation.RegularGrid(center, dx, dy, dz, grid_size)[source]

Bases: GridGenerator

Regular 3D grid generation with uniform spacing.

Parameters:
__init__(center, dx, dy, dz, grid_size)[source]

Initialize regular grid.

Parameters:

  • center (Position3D) – Grid center position

  • dx (list[float]) – [min_offset, max_offset] in x direction

  • dy (list[float]) – [min_offset, max_offset] in y direction

  • dz (list[float]) – [min_offset, max_offset] in z direction

  • grid_size (list[int]) – [nx, ny, nz] number of points per dimension

Return type:

None

generate_positions()[source]

Generate regular grid positions.

Return type:

Iterable[Position3D]

class pyetsimul.simulation.SequentialVariation(variations, param_name='sequential')[source]

Bases: ParameterVariation

Applies variations sequentially rather than in combination.

Parameters:
__init__(variations, param_name='sequential')[source]

Initialize sequential variation.

Parameters:

  • variations (list[ParameterVariation]) – List of parameter variations to apply sequentially

  • param_name (str) – Name for the sequential parameter

Return type:

None

describe()[source]

Return a human-readable description of the sequential variations.

Return type:

str

generate_values()[source]

Generate sequential values from all variations.

Return type:

Iterable[dict[str, Any]]

class pyetsimul.simulation.TargetPositionVariation(grid_center, dx, dy, dz, grid_size)[source]

Bases: TargetVariation

Varies gaze target positions in space using grid generation.

Parameters:
__init__(grid_center, dx, dy, dz, grid_size)[source]

Initialize target position variation.

Parameters:

  • grid_center (Position3D) – Center position for grid

  • dx (list[float]) – X-axis displacement ranges

  • dy (list[float]) – Y-axis displacement ranges

  • dz (list[float]) – Z-axis displacement ranges

  • grid_size (list[int]) – Number of steps in each dimension

Return type:

None

describe()[source]

Return human-readable description of target position variation.

Return type:

str

generate_values()[source]

Generate all target positions using the grid system.

Return type:

Iterable[Position3D]

class pyetsimul.simulation.TargetVariation(param_name)[source]

Bases: ParameterVariation

Base class for variations that provide gaze targets.

Parameters:

param_name (str)

get_targets()[source]

Get all target values for this variation.

Return type:

list[Any]

class pyetsimul.simulation.VariationStrategy[source]

Bases: ABC

Base strategy for using parameter variations.

abstractmethod execute(variation)[source]

Execute strategy over all variation values.

Return type:

Any

Parameters:

variation (ParameterVariation)

pyetsimul.simulation.create_experiment_config(experiment_name, eyes, cameras, lights, gaze_target=None, output_dir='outputs')[source]

Create experiment configuration with validation.

Return type:

ExperimentConfig

Parameters:
pyetsimul.simulation.validate_config(config)[source]

Validate experiment configuration.

Return type:

None

Parameters:

config (ExperimentConfig)

Core

Core parameter variation architecture for pure data generation.

class pyetsimul.simulation.core.ParameterVariation(param_name)[source]

Bases: ABC

Base class for all parameter variations - pure data generation only.

Parameters:

param_name (str)

__init__(param_name)[source]

Initialize parameter variation.

Parameters:

param_name (str) – Name of the parameter to vary

Return type:

None

abstractmethod generate_values()[source]

Generate all values for this parameter variation.

Return type:

Iterable[Any]

abstractmethod describe()[source]

Return a human-readable description of this variation.

Return type:

str

class pyetsimul.simulation.core.EyeParameterVariation(param_name)[source]

Bases: ParameterVariation

Base class for variations that modify eye objects.

Parameters:

param_name (str)

abstractmethod apply_to_eye(eye, value)[source]

Apply variation value to Eye object.

Return type:

None

Parameters:
class pyetsimul.simulation.core.TargetVariation(param_name)[source]

Bases: ParameterVariation

Base class for variations that provide gaze targets.

Parameters:

param_name (str)

get_targets()[source]

Get all target values for this variation.

Return type:

list[Any]

class pyetsimul.simulation.core.VariationStrategy[source]

Bases: ABC

Base strategy for using parameter variations.

abstractmethod execute(variation)[source]

Execute strategy over all variation values.

Return type:

Any

Parameters:

variation (ParameterVariation)

Config

Generic configuration system for parameter variation experiments.

class pyetsimul.simulation.config.ExperimentConfig(experiment_name, eyes, cameras, lights, gaze_target=None, output_dir=<factory>)[source]

Bases: object

Generic configuration for any parameter variation experiment.

Parameters:
experiment_name: str
eyes: list[Eye]
cameras: list[Camera]
lights: list[Light]
gaze_target: Position3D | None = None
output_dir: Path
get_gaze_target()[source]

Get the gaze target if specified.

Return type:

Position3D | None

pyetsimul.simulation.config.create_experiment_config(experiment_name, eyes, cameras, lights, gaze_target=None, output_dir='outputs')[source]

Create experiment configuration with validation.

Return type:

ExperimentConfig

Parameters:
pyetsimul.simulation.config.validate_config(config)[source]

Validate experiment configuration.

Return type:

None

Parameters:

config (ExperimentConfig)

Data Generation

Data generation strategy for parameter variations.

class pyetsimul.simulation.data_generation.DataGenerationStrategy(eyes, cameras, lights, experiment_name, gaze_target=None, output_dir='output', save_to_file=True, use_legacy_look_at=False, use_refraction=True, pupil_center_method='ellipse')[source]

Bases: VariationStrategy

Generates eye tracking data across parameter variations.

This class encapsulates a complete experimental setup (eyes + hardware) and can generate datasets by applying different parameter variations to the same setup.

Design Philosophy: - Eyes are part of the experimental setup (biological configuration) - Cameras/lights define the hardware configuration - Variations are the experimental parameters to test - The same setup can be reused to test multiple variations efficiently

Example Usage:

# Create strategy with complete setup
strategy = DataGenerationStrategy(
    eyes=[eye],
    cameras=[camera],
    lights=[light],
    gaze_target=Position3D(0, 0, 200)
)

# Test multiple parameter variations on same setup
pupil_data = strategy.execute(PupilSizeVariation([3, 7], 10))
kappa_data = strategy.execute(AngleKappaVariation([4, 8], [1, 3], 10))
radius_data = strategy.execute(CorneaRadiusVariation([7.5, 8.5], 10))
Parameters:
__init__(eyes, cameras, lights, experiment_name, gaze_target=None, output_dir='output', save_to_file=True, use_legacy_look_at=False, use_refraction=True, pupil_center_method='ellipse')[source]

Initialize data generation strategy with complete experimental setup.

Parameters:

  • eyes (list) – List of Eye objects to use in experiments

  • cameras (list) – List of Camera objects for data capture

  • lights (list) – List of Light objects for corneal reflections

  • gaze_target (Position3D | None) – Fixed target position (None allows variation-specific targets)

  • output_dir (str) – Directory to save generated datasets

  • experiment_name (str) – Base name for experiment files

  • save_to_file (bool) – Whether to save datasets to disk

  • use_legacy_look_at (bool) – Use legacy eye rotation method for compatibility

  • use_refraction (bool) – Enable corneal refraction in image capture

  • pupil_center_method (str) – Method for pupil center calculation (“ellipse” or “center_of_mass”)

Return type:

None

set_experiment_name(experiment_name)[source]

Update the experiment name for subsequent operations.

Parameters:

experiment_name (str) – New experiment name for metadata and file operations

Return type:

None

execute(variation)[source]

Generate eye tracking data using the configured setup and given variation.

Parameters:

variation (ParameterVariation) – Parameter variation to apply across the experimental setup

Return type:

dict[str, Any]

Returns:

Dictionary containing generated dataset with measurements and metadata

generate_single_measurement(eye, camera, param_value, index, gaze_target=None)[source]

Generate measurement data for single camera-eye-parameter combination.

Return type:

dict[str, Any]

Parameters:
apply_parameter_variation(eye_copy, variation, value)[source]

Apply parameter variation to eye copy and return gaze target.

Parameters:

  • eye_copy (Eye) – Eye object to modify

  • variation (ParameterVariation) – Parameter variation to apply

  • value (Any) – Variation value to apply

Return type:

Position3D | None

Returns:

Current gaze target position after applying variation

Data Loading

Data loading utilities for cached experiment datasets.

pyetsimul.simulation.data_loading.load_experiment_data(experiment_name, output_dir='outputs')[source]

Load cached experiment dataset by name.

Parameters:

  • experiment_name (str) – Original experiment name (will be auto-sanitized for file lookup)

  • output_dir (str | Path) – Directory containing the cached data files

Return type:

dict[str, Any]

Returns:

Dictionary containing the cached dataset

Raises:

FileNotFoundError – If no cached dataset exists for this experiment name

Variations

Generic parameter variation for any eye model parameter.

class pyetsimul.simulation.generic.GenericEyeVariation(parameter_name, value_range, num_steps, description=None)[source]

Bases: EyeParameterVariation

Generic parameter variation for any eye model parameter.

Supports direct property assignment, method calls, and nested object parameters through string-based parameter paths.

Parameters:
__init__(parameter_name, value_range, num_steps, description=None)[source]

Initialize generic parameter variation.

Parameters:

  • parameter_name (str) – Parameter path (e.g., “fovea_alpha_deg”, “cornea.anterior_radius”)

  • value_range (list[float]) – [min_value, max_value] range

  • num_steps (int) – Number of steps to generate

  • description (str | None) – Optional human-readable description

Return type:

None

describe()[source]

Return human-readable description of the parameter variation.

Return type:

str

generate_values()[source]

Generate parameter values using numpy linspace.

Return type:

Iterable[float]

apply_to_eye(eye, value)[source]

Apply parameter value to eye using parameter path resolution.

Return type:

None

Parameters:

Anatomical parameter variations for eye tracking simulation.

class pyetsimul.simulation.anatomy.PupilSizeVariation(diameter_range, num_steps=10)[source]

Bases: GenericEyeVariation

Pupil diameter variation with proper unit display.

Parameters:
__init__(diameter_range, num_steps=10)[source]

Initialize pupil diameter variation.

Parameters:

  • diameter_range (list[float]) – Range of pupil diameters in mm

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return a human-readable description of the pupil diameter variation.

Return type:

str

class pyetsimul.simulation.anatomy.AngleKappaAlphaVariation(alpha_range_deg, num_steps)[source]

Bases: GenericEyeVariation

Angle kappa alpha (horizontal) variation with proper unit display.

Parameters:
__init__(alpha_range_deg, num_steps)[source]

Initialize angle kappa alpha variation.

Parameters:

  • alpha_range_deg (list[float]) – Range of alpha angles in degrees

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return a human-readable description of the angle kappa alpha variation.

Return type:

str

class pyetsimul.simulation.anatomy.AngleKappaBetaVariation(beta_range_deg, num_steps)[source]

Bases: GenericEyeVariation

Angle kappa beta (vertical) variation with proper unit display.

Parameters:
__init__(beta_range_deg, num_steps)[source]

Initialize angle kappa beta variation.

Parameters:

  • beta_range_deg (list[float]) – Range of beta angles in degrees

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return a human-readable description of the angle kappa beta variation.

Return type:

str

pyetsimul.simulation.anatomy.AngleKappaVariation(alpha_range_deg, beta_range_deg, num_steps)[source]

Angle kappa variation affecting both horizontal (alpha) and vertical (beta) components.

Return type:

ComposedVariation

Parameters:
class pyetsimul.simulation.anatomy.CorneaRadiusVariation(radius_range_mm, num_steps)[source]

Bases: GenericEyeVariation

Corneal anterior radius variation with proper unit display.

Parameters:
__init__(radius_range_mm, num_steps)[source]

Initialize corneal radius variation.

Parameters:

  • radius_range_mm (list[float]) – Range of anterior radii in mm

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return a human-readable description of the corneal radius variation.

Return type:

str

class pyetsimul.simulation.anatomy.CorneaThicknessVariation(thickness_range_mm, num_steps)[source]

Bases: GenericEyeVariation

Corneal thickness variation that works with both SphericalCornea and ConicCornea.

Parameters:
__init__(thickness_range_mm, num_steps)[source]

Initialize corneal thickness variation.

Parameters:

  • thickness_range_mm (list[float]) – [min_thickness, max_thickness] in mm

  • num_steps (int) – Number of thickness steps

Return type:

None

describe()[source]

Return a human-readable description of the corneal thickness variation.

Return type:

str

apply_to_eye(eye, value)[source]

Apply thickness value by setting appropriate cornea parameter.

Return type:

None

Parameters:
class pyetsimul.simulation.anatomy.PupilSizeWithDecentrationVariation(diameter_range, decentration_config, num_steps=10)[source]

Bases: GenericEyeVariation

Pupil size variation with decentration effects enabled.

Parameters:

  • diameter_range (list[float])

  • decentration_config (PupilDecentrationConfig)

  • num_steps (int)

__init__(diameter_range, decentration_config, num_steps=10)[source]

Initialize pupil size variation with decentration.

Parameters:

  • diameter_range (list[float]) – Range of pupil diameters in mm

  • decentration_config (PupilDecentrationConfig) – PupilDecentrationConfig to apply

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return description of pupil size variation with decentration.

Return type:

str

apply_to_eye(eye, value)[source]

Apply decentration config and set pupil diameter.

Return type:

None

Parameters:
class pyetsimul.simulation.anatomy.PupilDecentrationVariation(dx_range=None, dy_range=None, dz_range=None, num_steps=10)[source]

Bases: GenericEyeVariation

Pupil decentration variation without changing pupil size.

Uses move_pupil_position to apply offsets in x, y, and/or z directions.

Parameters:
__init__(dx_range=None, dy_range=None, dz_range=None, num_steps=10)[source]

Initialize pupil decentration variation.

Parameters:

  • dx_range (list[float] | None) – [min_dx, max_dx] range for x offset in mm

  • dy_range (list[float] | None) – [min_dy, max_dy] range for y offset in mm

  • dz_range (list[float] | None) – [min_dz, max_dz] range for z offset in mm

  • num_steps (int) – Number of steps in variation

Return type:

None

describe()[source]

Return description of pupil decentration variation.

Return type:

str

apply_to_eye(eye, value)[source]

Apply pupil decentration by moving pupil position.

Return type:

None

Parameters:

Eye 3D position variations.

class pyetsimul.simulation.eye_position.EyePositionVariation(center, dx, dy, dz, grid_size)[source]

Bases: EyeParameterVariation

Varies eye position in space using grid generation.

Parameters:
__init__(center, dx, dy, dz, grid_size)[source]

Initialize eye position variation.

Parameters:

  • center (Position3D) – Center position for grid

  • dx (list[float]) – X-axis displacement ranges

  • dy (list[float]) – Y-axis displacement ranges

  • dz (list[float]) – Z-axis displacement ranges

  • grid_size (list[int]) – Number of steps in each dimension

Return type:

None

generate_values()[source]

Generate all eye positions using the grid system.

Return type:

Iterable[Position3D]

describe()[source]

Return a human-readable description of eye position variation.

Return type:

str

apply_to_eye(eye, value)[source]

Set eye position to the specified location.

Return type:

None

Parameters:

Target 3D position variations.

class pyetsimul.simulation.target_position.TargetPositionVariation(grid_center, dx, dy, dz, grid_size)[source]

Bases: TargetVariation

Varies gaze target positions in space using grid generation.

Parameters:
__init__(grid_center, dx, dy, dz, grid_size)[source]

Initialize target position variation.

Parameters:

  • grid_center (Position3D) – Center position for grid

  • dx (list[float]) – X-axis displacement ranges

  • dy (list[float]) – Y-axis displacement ranges

  • dz (list[float]) – Z-axis displacement ranges

  • grid_size (list[int]) – Number of steps in each dimension

Return type:

None

describe()[source]

Return human-readable description of target position variation.

Return type:

str

generate_values()[source]

Generate all target positions using the grid system.

Return type:

Iterable[Position3D]

Base grid generation system for spatial parameter variations.

class pyetsimul.simulation.grid_base.GridGenerator[source]

Bases: ABC

Abstract base for 3D grid generation.

abstractmethod generate_positions()[source]

Generate list of 3D positions.

Return type:

Iterable[Position3D]

class pyetsimul.simulation.grid_base.RegularGrid(center, dx, dy, dz, grid_size)[source]

Bases: GridGenerator

Regular 3D grid generation with uniform spacing.

Parameters:
__init__(center, dx, dy, dz, grid_size)[source]

Initialize regular grid.

Parameters:

  • center (Position3D) – Grid center position

  • dx (list[float]) – [min_offset, max_offset] in x direction

  • dy (list[float]) – [min_offset, max_offset] in y direction

  • dz (list[float]) – [min_offset, max_offset] in z direction

  • grid_size (list[int]) – [nx, ny, nz] number of points per dimension

Return type:

None

generate_positions()[source]

Generate regular grid positions.

Return type:

Iterable[Position3D]

class pyetsimul.simulation.grid_base.RandomGrid(center, dx, dy, dz, num_points, seed=None)[source]

Bases: GridGenerator

Random 3D positions within bounds.

Parameters:
__init__(center, dx, dy, dz, num_points, seed=None)[source]

Initialize random grid.

Parameters:

  • center (Position3D) – Grid center position

  • dx (list[float]) – [min_offset, max_offset] in x direction

  • dy (list[float]) – [min_offset, max_offset] in y direction

  • dz (list[float]) – [min_offset, max_offset] in z direction

  • num_points (int) – Number of random points to generate

  • seed (int | None) – Random seed for reproducibility

Return type:

None

generate_positions()[source]

Generate random positions.

Return type:

Iterable[Position3D]

Composed parameter variations for complex experiment designs.

class pyetsimul.simulation.composed_variation.ComposedVariation(variations, param_name='composed')[source]

Bases: ParameterVariation

Combines multiple parameter variations into a single experiment.

Parameters:
__init__(variations, param_name='composed')[source]

Initialize composed variation.

Parameters:

  • variations (list[ParameterVariation]) – List of parameter variations to combine

  • param_name (str) – Name for the composed parameter

Return type:

None

property description: str

Get a description of the composed variation.

generate_values()[source]

Generate Cartesian product of all variation values using a generator.

Return type:

Iterable[dict[str, Any]]

describe()[source]

Return a human-readable description of the composed variations.

Return type:

str

class pyetsimul.simulation.composed_variation.SequentialVariation(variations, param_name='sequential')[source]

Bases: ParameterVariation

Applies variations sequentially rather than in combination.

Parameters:
__init__(variations, param_name='sequential')[source]

Initialize sequential variation.

Parameters:

  • variations (list[ParameterVariation]) – List of parameter variations to apply sequentially

  • param_name (str) – Name for the sequential parameter

Return type:

None

describe()[source]

Return a human-readable description of the sequential variations.

Return type:

str

generate_values()[source]

Generate sequential values from all variations.

Return type:

Iterable[dict[str, Any]]