struct

Chem::Spatial::Parallelepiped

Inherits Struct / Value / Object

A parallelepiped is a three-dimensional figure formed by six parallelograms. It is defined by three vectors (basis) and it's useful for representing spatial bounds and unit cells.

It is internally represented by a 3x3 matrix, where each column correspond to a basis vector (see Mat3.basis), where coordinates are expressed in Cartesian space (angstroms). In this way, the basis matrix can be used to transform from Cartesian to fractional coordinates, and viceversa, by matrix multiplication (see #cart and #fract).

Constructors

[](a : Number, b : Number, c : Number) : self

Creates a Parallelepiped with the given lengths placed at the origin.

cubic(a : Number) : self

Creates a cubic parallelepiped (a = b = c and α = β = γ = 90°).

from_io(io : IO, format : IO::ByteFormat) : self

Reads a parallelepiped from io in the given format. See also: IO#read_bytes.

hexagonal(a : Number, c : Number) : self

Creates a hexagonal parallelepiped (a = b, α = β = 90°, and γ = 120°).

monoclinic(a : Number, c : Number, beta : Number) : self

Creates a monoclinic parallelepiped (a ≠ c, α = γ = 90°, and β ≠ 90°).

new(i : Vec3, j : Vec3, k : Vec3, origin : Vec3 = Vec3.zero) : self

Creates a Parallelepiped with the given basis vectors located at origin.

new(basis : Mat3, origin : Vec3 = Vec3.zero)

Creates a Parallelepiped with basis located at origin.

new(vmin : Vec3, vmax : Vec3) : self

Creates a Parallelepiped spanning from vmin to vmax.

new(size : NumberTriple | Size3, angles : NumberTriple = {90, 90, 90}, origin : Vec3 = Vec3.zero) : self

Creates a Parallelepiped with the given lengths (in angstroms) and angles (in degrees) located at origin. Raises ArgumentError if any of the lengths or angles is negative.

NOTE: The first basis vector will be aligned to the X axis and the second basis vector will lie in the XY plane.

orthorhombic(a : Number, b : Number, c : Number) : self

Creates an orthorhombic parallelepiped (a ≠ b ≠ c and α = β = γ = 90°).

rhombohedral(a : Number, alpha : Number) : self

Creates an rhombohedral parallelepiped (a = b = c and α = β = γ ≠ 90°).

tetragonal(a : Number, c : Number) : self

Creates an tetragonal parallelepiped (a = b ≠ c and α = β = γ = 90°).

Instance methods

*(value : Number) : self

Returns a parallelepiped with the basis vectors multiplied by value.

==(rhs : self) : Bool

angles

Returns the parallelepiped angles (alpha, beta, gamma) in degrees.

basis

Matrix containing the basis vectors.

basisvec

Returns the basis vectors.

cart(vec : Vec3) : Vec3

Returns the vector in Cartesian coordinates equivalent to the given fractional coordinates.

center

Returns the center of the parallelepiped.

center_at(vec : Vec3) : self

Centers the parallelepiped at vec.

center_at_origin

Centers the parallelepiped at the origin.

close_to?(rhs : self, delta : Number = Float64::EPSILON) : Bool

Returns true if the values of the parallelepipeds are within delta from each other, else false.

cubic?

Returns true if the parallelepiped is cubic (a = b = c and α = β = γ = 90°), else false.

each_edge

Yields each parallelepiped' edge as a pair of vertices.

each_vertex

Yields parallelepiped' vertices.

Parallelepiped[5, 10, 20].each_vertex { |vec| puts vec }

Prints:

Vec3[0.0, 0.0, 0.0]
Vec3[0.0, 0.0, 20.0]
Vec3[0.0, 10.0, 0.0]
Vec3[0.0, 10.0, 20.0]
Vec3[5.0, 0.0, 0.0]
Vec3[5.0, 0.0, 20.0]
Vec3[5.0, 10.0, 0.0]
Vec3[5.0, 10.0, 20.0]

edges

Returns the parallelepiped' edges as pairs of vertices.

fract(vec : Vec3) : Vec3

Returns the vector in fractional coordinates equivalent to the given Cartesian coordinates.

hexagonal?

Returns true if the parallelepiped is hexagonal (a = b, α = β = 90°, and γ = 120°), else false.

image(vec : Vec3, ix : Tuple(Int, Int, Int)) : Vec3

Returns the vector's image with respect to the parallelepiped.

pld = new Parallelepiped.new({2, 2, 3}, {90, 90, 120})
pld.i # =&gt; Vec3[2.0, 0.0, 0.0]
pld.j # =&gt; Vec3[-1, 1.732, 0.0]
pld.k # =&gt; Vec3[0.0, 0.0, 3.0]

vec = Vec3[1, 1, 1.5]
pld.image(vec, {1, 0, 0}) # =&gt; Vec3[3.0, 1.0, 1.5]
pld.image(vec, {0, 1, 0}) # =&gt; Vec3[0.0, 2.732, 1.5]
pld.image(vec, {0, 0, 1}) # =&gt; Vec3[1.0, 1.0, 4.5]
pld.image(vec, {1, 0, 1}) # =&gt; Vec3[3.0, 1.0, 4.5]
pld.image(vec, {1, 1, 1}) # =&gt; Vec3[2.0, 2.732, 4.5]

includes?(other : self) : Bool

Returns true if the parallelepiped encloses other, false otherwise.

It effectively checks if every vertex of other is contained by the parallelepiped.

pld = Parallelepiped.new({10, 10, 10}, {90, 90, 120})
pld.includes? Parallelepiped[5, 4, 6]                        # =&gt; true
pld.includes? Parallelepiped.new(Vec3[-1, 2, -4], {5, 4, 6}) # =&gt; false

includes?(vec : Vec3) : Bool

Returns true if the parallelepiped encloses vec, false otherwise.

pld = Parallelepiped.new({23.803, 23.828, 5.387}, {90, 90, 120})
pld.includes? Vec3[10, 20, 2]  # =&gt; true
pld.includes? Vec3[0, 0, 0]    # =&gt; true
pld.includes? Vec3[30, 30, 10] # =&gt; false
pld.includes? Vec3[-3, 10, 2]  # =&gt; true
pld.includes? Vec3[-3, 2, 2]   # =&gt; false

inspect(io : IO) : Nil

Appends this struct's name and instance variables names and values to the given IO.

struct Point
  def initialize(@x : Int32, @y : Int32)
  end
end

p1 = Point.new 1, 2
p1.to_s    # &quot;Point(@x=1, @y=2)&quot;
p1.inspect # &quot;Point(@x=1, @y=2)&quot;

monoclinic?

Returns true if the parallelepiped is monoclinic (a ≠ c, α = γ = 90°, and β ≠ 90°), else false.

origin

Origin of the parallelepiped.

orthogonal?

Returns true if the parallelepiped is orthogonal (α = β = γ = 90°), else false.

orthorhombic?

Returns true if the parallelepiped is orthorhombic (a ≠ b ≠ c and α = β = γ = 90°), else false.

pad(px : Number, py : Number, pz : Number, centered : Bool = true) : self

Returns a new parallelepiped by expanding the extents by padding in each direction. padding can be either a single value, three values, or a Size3 instance.

If centered is true, the origin will be changed such that the center does not change, else it will be kept intact.

pld = Parallelepiped.new(Vec3[1, 5, 3], {10, 5, 12})

other = pld.pad(2.5)
other.size                 # =&gt; Size3[15, 10, 17]
other.origin == pld.origin # =&gt; false
other.center == pld.center # =&gt; true

other = pld.pad(2.5, centered: false)
other.size                 # =&gt; Size3[15, 10, 17]
other.origin == pld.origin # =&gt; true
other.center == pld.center # =&gt; false

NOTE: Note that its size is actually increased by padding * 2.

pad(padding : Number, centered : Bool = true) : self

Returns a new parallelepiped by expanding the extents by padding in each direction. padding can be either a single value, three values, or a Size3 instance.

If centered is true, the origin will be changed such that the center does not change, else it will be kept intact.

pld = Parallelepiped.new(Vec3[1, 5, 3], {10, 5, 12})

other = pld.pad(2.5)
other.size                 # =&gt; Size3[15, 10, 17]
other.origin == pld.origin # =&gt; false
other.center == pld.center # =&gt; true

other = pld.pad(2.5, centered: false)
other.size                 # =&gt; Size3[15, 10, 17]
other.origin == pld.origin # =&gt; true
other.center == pld.center # =&gt; false

NOTE: Note that its size is actually increased by padding * 2.

pad(padding : Size3, centered : Bool = true) : self

Returns a new parallelepiped by expanding the extents by padding in each direction. padding can be either a single value, three values, or a Size3 instance.

If centered is true, the origin will be changed such that the center does not change, else it will be kept intact.

pld = Parallelepiped.new(Vec3[1, 5, 3], {10, 5, 12})

other = pld.pad(2.5)
other.size                 # =&gt; Size3[15, 10, 17]
other.origin == pld.origin # =&gt; false
other.center == pld.center # =&gt; true

other = pld.pad(2.5, centered: false)
other.size                 # =&gt; Size3[15, 10, 17]
other.origin == pld.origin # =&gt; true
other.center == pld.center # =&gt; false

NOTE: Note that its size is actually increased by padding * 2.

resize(si : Number | Nil, sj : Number | Nil, sk : Number | Nil) : self

Returns a parallelepiped by resizing the basis vectors to the given values.

pld = Parallelepiped.hexagonal(1, 2)
pld.angles # =&gt; {90, 90, 120}
pld.size   # =&gt; Size3[1, 1, 2]

other = pld.resize(5, 5, 12)
other.angles # =&gt; {90, 90, 120}
other.size   # =&gt; Size3[5, 5, 12]

Use nil to keep the current size:

other = pld.resize(nil, 5, nil)
other.angles # =&gt; {90, 90, 120}
other.size   # =&gt; Size3[1, 5, 12]

resize(size : Chem::Spatial::Size3) : self

Returns a parallelepiped by resizing the basis vectors to the given size.

pld = Parallelepiped.hexagonal(1, 2)
pld.angles # =&gt; {90, 90, 120}
pld.size   # =&gt; Size3[1, 1, 2]

other = pld.resize(Size3[5, 5, 12])
other.angles # =&gt; {90, 90, 120}
other.size   # =&gt; Size3[5, 5, 12]

resize

Yields the basis vectors' sizes to the given block, and returns a parallelepiped by resizing them to the returned values.

pld = Parallelepiped.hexagonal(1, 2)
pld.angles # =&gt; {90, 90, 120}
pld.size   # =&gt; Size3[1, 1, 2]

other = pld.resize { |a, b, c| {a * 2, b / 10, c} }
other.angles # =&gt; {90, 90, 120}
other.size   # =&gt; Size3[2, 0.1, 2]

resize_by(a : Number, b : Number, c : Number) : self

Returns a parallelepiped by padding the basis vectors by the given values.

pld = Parallelepiped.hexagonal(1, 2)
pld.angles # =&gt; {90, 90, 120}
pld.size   # =&gt; Size3[1, 1, 2]

other = pld.resize_by(2, 3, -0.5)
other.angles # =&gt; {90, 90, 120}
other.size   # =&gt; Size3[3, 4, 1.5]

rhombohedral?

Returns true if the parallelepiped is rhombohedral (a = b = c and α = β = γ ≠ 90°), else false.

rotate(x : Number, y : Number, z : Number) : self

Returns the parallelepiped rotated by the given Euler angles in degrees. Delegates to Quat.rotation for computing the rotation.

rotate(about rotaxis : Vec3, by angle : Number) : self

Returns the parallelepiped rotated about the axis vector rotaxis by angle degrees. Delegates to Quat.rotation for computing the rotation.

rotate(quat : Quat) : self

Returns the parallelepiped rotated by the given quaternion.

size

Returns the lengths of the basis vectors.

tetragonal?

Returns true if the parallelepiped is tetragonal (a = b ≠ c and α = β = γ = 90°), else false.

to_io(io : IO, format : IO::ByteFormat = :system_endian) : Nil

Writes the binary representation of the parallelepiped to io in the given format. See also IO#write_bytes.

transform(transformation : Transform) : self

Returns the parallelepiped resulting of applying the given transformation.

NOTE: the rotation will be applied about the center of the parallelepiped. Translation will be applied afterwards.

transform

Returns a new parallelepiped with the return value of the given block, which is invoked with the basis vectors.

pld = Parallelepiped.cubic(10).transform do |bi, bj, bk|
  bi *= 2
  bk /= 0.4
  {bi, bj, bk}
end
pld.basisvec[0] # =&gt; Vec3[20, 0, 0]
pld.basisvec[1] # =&gt; Vec3[0, 10, 0]
pld.basisvec[2] # =&gt; Vec3[0, 0, 25]

translate(offset : Vec3) : self

Returns a new parallelepiped translated by offset.

pld = Parallelepiped.new(Vec3[-5, 1, 20], {10, 10, 10}, {90, 90, 120})
pld.translate Vec3[1, 2, 10]
pld.origin # =&gt; Vec3[-4.0, 3.0, 30.0]

triclinic?

Returns true if the parallelepiped is triclinic (not orthogonal, hexagonal, monoclinic, nor rhombohedral), else false.

vertices

Returns parallelepiped' vertices.

pld = Parallelepiped[5, 10, 20]
pld.vertices # =&gt; [Vec3[0.0, 0.0, 0.0], Vec3[0.0, 0.0, 20.0], ...]

vmax

Returns the maximum vertex.

pld = Parallelepiped.new(Vec3[1.5, 3, -0.4], {10, 10, 12}, {90, 90, 120})
pld.vmax # =&gt; Vec3[6.5, 11.66, 11.6]

vmin

Returns the minimum vertex. This is equivalent to the parallelepiped's origin.

pld = Parallelepiped.new(Vec3[1.5, 3, -0.4], {10, 10, 12}, {90, 90, 120})
pld.vmin # =&gt; Vec3[1.5, 3, -0.4]

volume

Returns the volume of the parallelepiped.

wrap(vec : Vec3, around center : Vec3) : Vec3

Returns the vector by wrapping it into the parallelepiped centered at center. The vector is assumed to be expressed in Cartesian coordinates.

wrap(vec : Vec3) : Vec3

Returns the vector by wrapping it into the parallelepiped. The vector is assumed to be expressed in Cartesian coordinates.

xyz?

Whether the parallelepiped is aligned to the X, Y, and Z axes.