Package: eastereig
EasterEigConsider a parametric eigenvalue problem depending on a parameter (\nu). This arises for instance inwaveguides, where thewavenumber(eigenvalue) depends on the frequency (parameter)waveguides with absorbing materials on the wall, wheremodal attenuation(eigenvalue imaginary part) depends on the liner properties like impedance, density (parameter)structural dynamics with a randomly varying parameter, where theresonances frequencies(eigenvalue) depend on the parameter...Exceptional points (EP) of non-Hermitian systems correspond to particular values of the parameter leading to defective eigenvalue.
At EP, both eigenvalues and eigenvectors are merging.The aim of this package is tolocateexceptional points and toreconstructthe eigenvalue loci. The theoretical part of this work is described in [1], as for the location ofexceptional pointsand illustrated in [2] for eigenvalues reconstruction in structural dynamics.The method requires the computation of successive derivatives of two selected eigenvalues with respect to the parameter so that, after recombination, regular functions can be constructed. This algebraic manipulation enablesexceptional points (EP) localization, using standard root-finding algorithms;computation of the associated Puiseux series up to an arbitrary order.This representation, which is associated with the topological structure of Riemann surfaces, allows to efficiently approximate the selected pair in a certain neighbourhood of the EP.To use this package :an access to theoperator derivativemust be possiblethe eigenvalue problem must be recast into
[ \mathbf{L} (\lambda(\nu), \nu) \mathbf{x} (\nu) =\mathbf{0}  ]The matrices of discrete operators can be either of numpy type forfull, scipy type forsparseor petsc mpiaij type forsparse parallelmatrices.If eastereig is useful for your research, please cite the following references. If you have some questions, suggestions or find some bugs, report them as issueshere.References[1] B. Nennig and E. Perrey-Debain. A high order continuation method to locate exceptional points and to compute Puiseux series with applications to acoustic waveguides. J. Comp. Phys., 109425, (2020). [doi]; [open access][2] M. Ghienne and B. Nennig. Beyond the limitations of perturbation methods for real random eigenvalue problems using Exceptional Points and analytic continuation. Journal of Sound and vibration, (2020). [doi]; [open access]Basic workflow and class hierarchyeastereigprovides several top level classes:OP class, defines operators of your problemEig class, handles eigenvalues, their derivatives and reconstructionEP class, combines Eig object to locate EP and compute Puiseux seriesLoci class, stores numerical value of eigenvalues loci and allows easy Riemann surface plottingDependencieseastereigis based on numpy (full) and scipy (sparse) for most internal computation and can handlelargeparallel sparse matrices thanks tooptionalimport ofpetsc4py(and mumps),slepc4pyand
andmpi4py. As non-hermitian problems involve complex-valued eigenvalues, computations are realized with complex arithmetic and thecomplex petsc versionis expected.
Tested for python 3.5Remarks :To run an example with petsc (parallel), you need to run python withmpirun. For instance, to run a program with 2 procmpirun -n 2 python myprog.pyInstallYou'll need :python (tested for v >= 3.5);pip (optional).
Note that on ubuntu, you will need to usepip3instead ofpipandpython3instead ofpython. Please see the steps given in the continous integration scriptworkflows.Using pip (preferred)Consider usingpipover custom script (rationalehere).You can installeastereigeither from pypi (main releases only):pip install eastereig [--user]or from github:pip install path/to/EeasterEig-version.tar.gz [--user]or ineditablemode if you want to modify the sourcespip install -e path/to/EeasterEigThe version of the required libraries specified ininstall_requiresfield fromsetup.pyare given to ensure the backward compatibility up to python 3.5. A more recent version of these libraries can be safely used for recent python version.Using python setuptoolsGo to root folder.
and run:python setup.py install [--user]To get the lastest updates (dev relases), run:python setup.py develop [--user]Running testsTests are handled with doctest.To execute the full test suite, run :python -m eastereigDocumentationGenerate documentationRun:pdoc3 --html --force --config latex_math=True  eastereigN.B: The doctring are compatible with several Auto-generate API documentation, like pdoc.
This notably allows to see latex includes.Generate class diagramRun:pyreverse -s0 eastereig -m yes -f ALL
dot -Tsvg classes.dot -o classes.svgN.B: Class diagram generation is done usingpyreverse(installed with pylint and spyder).Generate documentation and class diagramBoth aspects are included in the `makedoc.py' script. So, just run :python ./makedoc.pyGetting startedSeveral working examples are available in./examples/folderAcoustic waveguide with an impedance boundary condition (with the different supported linear libraries)3-dof toy model of a structure with one random parameter (with numpy)To get started, the first step is to define your problem. Basically it means to link the discrete operators (matrices) and their derivatives to theeastereigOP class.
The problem has to be recast in the following form:( \left[ \underbrace{1}_{f_0(\lambda)=1} \mathbf{K}0(\nu) + \underbrace{\lambda(\nu)}{f_1(\lambda)=\lambda} \mathbf{K}1(\nu) + \underbrace{\lambda(\nu)^2}{f_2(\lambda)} \mathbf{K}_2(\nu) \right] \mathbf{x} =  \mathbf{0} ).Matrices are then stacked in the variableKK = [K0,K1,K2].The functionsthat return the derivatives with respect to (\nu) of each matrices have to be put indK. The prototype of this function is fixed (the parameter n corresponds to the derivative order) to ensure automatic computation of the operator derivatives.dK = [dK0,dK1,dK2].Finally,the functionsthat returns derivatives with respect to ( \lambda) are stored in 'flda'flda = [None,ee.lda_func.Lda,ee.lda_func.Lda2].Basic linear and quadratic dependency are defined in the modulelda_func. Others dependencies can be easily implemented; provided that the appropriate eigenvalue solver is also implemented). TheNonekeyword is used when there is no dependency to the eigenvalue, e. g. (\mathbf{K}_0).This formulation is used to automatically compute (i) the successive derivatives of the operator and (ii) the RHS associated to the bordered matrix.These variables are defined by creatinga subclassthat inherits from the eastereigOP class. For example, considering a generalized eigenvalue problem ( \left[\mathbf{K}_0(\nu) + \lambda \mathbf{K}_1(\nu) \right] \mathbf{x} =  \mathbf{0} ) :import eastereig as ee

class MyOP(ee.OP):
    """ Create a subclass of the OP class to describe your problem
    """
    def __init__(self):
        """ Initialize the problem       
        """

        # initialize OP interface
        self.setnu0(z)

        # mandatory -----------------------------------------------------------
        self._lib='scipysp' # 'numpy' or 'petsc'
        # create the operator matrices
        self.K=self.CreateMatrix()
        # define the list of function to compute the derivatives of each operator matrix
        self.dK = [self.dmat0, self.dmat1]        
        # define the list of functions to set the eigenvalue dependency of each operator matrix
        self.flda = [None, ee.lda_func.Lda] 
        # ---------------------------------------------------------------------

    def CreateMyMatrices(self,...):
		""" Create my matrices and return a list
		"""
 		...
    	return list_of_Ki

    def dmat0(self,n):
		""" Return the matrix derivative with respect to nu
		N.B. : The prototype of this function is fixed, the n parameter
		stands for the derivative order. If the derivative is null,
		the function returns the value 0.
		"""
		...
		return dM0

    def dmat1(self,n):
		""" Return the matrix derivative with respect to nu
		N.B. : The prototype of this function is fixed, the n parameter
		stands for the derivative order. If the derivative is null,
		the function returns the value 0.
		"""
		...
		return dM1How to contribute ?If you want to contribute toeastereig, your are welcomed! Don't hesitate toreport bugs, installation problems or ask questions onissues;propose some enhancements in the code or in documentation throughpull requests(PR);suggest or report some possible new usages and why not start a scientific collaboration ;-)...To ensure code homogeneity among contributors, we use a source-code analyzer (eg. pylint).
Before submitting a PR, run the tests suite.LicenseThis file is part of eastereig, a library to locate exceptional points and to reconstruct eigenvalues loci.Eastereig is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.Eastereig is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.You should have received a copy of the GNU General Public License along with Eastereig.  If not, seehttps://www.gnu.org/licenses/.