mcdc.Surface

class mcdc.Surface(type_, name, boundary_condition)

Geometric surface primitive with optional boundary condition and motion.

Surfaces are registered non-singletons and receive a stable ID. Factory constructors (PlaneX(), CylinderZ(), etc.) set the quadric coefficients (A..J) and linearity flag. Motion segments can be defined with move().

Parameters:

  • type_ (int) – One of SURFACE_* constants (e.g., SURFACE_PLANE_X).

  • name (str) – Optional label for reporting.

  • boundary_condition (str) – Boundary behavior at the surface ("none", "vacuum", or "reflective").

ID

Index in the global registry (assigned on construction).

Type:

int

type\_

Surface type code (SURFACE_*).

Type:

int

name

User label.

Type:

str

boundary_condition

One of BC_NONE, BC_VACUUM, BC_REFLECTIVE.

Type:

int

A,B,C,D,E,F,G,H,I,J

Quadric coefficients defining the implicit surface.

Type:

float

linear

True for linear (plane) surfaces.

Type:

bool

quadric

True for quadric (e.g.,cylinder) surfaces.

Type:

bool

quartic

True for quartic (e.g., torus) surfaces.

Type:

bool

nx, ny, nz

Outward normal components for linear planes.

Type:

float

moving

True if move() has been called.

Type:

bool

N_move

Number of motion segments plus the final static segment.

Type:

int

move_velocities

Per-segment velocity vectors.

Type:

(N_move, 3) ndarray

move_durations

Per-segment durations (s).

Type:

(N_move,) ndarray

move_time_grid

Cumulative time breakpoints.

Type:

(N_move+1,) ndarray

move_translations

Cumulative translations at each breakpoint.

Type:

(N_move+1, 3) ndarray

See also

Region

Use unary + / - to form half-spaces: +surface or -surface.

decode_type

Human-readable surface type.

decode_BC_type

Human-readable boundary condition name.

classmethod ConeX(name: str = '', apex: Sequence[float] = [0.0, 0.0, 0.0], t_sq: float = 1.0, boundary_condition: str = 'none')

Create an infinite cone with axis along the x-axis.

Equation: (y - y0)^2 + (z - z0)^2 - t_sq * (x - x0)^2 = 0

Parameters:

  • name (str, optional) –

  • apex ((3,) array_like of float) – Cone apex (x0, y0, z0) in cm.

  • t_sq (float) – Squared tangent of the half-angle: t_sq = tan^2(theta). For a 45-degree half-angle use t_sq = 1.0.

  • boundary_condition ({"none","vacuum","reflective"}, optional) –

Returns:

Cone-X surface.

Return type:

Surface

classmethod ConeY(name: str = '', apex: Sequence[float] = [0.0, 0.0, 0.0], t_sq: float = 1.0, boundary_condition: str = 'none')

Create an infinite cone with axis along the y-axis.

Equation: (x - x0)^2 + (z - z0)^2 - t_sq * (y - y0)^2 = 0

Parameters:

  • name (str, optional) –

  • apex ((3,) array_like of float) – Cone apex (x0, y0, z0) in cm.

  • t_sq (float) – Squared tangent of the half-angle: t_sq = tan^2(theta).

  • boundary_condition ({"none","vacuum","reflective"}, optional) –

Returns:

Cone-Y surface.

Return type:

Surface

classmethod ConeZ(name: str = '', apex: Sequence[float] = [0.0, 0.0, 0.0], t_sq: float = 1.0, boundary_condition: str = 'none')

Create an infinite cone with axis along the z-axis.

Equation: (x - x0)^2 + (y - y0)^2 - t_sq * (z - z0)^2 = 0

Parameters:

  • name (str, optional) –

  • apex ((3,) array_like of float) – Cone apex (x0, y0, z0) in cm.

  • t_sq (float) – Squared tangent of the half-angle: t_sq = tan^2(theta).

  • boundary_condition ({"none","vacuum","reflective"}, optional) –

Returns:

Cone surface.

Return type:

Surface

classmethod Cylinder(name: str = '', radius: float = 0.0, axis: Sequence[float] = [0.0, 0.0, 1.0], point: Sequence[float] = [0.0, 0.0, 0.0], boundary_condition: str = 'none')

Create a general infinite cylinder with an arbitrary axis.

