Physics-aware arrays

A core building block of the underlying features of treams are physics-aware arrays. In most of their properties they behave similar to numpy arrays and one can easily change the type and mix them

>>> np.array([1, 2]) * treams.PhysicsArray([2, 3])
PhysicsArray(
    [2, 6],
)
>>> np.array([1, 2]) @ treams.PhysicsArray([2, 3])
8

but they have mainly two features added. First, they derive from treams.util.AnnotatedArray so they can carry annotations with them, but these annotations are restricted to the physical quantities (as described in Basis sets and other core parameters). Second, they offer special methods to create matrices for common transformations like rotations, which are described in more detail in Operators.

Special properties

>>> treams.PhysicsArray([[0, 1], [2, 3]], k0=(1, 2))
PhysicsArray(
    [[0, 1],
     [2, 3]],
    k0=(1.0, 2.0),
)

In this example you can notice that the values for the vacuum wave number k0 were converted from integers to floats. Thus, trying to use tream.PhysicsArray([1], k0=1j) will raise an error, because the complex number cannot be interpreted as a float. Additional special keywords are basis, kpar, lattice, material, modetype, and poltype. These properties can also be accessed by setting the corresponding attribute

>>> m = treams.PhysicsArray([1, 2])
>>> m.material = 4
>>> m
PhysicsArray(
    [1, 2],
    material=Material(4, 1, 0),
)

where we now have a material with the relative permittivity 4. As with its parent class these properties are also compared and merged when using operations on these objects

>>> treams.PhysicsArray([0, 1], k0=1) + treams.PhysicsArray([2, 3], material=2)
PhysicsArray(
    [2, 4],
    k0=1.0,
    material=Material(2, 1, 0),
)

and using conflicting values will raise a warning, for example treams.PhysicsArray([0, 1], k0=1) + treams.PhysicsArray([2, 3], k0=2) emits treams/util.py:249: AnnotationWarning: at index 0: overwriting key 'k0'. The special properties have also a unique behavior when appearing in matrix multiplications. If one of the two matrices has the special property not set, it becomes “transparent” to it. Check out the difference between

>>> np.ones((2, 2)) @ treams.PhysicsArray([1, 2], k0=1.0)
PhysicsArray(
    [3., 3.],
    k0=1.0,
)

and

>>> np.ones((2, 2)) @ treams.util.AnnotatedArray([1, 2], k0=(1.0,))
AnnotatedArray(
    [3., 3.],
    AnnotationSequence(AnnotationDict({})),
)

where besides the obvious difference in array types, the property k0 is preserved.

The full list of special properties is:

Name	Description
basis	Basis set: spherical, cylindrical, planar
k0	Vacuum wave number
kpar	Phase relation in lattices (treams.WaveVector)
lattice	Definition of a lattice (treams.Lattice)
modetype	Modetype, depends on wave (Mode types)
material	Embedding material (treams.Material)
poltype	Polarization types (Polarizations)