Coordinate System Module

class CoordinateSystem(nx: int, ny: int, x_min: float, x_max: float, y_min: float, y_max: float, endpoint: bool = True)

Bases: object

A 2D Cartesian coordinate system for fiber optics simulations.

This class represents a structured 2D grid with customizable boundaries and resolution. It provides utilities for mesh generation, coordinate transformations, and grid manipulations commonly needed in optical fiber modeling.

Parameters:

• nx (int) – Number of grid points along the x-axis. Must be >= 2.

• ny (int) – Number of grid points along the y-axis. Must be >= 2.

• x_min (float) – Minimum x-coordinate of the computational domain.

• x_max (float) – Maximum x-coordinate of the computational domain. Must be > x_min.

• y_min (float) – Minimum y-coordinate of the computational domain.

• y_max (float) – Maximum y-coordinate of the computational domain. Must be > y_min.

• endpoint (bool, optional) – Whether to include the boundary points in the grid. Default is True.

Examples

Create a square coordinate system centered at origin:

>>> coords = CoordinateSystem(
...     nx=101, ny=101,
...     x_min=-5e-6, x_max=5e-6,
...     y_min=-5e-6, y_max=5e-6
... )
>>> coords.shape
(101, 101)
>>> coords.dx
1e-07

Create an asymmetric domain:

>>> coords = CoordinateSystem.from_bounds_and_resolution(
...     x_bounds=(-10e-6, 10e-6),
...     y_bounds=(-5e-6, 15e-6),
...     resolution=0.1e-6
... )

The CoordinateSystem class manages the coordinate grid for rendering and evaluating the mesh construction. It includes methods for centering, padding, and scaling boundaries, enabling flexible and precise geometry visualization.

nx: int

ny: int

x_min: float

x_max: float

y_min: float

y_max: float

endpoint: bool = True

classmethod validate_grid_points(value: int) → int

Validate that grid points are reasonable.

classmethod validate_x_bounds(x_max: float, info) → float

Validate x boundaries are properly ordered.

classmethod validate_y_bounds(y_max: float, info) → float

Validate y boundaries are properly ordered.

classmethod from_bounds_and_resolution(x_bounds: Tuple[float, float], y_bounds: Tuple[float, float], resolution: float, endpoint: bool = True) → CoordinateSystem

Create coordinate system from bounds and desired resolution.

Parameters:

• x_bounds (tuple of float) – X-axis boundaries as (x_min, x_max).

• y_bounds (tuple of float) – Y-axis boundaries as (y_min, y_max).

• resolution (float) – Desired grid spacing in both directions.

• endpoint (bool, optional) – Whether to include boundary points. Default is True.

Returns:

New coordinate system instance.

Return type:

CoordinateSystem

Examples

>>> coords = CoordinateSystem.from_bounds_and_resolution(
...     x_bounds=(-5e-6, 5e-6),
...     y_bounds=(-5e-6, 5e-6),
...     resolution=0.1e-6
... )

classmethod square_domain(size: float, resolution: float, center: Tuple[float, float] = (0.0, 0.0), endpoint: bool = True) → CoordinateSystem

Create a square computational domain.

Parameters:

• size (float) – Side length of the square domain.

• resolution (float) – Grid spacing.

• center (tuple of float, optional) – Center coordinates (x, y). Default is (0, 0).

• endpoint (bool, optional) – Whether to include boundary points. Default is True.

Returns:

New coordinate system instance.

Return type:

CoordinateSystem

Examples

>>> coords = CoordinateSystem.square_domain(
...     size=20e-6,
...     resolution=0.1e-6,
...     center=(2e-6, -1e-6)
... )

property shape: Tuple[int, int]

Grid shape following NumPy convention (rows, columns).

Returns:

Shape as (ny, nx).

Return type:

tuple of int

property x_bounds: Tuple[float, float]

X-axis boundaries.

Returns:

Boundaries as (x_min, x_max).

Return type:

tuple of float

property y_bounds: Tuple[float, float]

Y-axis boundaries.

