public class Theta extends Object implements Serializable, Cloneable
The de.jtem.riemann theta function is defined by its mulit-dimensional Fourier series
θ(z|B) = ∑n∈Zg exp( ½(Bn,n)+(z,n) )
,
z∈Cg,B∈Cgxg
.
B
is symmetric and has strictly negative definite real part.
The exponential growth in z
of the Riemann theta function can be factored
out and the remaining oscillatory part can be approximated with a prescribed error
tolerance. Thus we have:
θ(z|B) = exp( factor(z|B) ) · thetaSum(z|B)
,
Separating the exponential factor is crucial when dealing with theta functions. In practice,
they often appear as ratios, in which case the exponential growth can be canceled.
For example,
let a,b,c,d ∈ Cg
with
a+b = c+d mod 2πiZg
. Then
θ(z+a|B)·θ(z+b|B)
f(z) =
θ(z+c|B)·θ(z+d|B)
defines an Abelian function.
The following code fragment is taken from AbelianFunction
,
it shows how you evaluate f(z)
using Theta
:
Theta theat = new Theta( B, tol );
theta.theta( z.plus(a), factorOfZPlusA, thetaSumOfZPlusA );
theta.theta( z.plus(b), factorOfZPlusB, thetaSumOfZPlusB );
theta.theta( z.plus(c), factorOfZPlusC, thetaSumOfZPlusC );
theta.theta( z.plus(d), factorOfZPlusD, thetaSumOfZPlusD );
factor.assign( factorOfZPlusA );
factor.assignPlus( factorOfZPlusB );
factor.assignMinus( factorOfZPlusC );
factor.assignMinus( factorOfZPlusD );
fOfZ.assignExp( factor );
fOfZ.assignTimes( thetaSumOfZPlusA );
fOfZ.assignTimes( thetaSumOfZPlusB );
fOfZ.assignDivide( thetaSumOfZPlusC );
fOfZ.assignDivide( thetaSumOfZPlusD );
Evaluating the theta function may easily lead to overflows or numerical
instabilities, which should be avoided. ( The code above avoids the creation of
temporarily used objects, which can be very beneficial for the performance. )
The first line of the code creates a theta function for a period matrix
B
and a tolerance of tol
for the thetaSum(z|B)
.
This results in an absolute error of
thetaSumZPlusA+thetaSumZPlusB
· exp(factor) · tol thetaSumZPlusC·thetaSumZPlusD
for fOfZ
. This error has be be controled if you want to be really shure what
is going on. In practice it suffies to avoid the poles of f
. This is true because
the estimates, which lead to the approximation of the oscillating part of the Riemann
theta function, are rather weak, and therefore the error for the actual values often falls low
of the tolerance. This is also the reason why we have never experienced
inaccuracies when evaluating first and second order derivatives of the Riemann
theta function. Hence, we have not incorporated error estimates for these.
To create a theta function object you must provide the period matrix and you may provide an error tolerance. Additionally, you may switch off features, which are used by default.
The first is about the fill factor error. The fill factor error is a heuristic to improve
the accuracy of the error prediction. As mentioned earlier the estimates which lead to
the approximation error are rather coarse, which is improved by this heuristic for
the price of loosing the certainty of the 100% error. The smaller
the fill factor, the bigger its influence on the approximation, which
anyway is usually irrelevant for small genus (g<4
).
The second feature is Siegel`s reduction.
uses the modular
transformation property of the Riemann theta function and can reduce the cost of
computing theta functions drasticly. Sometimes you already know that your period
matrix cannot be reduced. In that case you would switch of this feature to save the effort
of checking for a possible reduction.
The SiegelReduction
is implemented without controling
a nasty 8th-root of unity,
which leads to an ambiguity. It is, however, usually neglectable because one only deals
with ratios of theta functions. In case you are interested in theta functions themselves
you still can take advantage of Siegel`s reduction: just evaluate theta at zero
(or any other point) with and
without Siegel`s reduction and determine that 8th-root of unity.
ModularPropertySupport
Finally you can decide whehter you want to use pointwise or uniform approximation. The uniform approximation is the default. Allthough we experienced that for genus g>3 the pointwise is superior. If you experience memory problems, because of the number of terms in the theta sum, you should toggle off the uniform approximation and use the the pointwise.
Further reading:
- | B.Deconinck, M.Heil, A.I.Bobenko, M.van Hoeij, and M.Schmies. Computing Riemann Theta Functions. Is to appear. |
- | M.Heil. Numerical Tools for the study of finite gap solutions of integrable systems. PhD thesis, Technische Universität Berlin, 1995. |
- | E.D.Belokolos, A.I.Bobenko, V.Z.Enolskii, A.R.Its, and V.B.Matveev. Algebro-geometric appoach to nonlinear integrable probems. Springer-Verlag Berlin, 1994. |
- | C.L.Siegel. Topics in complex function theory. Vol.III. John Wiley & Sons, Inc., New York, 1989 |
ThetaWithChar
,
TransformPropertySupport
,
ModularPropertySupport
,
SiegelReduction
,
AbelianFunction
,
Serialized FormConstructor and Description |
---|
Theta(de.jtem.blas.ComplexMatrix periodMatrix)
Creates a Riemann theta function with prescribed
periodMatrix . |
Theta(de.jtem.blas.ComplexMatrix periodMatrix,
double tol)
Creates a Riemann theta function with prescribed
periodMatrix
and error tolerance tol . |
Theta(de.jtem.blas.ComplexMatrix periodMatrix,
double tol,
boolean performSiegelReduction)
Creates a Riemann theta function with prescribed
periodMatrix
and error tolerance tol . |
Theta(de.jtem.blas.ComplexMatrix periodMatrix,
double tol,
boolean performSiegelReduction,
boolean useFillFactorError)
Creates a Riemann theta function
with prescribed
periodMatrix
and error tolerance tol . |
Theta(de.jtem.blas.ComplexMatrix periodMatrix,
double tol,
boolean performSiegelReduction,
boolean useFillFactorError,
boolean uniformApproximation)
Creates a Riemann theta function
with prescribed
periodMatrix
and error tolerance tol . |
Modifier and Type | Method and Description |
---|---|
de.jtem.mfc.field.Complex |
ddLogTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X,
de.jtem.blas.ComplexVector Y)
Evaluates the first logarythmic derivative of the Riemann theta funciton
in the
X and Y direction at Z . |
void |
ddLogTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X,
de.jtem.blas.ComplexVector Y,
de.jtem.mfc.field.Complex DXDYLogThetaAtZ)
Evaluates the second logarythmic derivative of the Riemann theta funciton
in the
X and the Y direction at Z . |
de.jtem.mfc.field.Complex |
ddTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X,
de.jtem.blas.ComplexVector Y)
Evaluates the Riemann theta function, its first derivative
in the
X and Y direction and,
its second derivative into the same direction at Z . |
void |
ddTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X,
de.jtem.blas.ComplexVector Y,
de.jtem.mfc.field.Complex thetaAtZ,
de.jtem.mfc.field.Complex DXThetaAtZ,
de.jtem.mfc.field.Complex DYThetaAtZ,
de.jtem.mfc.field.Complex DXDYThetaAtZ)
Evaluates the Riemann theta function, its first derivative
in the
X and Y direction and,
its second derivative into the same direction at Z . |
void |
ddTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X,
de.jtem.blas.ComplexVector Y,
de.jtem.mfc.field.Complex factor,
de.jtem.mfc.field.Complex thetaSumZ,
de.jtem.mfc.field.Complex thetaSumX,
de.jtem.mfc.field.Complex thetaSumY,
de.jtem.mfc.field.Complex thetaSumXY)
Evaluates the Riemann theta function, its first derivatives
in the
X and Y direction and,
its second derivative into the same direction at Z . |
de.jtem.mfc.field.Complex |
dLogTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X)
Returns the first logarythmic derivative of the Riemann theta function
in the
X direction at Z . |
void |
dLogTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X,
de.jtem.mfc.field.Complex DXLogThetaAtZ)
Evaluates the first logarythmic derivative of the Riemann theta funciton
in the
X direction at Z . |
de.jtem.mfc.field.Complex |
dTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X)
Returns the first derivative of the Riemann theta function
in the
X direction at Z . |
void |
dTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X,
de.jtem.mfc.field.Complex thetaAtZ,
de.jtem.mfc.field.Complex DXThetaAtZ)
Evaluates the Riemann theta function and its first derivative
in the
X direction at Z . |
void |
dTheta(de.jtem.blas.ComplexVector Z,
de.jtem.blas.ComplexVector X,
de.jtem.mfc.field.Complex factor,
de.jtem.mfc.field.Complex thetaSumZ,
de.jtem.mfc.field.Complex thetaSumX)
Evaluates the Riemann theta function and its first derivative
in the
X direction at Z . |
double |
getAccuracy()
Returns accuracy for the oscillatory part of the theta function.
|
de.jtem.blas.ComplexMatrix |
getB() |
int |
getDim()
Returns the dimension of the complex vector space on which the Riemann theta
functions operates.
|
double |
getFillFactor()
Returns the fill factor.
|
ModularPropertySupport |
getModularPropertySupport() |
int |
getNumOfLatticePoints()
Returns number of lattice points which are used for the uniform approximation
of the oscillatory part of the Riemann theta function.
|
de.jtem.blas.ComplexMatrix |
getPeriodMatrix()
Returns period matrix on which the Riemann theta function operates.
|
double |
getRadius()
Returns radius of ellipsoid which is used to determine the lattice
points which are used for the uniform approximation
of the oscillatory part of the Riemann theta function.
|
double |
getShortestLatticeVector()
Returns shortest lattice vector of possibly Siegel reduced period matrix.
|
boolean |
getUseFillFactorError()
Returns whether the heuristic of the fill factor error is used or not.
|
boolean |
isSiegelReductionPerformed()
Returns whether Siegel's reduction algorithm is peroformed or not.
|
boolean |
isUniformApproximation()
Returns whether pointwise or uniform approximation is used.
|
void |
setAccuracy(double accuracy)
Sets the accuracy for the oscillatory part of the theta function.
|
void |
setPeriodMatrix(de.jtem.blas.ComplexMatrix periodMatrix)
Sets periodMatrix on which the Riemann theta function operates.
|
void |
setSiegelReductionPerformed(boolean performSiegelReduction)
Switches between pointwise and uniform approximation.
|
void |
setUniformApproximation(boolean uniformApproximation)
Switches between pointwise and uniform approximation.
|
void |
setUseFillFactorError(boolean useFillFactorError)
Switches the heuristic fill factor error on or off.
|
de.jtem.mfc.field.Complex |
theta(de.jtem.blas.ComplexVector Z)
Returns the Riemann theta function at
Z . |
void |
theta(de.jtem.blas.ComplexVector Z,
de.jtem.mfc.field.Complex thetaAtZ)
Evaluates the Riemann theta function at
Z . |
void |
theta(de.jtem.blas.ComplexVector Z,
de.jtem.mfc.field.Complex factor,
de.jtem.mfc.field.Complex thetaSumZ)
Evaluates the Riemann theta function at
Z . |
public Theta(de.jtem.blas.ComplexMatrix periodMatrix)
periodMatrix
.
The error tolerance is by default e-7
, the fill factor error
and Siegel`s reduction is used.periodMatrix
- symmetric complex matrix with negative definite real partpublic Theta(de.jtem.blas.ComplexMatrix periodMatrix, double tol)
periodMatrix
and error tolerance tol
.
Both, fill factor error and Siegel`s reduction is used.periodMatrix
- symmetric complex matrix with negative definite real parttol
- positive numberpublic Theta(de.jtem.blas.ComplexMatrix periodMatrix, double tol, boolean performSiegelReduction)
periodMatrix
and error tolerance tol
.
It further enables the user to switch off the Siegel`s Reduction.periodMatrix
- symmetric complex matrix with negative definite real parttol
- positive numberperformSiegelReduction
- controles whether or not Siegel`s reduction is performedpublic Theta(de.jtem.blas.ComplexMatrix periodMatrix, double tol, boolean performSiegelReduction, boolean useFillFactorError)
periodMatrix
and error tolerance tol
.
It further enables the user to switch off the Siegel`s Reduction and the
heuristic of the fill factor error.periodMatrix
- symmetric complex matrix with negative definite real parttol
- positive numberperformSiegelReduction
- controles whether or not Siegel`s reduction is performeduseFillFactorError
- controles whether the fill factor or the 100% error is used.public Theta(de.jtem.blas.ComplexMatrix periodMatrix, double tol, boolean performSiegelReduction, boolean useFillFactorError, boolean uniformApproximation)
periodMatrix
and error tolerance tol
.
It further enables the user to switch off the Siegel`s Reduction and the
heuristic of the fill factor error.periodMatrix
- symmetric complex matrix with negative definite real parttol
- positive numberperformSiegelReduction
- controles whether or not Siegel`s reduction is performed.useFillFactorError
- controles whether the fill factor or the 100% error is used.uniformApproximation
- controles whether to use uniform or pointwise approximation.public final void ddTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X, de.jtem.blas.ComplexVector Y, de.jtem.mfc.field.Complex factor, de.jtem.mfc.field.Complex thetaSumZ, de.jtem.mfc.field.Complex thetaSumX, de.jtem.mfc.field.Complex thetaSumY, de.jtem.mfc.field.Complex thetaSumXY)
X
and Y
direction and,
its second derivative into the same direction at Z
.
θ(z|B) = exp( factor ) · thetaSumZ
DXθ(z|B) = exp( factor ) · thetaSumX
DYθ(z|B) = exp( factor ) · thetaSumY
D²X,Yθ(z|B) = exp( factor ) · thetaSumXY
Evaluating the Riemann theta funciton and its first derivative simultanesly can be performed with almost no extra cost.
Z
- argument vectorX
- direction of derivativeY
- direction of derivativefactor
- exponential partthetaSumZ
- oscillatory partthetaSumX
- oscillatory part of first derivative in X
directionthetaSumY
- oscillatory part of first derivative in Y
directionthetaSumXY
- oscillatory part of second derivativepublic final void dTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X, de.jtem.mfc.field.Complex factor, de.jtem.mfc.field.Complex thetaSumZ, de.jtem.mfc.field.Complex thetaSumX)
X
direction at Z
.
θ(z|B) = exp( factor ) · thetaSumZ
DXθ(z|B) = exp( factor ) · thetaSumX
Evaluating the Riemann theta funciton and its first derivative simultanesly can be performed with almost no extra cost.
Z
- argument vectorX
- direction of derivativefactor
- exponential partthetaSumZ
- oscillatory partthetaSumX
- oscillatory part of first derivative in X
directionpublic final double getAccuracy()
public final de.jtem.blas.ComplexMatrix getB()
public final int getDim()
public final double getFillFactor()
public ModularPropertySupport getModularPropertySupport()
public final int getNumOfLatticePoints()
public final de.jtem.blas.ComplexMatrix getPeriodMatrix()
public final double getRadius()
public double getShortestLatticeVector()
public final boolean getUseFillFactorError()
public final boolean isSiegelReductionPerformed()
public final boolean isUniformApproximation()
public final void setAccuracy(double accuracy)
accuracy
- positive numberpublic final void setPeriodMatrix(de.jtem.blas.ComplexMatrix periodMatrix)
periodMatrix
- symmetric complex matrix with negative definite real partpublic final void setSiegelReductionPerformed(boolean performSiegelReduction)
performSiegelReduction
- controles whether Siegel's reduction algorithm is peroformed or not.public final void setUniformApproximation(boolean uniformApproximation)
uniformApproximation
- controles whether pointwise or uniform approximation is used.public final void setUseFillFactorError(boolean useFillFactorError)
useFillFactorError
- controles whether the fill factor or the 100% error is used.public final void theta(de.jtem.blas.ComplexVector Z, de.jtem.mfc.field.Complex factor, de.jtem.mfc.field.Complex thetaSumZ)
Z
.
θ(z|B) = exp( factor ) · thetaSumZ
Z
- argument vectorfactor
- exponential partthetaSumZ
- oscillatory partpublic final de.jtem.mfc.field.Complex ddLogTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X, de.jtem.blas.ComplexVector Y)
X
and Y
direction at Z
.
D²X,Ylog( θ(z|B) ) = DXDYLogThetaAtZ
Z
- argument vectorX
- direction of derivativeY
- direction of derivativeX
and Y
directionpublic final void ddLogTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X, de.jtem.blas.ComplexVector Y, de.jtem.mfc.field.Complex DXDYLogThetaAtZ)
X
and the Y
direction at Z
.
D²X,Ylog( θ(z|B) ) = DXDYLogThetaAtZ
Z
- argument vectorX
- direction of derivativeY
- direction of derivativeDXDYLogThetaAtZ
- second logarythmic derivative in the X
and the Y
directionpublic final de.jtem.mfc.field.Complex ddTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X, de.jtem.blas.ComplexVector Y)
X
and Y
direction and,
its second derivative into the same direction at Z
.Z
- argument vectorX
- direction of derivativeY
- direction of derivativethetaAtZ
- oscillatory partDXThetaAtZ
- oscillatory part of first derivative in X
directionDYThetaAtZ
- oscillatory part of first derivative in Y
directionDXDYThetaAtZ
- oscillatory part of second derivativepublic final void ddTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X, de.jtem.blas.ComplexVector Y, de.jtem.mfc.field.Complex thetaAtZ, de.jtem.mfc.field.Complex DXThetaAtZ, de.jtem.mfc.field.Complex DYThetaAtZ, de.jtem.mfc.field.Complex DXDYThetaAtZ)
X
and Y
direction and,
its second derivative into the same direction at Z
.
θ(z|B) = thetaAtZ
DX θ(z|B) = DXThetaAtZ
DY θ(z|B) = DYThetaAtZ
D²X,Yθ(z|B) = DXDYThetaAtZ
Evaluating the Riemann theta funciton and its first derivative simultanesly can be performed with almost no extra cost.
Z
- argument vectorX
- direction of derivativeY
- direction of derivativethetaAtZ
- oscillatory partDXThetaAtZ
- oscillatory part of first derivative in X
directionDYThetaAtZ
- oscillatory part of first derivative in Y
directionDXDYThetaAtZ
- oscillatory part of second derivativepublic final de.jtem.mfc.field.Complex dLogTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X)
X
direction at Z
.Z
- argument vectorX
- direction of derivativeX
directionpublic final void dLogTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X, de.jtem.mfc.field.Complex DXLogThetaAtZ)
X
direction at Z
.
DXlog( θ(z|B) ) = DXLogThetaAtZ
Z
- argument vectorX
- direction of derivativeDXLogThetaAtZ
- first logarythmic derivative in X
directionpublic final de.jtem.mfc.field.Complex dTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X)
X
direction at Z
.Z
- argument vectorX
- direction of derivativeX
directionpublic final void dTheta(de.jtem.blas.ComplexVector Z, de.jtem.blas.ComplexVector X, de.jtem.mfc.field.Complex thetaAtZ, de.jtem.mfc.field.Complex DXThetaAtZ)
X
direction at Z
.
θ(z|B) = thetaAtZ
DXθ(z|B) = DXThetaAtZ
Evaluating the Riemann theta funciton and its first derivative simultanesly can be performed with almost no extra cost.
Z
- argument vectorX
- direction of derivativethetaAtZ
- value of the Riemann theta function at Z
DXThetaAtZ
- value of first derivative in X
directionpublic final de.jtem.mfc.field.Complex theta(de.jtem.blas.ComplexVector Z)
Z
.Z
- argument vectorZ
public final void theta(de.jtem.blas.ComplexVector Z, de.jtem.mfc.field.Complex thetaAtZ)
Z
.
θ(z|B) = thetaAtZ
Z
- argument vectorthetaAtZ
- value of the Riemann theta function at Z