Parameters:

  • name (str, optional) –

  • radius (float) – Cylinder radius (cm).

  • axis ((3,) array_like of float) – Direction vector of the cylinder axis (normalized automatically).

  • point ((3,) array_like of float) – A point on the cylinder axis (cm).

  • boundary_condition ({"none","vacuum","reflective"}, optional) –

Returns:

General cylinder surface.

Return type:

Surface

classmethod CylinderX(name: str = '', center: Sequence[float] = [0.0, 0.0], radius: float = 0.0, boundary_condition: str = 'none')

Create an infinite cylinder aligned with the x-axis.

Parameters:

  • name (str, optional) – User label.

  • center ((2,) array_like of float, default (0, 0)) – Cylinder center in (y, z) (cm).

  • radius (float, default 1.0) – Cylinder radius (cm).

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

Quadratic cylinder surface.

Return type:

Surface

classmethod CylinderY(name: str = '', center: Sequence[float] = [0.0, 0.0], radius: float = 0.0, boundary_condition: str = 'none')

Create an infinite cylinder aligned with the y-axis.

Parameters:

  • name (str, optional) – User label.

  • center ((2,) array_like of float) – Cylinder center in (x, z) (cm).

  • radius (float) – Cylinder radius (cm).

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

Quadratic cylinder surface.

Return type:

Surface

classmethod CylinderZ(name: str = '', center: Sequence[float] = [0.0, 0.0], radius: float = 0.0, boundary_condition: str = 'none')

Create an infinite cylinder aligned with the z-axis.

Parameters:

  • name (str, optional) – User label.

  • center ((2,) array_like of float) – Cylinder center in (x, y) (cm).

  • radius (float) – Cylinder radius (cm).

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

Quadratic cylinder surface.

Return type:

Surface

classmethod Plane(name: str = '', A: float = 0.0, B: float = 0.0, C: float = 0.0, D: float = 0.0, boundary_condition: str = 'none')

Create a general plane defined by A x + B y + C z + D = 0.

The normal is normalized to unit length and stored in (nx, ny, nz).

Parameters:

  • name (str, optional) – User label.

  • A (float) – Plane coefficients.

  • B (float) – Plane coefficients.

  • C (float) – Plane coefficients.

  • D (float) – Plane coefficients.

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

Linear plane with normalized normal vector.

Return type:

Surface

classmethod PlaneX(name: str = '', x: float = 0.0, boundary_condition: str = 'none')

Create a plane perpendicular to +x at x = constant.

Parameters:

  • name (str, optional) – User label.

  • x (float, default 0.0) – Plane location (cm).

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

Linear plane with normal (+1, 0, 0).

Return type:

Surface

classmethod PlaneY(name: str = '', y: float = 0.0, boundary_condition: str = 'none')

Create a plane perpendicular to +y at y = constant.

Parameters:

  • name (str, optional) – User label.

  • y (float, default 0.0) – Plane location (cm).

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

Linear plane with normal (0, +1, 0).

Return type:

Surface

classmethod PlaneZ(name: str = '', z: float = 0.0, boundary_condition: str = 'none')

Create a plane perpendicular to +z at z = constant.

Parameters:

  • name (str, optional) – User label.

  • z (float, default 0.0) – Plane location (cm).

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

Linear plane with normal (0, 0, +1).

Return type:

Surface

classmethod Quadric(name: str = '', A: float = 0.0, B: float = 0.0, C: float = 0.0, D: float = 0.0, E: float = 0.0, F: float = 0.0, G: float = 0.0, H: float = 0.0, I: float = 0.0, J: float = 0.0, boundary_condition: str = 'none')
Create a general quadric:

A x^2 + B y^2 + C z^2 + D xy + E yz + F zx + G x + H y + I z + J = 0

Parameters:

  • name (str, optional) – User label.

  • A (float) – Quadric coefficients.

  • B (float) – Quadric coefficients.

  • C (float) – Quadric coefficients.

  • D (float) – Quadric coefficients.

  • E (float) – Quadric coefficients.

  • F (float) – Quadric coefficients.

  • G (float) – Quadric coefficients.

  • H (float) – Quadric coefficients.

  • I (float) – Quadric coefficients.

  • J (float) – Quadric coefficients.

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

General quadratic surface.

Return type:

Surface

classmethod Sphere(name: str = '', center: Sequence[float] = [0.0, 0.0, 0.0], radius: float = 0.0, boundary_condition: str = 'none')

Create a sphere.