Returns:

Boundaries as (y_min, y_max).

Return type:

tuple of float

property dx: float

Grid spacing along x-axis.

Returns:

Spacing between adjacent x grid points.

Return type:

float

property dy: float

Grid spacing along y-axis.

Returns:

Spacing between adjacent y grid points.

Return type:

float

property area: float

Total area of the computational domain.

Returns:

Domain area.

Return type:

float

property aspect_ratio: float

Aspect ratio of the domain (width/height).

Returns:

Aspect ratio.

Return type:

float

property x_vector: ndarray

1D array of x-coordinates.

Returns:

Array of x-coordinates with shape (nx,).

Return type:

ndarray

property y_vector: ndarray

1D array of y-coordinates.

Returns:

Array of y-coordinates with shape (ny,).

Return type:

ndarray

property x_mesh: ndarray

2D meshgrid of x-coordinates.

Returns:

2D array of x-coordinates with shape (ny, nx).

Return type:

ndarray

property y_mesh: ndarray

2D meshgrid of y-coordinates.

Returns:

2D array of y-coordinates with shape (ny, nx).

Return type:

ndarray

get_coordinates_flattened() → ndarray

Get flattened coordinate pairs for unstructured operations.

Returns:

Array of coordinate pairs with shape (nx*ny, 2). Each row contains [x, y] coordinates.

Return type:

ndarray

Examples

>>> coords = CoordinateSystem(nx=3, ny=2, x_min=0, x_max=2, y_min=0, y_max=1)
>>> pairs = coords.get_coordinates_flattened()
>>> pairs.shape
(6, 2)

find_nearest_indices(x: float, y: float) → Tuple[int, int]

Find grid indices closest to given coordinates.

Parameters:

• x (float) – Target x-coordinate.

• y (float) – Target y-coordinate.

Returns:

Grid indices (i, j) where i is y-index and j is x-index.

Return type:

tuple of int

Raises:

ValueError – If coordinates are outside the domain.

Examples

>>> coords = CoordinateSystem.square_domain(size=10e-6, resolution=1e-6)
>>> i, j = coords.find_nearest_indices(1e-6, 2e-6)

get_value_at_indices(array: ndarray, i: int, j: int) → float

Safely extract value from array at given indices.

Parameters:

• array (ndarray) – 2D array with shape matching the grid.

• i (int) – Y-index (row).

• j (int) – X-index (column).

Returns:

Value at the specified indices.

Return type:

float

Raises:

ValueError – If indices are out of bounds or array shape doesn’t match grid.

interpolate_at_point(array: ndarray, x: float, y: float) → float

Bilinear interpolation of array values at given coordinates.

Parameters:

• array (ndarray) – 2D array with values at grid points.

• x (float) – X-coordinate for interpolation.

• y (float) – Y-coordinate for interpolation.

Returns:

Interpolated value.

Return type:

float

Raises:

ValueError – If coordinates are outside domain or array shape doesn’t match.

ensure_odd_resolution(axis: str | None = None) → CoordinateSystem

Ensure grid has odd number of points for symmetric operations.

Parameters:

axis (str or None, optional) – Axis to modify (‘x’, ‘y’, or None for both). Default is None.

Returns:

New coordinate system with odd resolution.

Return type:

CoordinateSystem

Examples

>>> coords = CoordinateSystem(nx=100, ny=50, x_min=-5, x_max=5, y_min=-2, y_max=2)
>>> odd_coords = coords.ensure_odd_resolution()
>>> odd_coords.nx, odd_coords.ny
(101, 51)

center_on_origin(preserve_size: bool = True) → CoordinateSystem

Create coordinate system centered on the origin (immutable).

Parameters:

preserve_size (bool, optional) – If True, preserve the original domain size. If False, make symmetric around origin using the maximum absolute boundary. Default is True.

Returns:

New centered coordinate system.

Return type:

CoordinateSystem

Examples

