QPMS
/
qpms
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Some little docstrings. 

Former-commit-id: 762774a600ca9a02fecba86e6cb6e6992a1d1b05
This commit is contained in:
Marek Nečada 2020-04-03 21:31:33 +03:00
parent 70d03f75aa
commit e774b30d0c
3 changed files with 284 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
qpms/cymaterials.pyx
View File

@ -19,7 +19,24 @@ class EpsMuGeneratorType(enum.Enum):
PYTHON_CALLABLE = 4
cdef class EpsMu:
"""Permittivity and permeability of an isotropic material.
This wraps the C structure qpms_epsmu_t.
See Also
--------
EpsMuGenerator : generates EpsMu objects as a function of frequency.
"""
def __init__(self, *args ,**kwargs):
"""EpsMu object constructor
Parameters
----------
eps : complex
Relative electric permittivity.
mu : complex
Relative magnetic permeability.
"""
self.em.eps = 1
self.em.mu = 1
if(len(args)>=1):
@ -36,15 +53,38 @@ cdef class EpsMu:
return 'EpsMu(' + repr(self.em.eps) + ', ' + repr(self.em.mu) + ')'
def k(self, omega):
"""Wavenumber of the material at frequency omega
Parameters
----------
omega : complex
Angular frequency in 1/s.
Returns
-------
out : complex
Wavenumber of the material at omega assuming permittivity and permeability
from self.
"""
return self.n * omega / c
property n:
"""Refractive index of a material specified by this permittivity and permeability."""
def __get__(self):
return (self.em.eps * self.em.mu)**.5
property Z:
"""Wave impedance of a material specified by this permittivity and permeability."""
def __get__(self):
return (self.em.mu / self.em.eps)**.5
cdef class LorentzDrudeModel:
"""Lorentz-Drude model of material permittivity.
This wraps the C structure qpms_ldparams_t.
Some materials are available in the `lorentz_drude` dictionary.
"""
def __cinit__(self, eps_inf, omega_p, f_arr, omega_arr, gamma_arr):
cdef size_t n = len(omega_arr)
if (n != len(gamma_arr) or n != len(f_arr)):
@ -66,9 +106,26 @@ cdef class LorentzDrudeModel:
self.params = NULL
def __call__(self, omega):
"""Evaluates the permittivity at a given frequency
Parameters
----------
omega : complex
Angular frequency in 1/s.
Returns
-------
eps : complex
Relative permittivity from the Lorentz-Drude model
"""
return qpms_lorentzdrude_eps(omega, self.params)
cdef class _CLorentzDrudeModel:
"""Lorentz-Drude model of material permittivity.
This is an auxilliary class making the pre-compiled C Lorentz-Drude models accessible.
For defining own Lorentz-Drude models from python, use LorentzDrudeModel class instead.
"""
def __cinit__(self):
"Do not use directly. Do not use from Python. Use the link() method instead."
pass
@ -80,6 +137,18 @@ cdef class _CLorentzDrudeModel:
return self
def __call__(self, omega):
"""Evaluates the permittivity at a given frequency
Parameters
----------
omega : complex
Angular frequency in 1/s.
Returns
-------
eps : complex
Relative permittivity from the Lorentz-Drude model
"""
return qpms_lorentzdrude_eps(omega, self.params)
cdef double eh = eV/hbar

69
qpms/cytmatrices.pyx
View File