Parameters:

  • name (str, optional) – User label.

  • center ((3,) array_like of float) – Sphere center (x, y, z) in cm.

  • radius (float) – Radius (cm).

  • boundary_condition (str, optional) – Boundary type ("none", "vacuum", or "reflective").

Returns:

Quadratic spherical surface.

Return type:

Surface

classmethod Torus(name: str = '', center: Sequence[float] = [0.0, 0.0, 0.0], axis: Sequence[float] = [0.0, 0.0, 1.0], R: float = 0.0, r: float = 0.0, boundary_condition: str = 'none')

Create a general torus with an arbitrary axis.

Parameters:

  • name (str, optional) –

  • center ((3,) array_like of float) – Torus center (cm).

  • axis ((3,) array_like of float) – Direction vector of the torus axis (normalized automatically).

  • R (float) – Major radius.

  • r (float) – Minor radius of the tube.

  • boundary_condition ({"none","vacuum","reflective"}, optional) –

Returns:

General torus surface.

Return type:

Surface

classmethod TorusX(name: str = '', A: float = 0.0, B: float = 0.0, C: float = 0.0, R: float = 0.0, r: float = 0.0, boundary_condition: str = 'none')
Create a torus on the y-z plane radially symmetric around the x axis:

f(x, y, z) = ( sqrt[(y - B)^2 + (z - C)^2] - R )^2 + (x - A)^2 - r^2

Parameters:

  • name (str, optional) –

  • A (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the x-axis) r is the radius of the circle that is being revolved

  • B (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the x-axis) r is the radius of the circle that is being revolved

  • C (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the x-axis) r is the radius of the circle that is being revolved

  • R (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the x-axis) r is the radius of the circle that is being revolved

  • r (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the x-axis) r is the radius of the circle that is being revolved

  • boundary_condition ({"none","vacuum","reflective"}, optional) –

Returns:

Torus surface.

Return type:

Surface

classmethod TorusY(name: str = '', A: float = 0.0, B: float = 0.0, C: float = 0.0, R: float = 0.0, r: float = 0.0, boundary_condition: str = 'none')
Create a torus on the x-z plane radially symmetric around the y axis:

f(x, y, z) = ( sqrt[(x - A)^2 + (z - C)^2] - R )^2 + (y - B)^2 - r^2

Parameters:

  • name (str, optional) –

  • A (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the y-axis) r is the radius of the circle that is being revolved

  • B (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the y-axis) r is the radius of the circle that is being revolved

  • C (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the y-axis) r is the radius of the circle that is being revolved

  • R (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the y-axis) r is the radius of the circle that is being revolved

  • r (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the y-axis) r is the radius of the circle that is being revolved

  • boundary_condition ({"none","vacuum","reflective"}, optional) –

Returns:

Torus surface.

Return type:

Surface

classmethod TorusZ(name: str = '', A: float = 0.0, B: float = 0.0, C: float = 0.0, R: float = 0.0, r: float = 0.0, boundary_condition: str = 'none')
Create a torus on the x-y plane radially symmetric around the z axis:

f(x, y, z) = ( sqrt[(x - A)^2 + (y - B)^2] - R )^2 + (z - C)^2 - r^2

Parameters:

  • name (str, optional) –

  • A (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the z-axis) r is the radius of the circle that is being revolved

  • B (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the z-axis) r is the radius of the circle that is being revolved

  • C (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the z-axis) r is the radius of the circle that is being revolved

  • R (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the z-axis) r is the radius of the circle that is being revolved

  • r (float) – A, B, C are displacement values for the torus in the x, y, z directions respectively R is the radius around which a circle is revolved about the axis of revolution (parallel with the z-axis) r is the radius of the circle that is being revolved

  • boundary_condition ({"none","vacuum","reflective"}, optional) –

Returns:

Torus surface.

Return type:

Surface

move(velocities, durations)

Define piecewise-constant motion for the surface.

Appends a final static segment (zero velocity, infinite duration) so that the motion covers the whole simulation time.

Parameters:

  • velocities (array_like, shape (N, 3) or list) – Per-segment velocity vectors [cm/s].

  • durations (array_like, shape (N,) or list) – Per-segment durations [s].

Notes

  • Internally converts lists to arrays and constructs move_time_grid and cumulative move_translations.

  • Sets moving=True and N_move = len(durations) + 1.

Examples

>>> s = Surface.PlaneZ(z=0.0)
>>> s.move(velocities=[[0,0,1.0]], durations=[0.5])  # 0.5 s upward, then static
>>> s.N_move
2