>>> coords = CoordinateSystem(nx=100, ny=100, x_min=-2, x_max=8, y_min=1, y_max=6)
>>> centered = coords.center_on_origin(preserve_size=True)
>>> centered.x_bounds
(-5.0, 5.0)
>>> centered.y_bounds
(-2.5, 2.5)

scale(factor: float) → CoordinateSystem

Create scaled coordinate system.

Parameters:

factor (float) – Scaling factor. Must be > 0.

Returns:

New scaled coordinate system.

Return type:

CoordinateSystem

Raises:

ValueError – If factor <= 0.

translate(dx: float, dy: float) → CoordinateSystem

Create translated coordinate system.

Parameters:

• dx (float) – Translation along x-axis.

• dy (float) – Translation along y-axis.

Returns:

New translated coordinate system.

Return type:

CoordinateSystem

refine(factor: int) → CoordinateSystem

Create refined coordinate system with higher resolution.

Parameters:

factor (int) – Refinement factor. Must be >= 1.

Returns:

New coordinate system with factor times more grid points.

Return type:

CoordinateSystem

Raises:

ValueError – If factor < 1.

get_subdomain(x_range: Tuple[float, float], y_range: Tuple[float, float]) → CoordinateSystem

Extract a subdomain from the current coordinate system.

Parameters:

• x_range (tuple of float) – X-axis range as (x_min, x_max).

• y_range (tuple of float) – Y-axis range as (y_min, y_max).

Returns:

New coordinate system covering the specified subdomain.

Return type:

CoordinateSystem

Raises:

ValueError – If the specified ranges are outside the current domain.

is_uniform(rtol: float = 1e-10) → bool

Check if the grid has uniform spacing.

Parameters:

rtol (float, optional) – Relative tolerance for comparison. Default is 1e-10.

Returns:

True if grid spacing is uniform in both directions.

Return type:

bool

summary() → str

Get a formatted summary of the coordinate system.

Returns:

Multi-line string summary with key properties.

Return type:

str

add_padding(padding_factor: float) → None

Add padding space around the coordinate boundaries (mutable).

Parameters:

padding_factor (float) – Factor by which to pad the boundaries. Must be greater than 1.0.

Raises:

ValueError – If the padding factor is not greater than 1.0.

with_padding(padding_factor: float) → CoordinateSystem

Create coordinate system with added padding (immutable version).

This is the preferred method for new code.

Parameters:

padding_factor (float) – Factor by which to expand the domain. Must be > 1.0.

Returns:

New coordinate system with expanded boundaries.

Return type:

CoordinateSystem

set_right() → None

Set the coordinate system boundaries to align the grid to the left.

set_left() → None

Set the coordinate system boundaries to align the grid to the right.

set_top() → None

Set the coordinate system boundaries to align the grid to the top.

set_bottom() → None

Set the coordinate system boundaries to align the grid to the bottom.

y_centering(zero_included: bool = False) → None

Center the y-axis coordinate system around zero.

Parameters:

zero_included (bool, optional) – If True, adjusts grid points to include zero. Default is True.

x_centering(zero_included: bool = False) → None

Center the x-axis coordinate system around zero.

Parameters:

zero_included (bool, optional) – If True, adjusts grid points to include zero. Default is True.

center(factor: float = 1.0, zero_included: bool = False) → None

Center the coordinate system by scaling the boundaries.

Parameters:

• factor (float, optional) – Scaling factor for the boundaries. Must be greater than 0. Default is 1.2.

• zero_included (bool, optional) – If True, adjust grid points to include zero. Default is True.

Raises:

ValueError – If the scaling factor is not positive.

update(**kwargs) → None

Update the coordinate system attributes and recompute parameters.

Parameters:

**kwargs (dict) – Attribute-value pairs to update in the coordinate system.

Raises:

ValueError – If an invalid attribute is passed.

ensure_odd(attribute: str) → None

Ensure the specified grid attribute (nx or ny) is odd.

Parameters:

attribute (str) – The attribute to update (‘nx’ or ‘ny’).

Raises:

ValueError – If the attribute is not ‘nx’ or ‘ny’.