@ -274,6 +274,20 @@ cdef class TMatrixGenerator:
raise TypeError("Can't construct TMatrixGenerator from that")
def __call__(self, arg, cdouble omega):
"""Produces a T-matrix at a given frequency.
Parameters
----------
arg : CTMatrix or BaseSpec
If arg is a CTMatrix, its contents will be replaced.
If arg is a BaseSpec, a new CTMatrix instance will be created.
omega : complex
Angular frequency at which the T-matrix shall be evaluated.
Returns
-------
t : CTMatrix
"""
cdef CTMatrix tm
if isinstance(arg, CTMatrix): # fill the matrix
tm = arg
@ -300,15 +314,70 @@ cdef class TMatrixGenerator:
# Better "constructors":
@staticmethod
def sphere(outside, inside, r):
"""Creates a T-matrix generator for a spherical scatterer.
This method uses analytical Mie-Lorentz formulae.
Parameters:
-----------
outside : EpsMuGenerator or EpsMu
Optical properties of the surrounding medium.
inside : EpsMuGenerator or EpsMu
Optical properties of the material inside the sphere.
r : double
Sphere radius
"""
return TMatrixGenerator(__MieParams(EpsMuGenerator(outside),
EpsMuGenerator(inside), r))
@staticmethod
def sphere_asarc(outside, inside, r, *args, **kwargs):
"""Creates a T-matrix generator for a spherical scatterer.
This method uses numerical evaluation for generic axially-symmetric
scatterer, and is intended for testing and benchmarking only.
For regular use, see TMatrigGenerator.sphere() instead.
Parameters
----------
outside : EpsMuGenerator or EpsMu
Optical properties of the surrounding medium.
inside : EpsMuGenerator or EpsMu
Optical properties of the material inside the sphere.
r : double
Sphere radius
Returns
-------
tmgen : TMatrixGenerator
See Also
--------
TMatrigGenerator.sphere : Faster and more precise method.
"""
return TMatrixGenerator(__AxialSymParams(
EpsMuGenerator(outside), EpsMuGenerator(inside),
ArcFunction(__ArcSphere(r)), *args, **kwargs))
@staticmethod
def cylinder(outside, inside, r, h, *args, **kwargs):
"""Creates a T-matrix generator for a right circular cylinder.
Parameters:
-----------
outside : EpsMuGenerator or EpsMu
Optical properties of the surrounding medium.
inside : EpsMuGenerator or EpsMu
Optical properties of the material inside the cylinder.
r : double
Cylinder base radius.
h : double
Cylinder height.
Returns
-------
tmgen : TMatrixGenerator
"""
return TMatrixGenerator(__AxialSymParams(
EpsMuGenerator(outside), EpsMuGenerator(inside),
ArcFunction(__ArcCylinder(r, h)), *args, **kwargs))

145
qpms/qpms_c.pyx
View File

@ -271,6 +271,20 @@ cdef class Particle:
def __cinit__(Particle self, pos, t, bspec = None):
"""Particle object constructor.
Parameters
----------
pos : (x, y, z)
Particle position in cartesian coordinates
t : TMatrixGenerator or CTMatrix or TMatrixInterpolator
T-matrix specification for the particle.
bspec : BaseSpec
WSWF basis specification for the particle. Might be omitted if
t is a CTMatrix.
"""
cdef TMatrixGenerator tgen
cdef BaseSpec spec
if(len(pos)>=2 and len(pos) < 4):
@ -347,7 +361,11 @@ cpdef void scatsystem_set_nthreads(long n):
cdef class ScatteringSystem:
'''
Wrapper over the C qpms_scatsys_t structure.
Wrapper over the C qpms_scatsys_t structure, representing a collection
of scatterers, finite or periodic.
Currently, it does not have a standard constructor. Use the
ScatteringSystem.create() method instead.
'''
cdef list tmgobjs # here we keep the references to occuring TMatrixFunctions (and hence BaseSpecs and TMatrixGenerators)
#cdef list Tmatrices # Here we keep the references to occuring T-matrices
@ -372,6 +390,45 @@ cdef class ScatteringSystem:
@staticmethod # We don't have any "standard" constructor for this right now
def create(particles, medium, cdouble omega, FinitePointGroup sym = FinitePointGroup.TRIVIAL(),
latticebasis = None): # TODO tolerances
"""(Non-standard) constructor of ScatteringSystem
Parameters
----------
particles : list of Particles objects
Scatterers to be included in the system. These scatterers are then
copied around by the constructor using the point group symmetry defined in sym.
medium : EpsMu or EpsMuGenerator
Material properties of the background medium.
omega : complex
Any valid angular frequency for the initial T-matrix evaluation.
It must be a value which all the T-matrix generators and interpolators
referenced by particles can evaluate.
sym : FinitePointGroup
Symmetry group for a finite system.
Defaults to the trivial point group FinitePointGroup.TRIVIAL().
Currently, this must be left trivial for periodic systems.
latticebasis : None or array_like of float type.
Lattice base vectors of a periodic system in cartesian coordinates.
The shape must be [d][3], where d = 1, 2 or 3 determines the lattice dimension.
Defaults to None, i.e. a finite system.
Returns
-------
ss : ScatteringSystem
Object representing the system of compact scatterers.
ssw : _ScatteringSystemAtOmega
Object representing ss evaluated at omega (angular frequency used for the
initial evaluation).
Note
----
Currently, the ScatterinSystem's T-matrices need to be evaluated for at least
one frequency in order to initialise the symmetry structure. For this reason,
this "constructor" creates an instance of ScatteringSystem and an instance
of _ScatteringSystemAtOmega at the same time, so that the evaluated T-matrices
can be used right away if needed. This is why this approach is used instead
of the usual __init__ method.
"""
if latticebasis is not None and sym.order != 1:
raise NotImplementedError("Periodic systems don't currently support nontrivial point group symmetries")
@ -477,10 +534,12 @@ cdef class ScatteringSystem:
return r
property fecv_size:
"""Length of the full excitation coefficient vector"""
def __get__(self):
self.check_s()
return self.s[0].fecv_size
property saecv_sizes:
"""Lengths of the partial symmetry-adapted excitation coefficient vectors"""
def __get__(self):
self.check_s()
return [self.s[0].saecv_sizes[i]
@ -492,6 +551,7 @@ cdef class ScatteringSystem:
if (self.s[0].sym[0].irreps[iri].name) else None
for iri in range(self.s[0].sym[0].nirreps)]
property nirreps:
"""Number of irreducible representations of the scattering system point symmetry group"""
def __get__(self):
self.check_s()
return self.s[0].sym[0].nirreps
@ -508,6 +568,26 @@ cdef class ScatteringSystem:
return None
def pack_vector(self, vect, iri):
"""Converts (projects) a full excitation coefficient vector into an irrep subspace.
Parameters
----------
vect : array_like of shape (self.fecv_size,)
The full excitation coefficient vector to be converted.
iri : int
Index of the irreducible representation.
Returns
-------
packed : ndarray of shape (self.saecv_sizes[iri],)
"irrep-packed" excitation vector: the part of vect belonging to the
irrep indexed by iri, in terms of given irrep's internal coordinates.
See Also
--------
unpack_vector : The beckward (not exactly inverse) operation.
pack_matrix : Corresponding conversion for matrices.
"""
self.check_s()
if len(vect) != self.fecv_size:
raise ValueError("Length of a full vector has to be %d, not %d"
@ -519,7 +599,28 @@ cdef class ScatteringSystem:
cdef cdouble[::1] target_view = target_np
qpms_scatsys_irrep_pack_vector(&target_view[0], &vect_view[0], self.s, iri)
return target_np
def unpack_vector(self, packed, iri):
"""Unpacks an "irrep-packed" excitation coefficient vector to full coordinates.
Parameters
----------
packed : array_like of shape (self.saecv_sizes[iri],)
Excitation coefficient vector part belonging to the irreducible representation
indexed by iri, in terms of given irrep's internal coordinates.
iri : int
Index of the irreducible representation.
Returns
-------
vect : ndarray of shape (self.fecv_size,)
The contribution to a full excitation coefficient vector from iri'th irrep.
See Also
--------
pack_vector : The inverse operation.
unpack_matrix : Corresponding conversion for matrices.
"""
self.check_s()
if len(packed) != self.saecv_sizes[iri]:
raise ValueError("Length of %d. irrep-packed vector has to be %d, not %d"
@ -532,7 +633,28 @@ cdef class ScatteringSystem:
qpms_scatsys_irrep_unpack_vector(&target_view[0], &packed_view[0],
self.s, iri, 0)
return target_np
def pack_matrix(self, fullmatrix, iri):
"""Converts (projects) a matrix into an irrep subspace.
Parameters
----------
fullmatrix : array_like of shape (self.fecv_size, self.fecv_size)
The full matrix (operating on the exctitation coefficient vectors) to be converted.
iri : int
Index of the irreducible representation.
Returns
-------
packedmatrix : ndarray of shape (self.saecv_sizes[iri], self.saecv_sizes[iri])
"irrep-packed" matrix: the part of fullmatrix belonging to the
irrep indexed by iri, in terms of given irrep's internal coordinates.
See Also
--------
unpack_matrix : The beckward (not exactly inverse) operation.
pack_vector : Corresponding conversion for excitation coefficient vectors.
"""
self.check_s()
cdef size_t flen = self.s[0].fecv_size
cdef size_t rlen = self.saecv_sizes[iri]
@ -548,6 +670,27 @@ cdef class ScatteringSystem:
self.s, iri)
return target_np
def unpack_matrix(self, packedmatrix, iri):
"""Unpacks an "irrep-packed" excitation coefficient vector to full coordinates.
Parameters
----------
packedmatrix : array_like of shape (self.saecv_sizes[iri], self.saecv_sizes[iri])
A matrix (operating on the excitation coefficient vectors) part belonging to the
irreducible representation indexed by iri, in terms of given irrep's internal
coordinates.
iri : int
Index of the irreducible representation.
Returns
-------
fullmatrix : ndarray of shape (self.fecv_size, self.fecv_size)
The iri'th irrep contribution to a full matrix.
See Also
--------
pack_matrix : The inverse operation.
unpack_vector : Corresponding conversion for excitation coefficient vectors.
"""
self.check_s()
cdef size_t flen = self.s[0].fecv_size
cdef size_t rlen = self.saecv_sizes[iri]