API reference

Functions and types are grouped by the stage of the calculation in which they are used. The same docstrings are available in the REPL help mode (?name).

Meshes and boundary conditions

FEMTISE.make_model — Method
make_model(grid_type,params)

Aim

  • Create a mesh model using Gmsh

Arguments

  • grid_type::String: type of grid to create
  • params::Tuple: parameters to create the grid

Returns

  • model::GmshDiscreteModel: mesh model

References

  • https://gitlab.onelab.info/gmsh/gmsh/blob/master/api/gmsh.jl
source
FEMTISE.make_boundary_conditions — Method
make_boundary_conditions(grid_type,BC_type,TypeData;<keyword arguments>)

Aim

  • Create boundary conditions for a given grid and type of boundary conditions

Arguments

  • grid_type::String: type of grid
  • BC_type::String: type of boundary conditions
  • TypeData::Type: type of data
  • <keyword arguments>:
    • homogeneous::Bool=true: if boundary conditions are homogeneous
    • params::Tuple=(nothing,nothing): parameters for boundary conditions

Returns

  • BC_values::Array{TypeData,1}: values of boundary conditions
  • BC_tags::Array{String,1}: tags of boundary conditions

Example

BC_values,BC_tags=make_boundary_conditions("simple_line","FullDirichlet",Float64)
source

Measures, spaces and forms

FEMTISE.bilineal_forms — Method
bilineal_forms(p,q,r,dΩ)

Aim

  • Returns bilineals forms (a(u,v) and b(u,v)) for eigenvalues 1D or 2D (equal masses)

Arguments

  • p::Function: kinetic energy function from Sturm Liouville_Formulation.
  • q::Function: potential energy function from Sturm Liouville_Formulation.
  • r::Function: weight or density function from Sturm Liouville_Formulation.
  • dΩ::Gridap.CellData.GenericMeasure: differential FE domain
source
FEMTISE.fe_spaces — Method
fe_spaces(model,reff,grid_type; <keyword arguments>)

Aim

  • Create finite element (FE) spaces (Trial and Test spaces).

Arguments

  • BC_type::String="FullDirichlet": the type of boundary condition.
  • TypeData::Type=ComplexF64: the type of data to define FE spaces.
  • conf_type::Symbol=:H1: the regularity of the interpolation at the boundaries of cells in the mesh. (e.g.:L2,:H1,:C0,:Hgrad,)
source
FEMTISE.measures — Method
measures(model,degree,tags_boundary)

Aim

The triangulation and integration aproximated Lebesgue measures

Arguments

  • model: FE grid model.
  • degree::Integer: degree of quadrature rule to use in the cells of triangulation.
  • tags_boundary: tags of boundary conditions.
source
FEMTISE.space_coord — Method
space_coord(dom,Δr,n;<keyword arguments>)

Aim

  • Returns coordinate vector (r) and discrete points (pts) for 1D or 2D spaces.
    • if dimension=="1D" ⇒ dom=(x₁,x₂); Δr=Δx; n=nx
    • if dimension=="2d" ⇒ dom=(x₁,x₂,y₁,y₂); Δr=(Δx,Δy); n=(nx,ny)

Arguments

  • dom::Tuple: FE cartesian domain.
  • Δr:: discretization of FE space.
  • n:: number of FE in each direction.
source

Eigenvalue problem

FEMTISE.eigen_problem — Method
eigen_problem(weakform_k,weakform_m,test,trial; <keyword arguments>)

Aim

  • Define eigen problem as an input to solve function where we compute eigen problem by Arpack eigs function.

Arguments

  • weakform_k::Function: forma bilineal lado izquierdo de la formulación débil
  • weakform_m::Function: forma bilineal lado derecho de la formulación débil
  • test::FESpace: espacio de prueba, puede ser MultiFieldFESpace
  • trial::FESpace: espacio de solución, puede ser MultiFieldFESpace
  • nev::Int=10: número de autovalores requeridos
  • tol::Float64=10e-6: relative tolerance for convergence of Ritz values
  • maxiter::Integer=100: maximum number of iterations
  • explicittransform::Symbol=:none: shift and invert should be explicitly invoked in julia code
    • =:auto:
    • =:shiftinvert:
  • sigma::Float64=1.0: the level shift used in inverse iteration.
  • which::Symbol=:LM: eigenvalues of largest magnitude (default)
    • =:SM: eigenvalues of smallest magnitude
    • =:LR: eigenvalues of largest real part
    • =:SR: eigenvalues of smallest real part
    • =:LI: eigenvalues of largest imaginary part (nonsymmetric or complex matrix only)
    • =:SI: eigenvalues of smallest imaginary part (nonsymmetric or complex matrix only)
    • =:BE: compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric matrix only)

Returns

  • EigenProblem: problem definition
source
Gridap.Algebra.solve — Method
solve(prob)

Aim

  • Compute eigen problem by Arpack eigs function and return eigenvalues and eigenvectors.

Arguments

  • prob::EigenProblem: problem deinition

Returns

  • eigenvalues::Vector{Float64}: eigenvalues
  • eigenvectors::Vector{CellField}: eigenvectors
source
FEMTISE.eigen_values_and_eigen_vectors — Method
eigen_values_and_eigen_vectors(p₁,p₂,q,r,dΩ,USpace,VSpace; <keyword arguments>)

Aim

  • Compute matrix eigen problem and return eigenvalues and eigenvectors

Arguments

  • p₁,p₂,q,r::Function: functions from Sturm Liouville formulation
  • dΩ::Gridap.CellData.GenericMeasure: measure of FE grid
  • USpace::FESpace: trial FE Space
  • VSpace::FESpace: test FE Space
  • params::Tuple=(nev,tol,maxiter,explicittransform,sigma): params to Arpack eigs function.
    • nev::Integer=10: quantity of eigendata to calculate
    • tol::Float64=10e-9: relative tolerance for convergence of Ritz values
    • maxiter::Integer=100: maximum number of iterations
    • explicittransform::Symbol=:none: shift and invert should be explicitly invoked in julia code
    • sigma::Float64=1.0: the level shift used in inverse iteration.

Example

using Gridap
using FEMTISE
using LinearAlgebra

# Define functions
p₁(x)=1.0
p₂(x)=0.0
q(x)=0.0
r(x)=1.0
# Define measure
Ω=1.0:0.1:10.0
dΩ=Gridap.CellData.CellData(Ω)
# Define FE Spaces
USpace=fe_space(1,1,Ω)
VSpace=fe_space(1,1,Ω)
# Compute eigenvalues and eigenvectors
ϵ,ϕ=eigen_values_and_eigen_vectors(p₁,p₂,q,r,dΩ,USpace,VSpace)
source
FEMTISE.eigen_values_and_eigen_vectors — Method
eigen_values_and_eigen_vectors(p,q,r,dΩ,USpace,VSpace; <keyword arguments>)

Aim

  • Compute matrix eigen problem and return eigenvalues and eigenvectors

Arguments

  • p,q,r::Function: functions from Sturm Liouville formulation
  • dΩ::Gridap.CellData.GenericMeasure: measure of FE grid
  • USpace::FESpace: trial FE Space
  • VSpace::FESpace: test FE Space
  • params::Tuple=(nev,tol,maxiter,explicittransform,sigma): params to Arpack eigs function.
    • nev::Integer=10: quantity of eigendata to calculate
    • tol::Float64=10e-9: relative tolerance for convergence of Ritz values
    • maxiter::Integer=100: maximum number of iterations
    • explicittransform::Symbol=:none: shift and invert should be explicitly invoked in julia code
    • sigma::Float64=1.0: the level shift used in inverse iteration.

Example

using Gridap
using FEMTISE
using LinearAlgebra

# Define functions
p(x)=1.0
q(x)=0.0
r(x)=1.0
# Define measure
Ω=1.0:0.1:10.0
dΩ=Gridap.CellData.CellData(Ω)
# Define FE Spaces
USpace=fe_space(1,1,Ω)
VSpace=fe_space(1,1,Ω)
# Compute eigenvalues and eigenvectors
ϵ,ϕ=eigen_values_and_eigen_vectors(p,q,r,dΩ,USpace,VSpace)
source

Post-processing

FEMTISE.aprox_dirac_delta — Method
aprox_dirac_delta(x,params)

Aim

  • Approximation of Dirac delta function as rectangular function

Arguments

  • x: independent variable (is a FE coordinate object)
  • params::Tuple{Float64,Float64,Int,Float64}: parameters
    • x₀::Float64: specific point to centre dirac function
    • δnorm::Float64: norm value to obtain normalized delta function
    • component::Int: component of x coordinate
    • Δx::Float64: thickness of rectangular function

Output

  • result::Vector: integral value

Example

x=0:0.1:10;
params=(5.0,1.0,1,0.1);
result=aprox_dirac_delta(x,params)
source
FEMTISE.coord_first_moment — Method
coord_first_moment(psi,TrialSpace,Omega,dOmega,x_component)

Aim

  • Compute first moment of coordinate (specific component)

Arguments

  • psi::Vector{CellField}: array of FE wave functions
  • TrialSpace::FESpace: Trial finite element space
  • Omega: Finite element domain
  • dOmega::Gridap.CellData.GenericMeasure: integration domain
  • x_component::Int: component of specific coordinate variable

Output

  • expval::Array{Float64}: array of expectation values of specific coordinate
source
FEMTISE.coord_second_moment — Method
coord_second_moment(psi,TrialSpace,Omega,dOmega,x_component)

Aim

  • Compute first moment of coordinate (specific component) or position variance

Arguments

  • psi::Vector{CellField}: array of FE wave functions
  • TrialSpace::FESpace: Trial finite element space
  • Omega: Finite element domain
  • dOmega::Gridap.CellData.GenericMeasure: integration domain
  • x_component::Int: component of specific coordinate variable

Output

  • var::Array{Float64}: array of variance values of specific coordinate
source
FEMTISE.coord_standar_deviation — Method
coord_standar_deviation(expval,var)

Aim

  • Compute standar deviation of coordinate (specific component)

Arguments

  • expval::Array{Float64}: array of expectation values of specific coordinate
  • var::Array{Float64}: array of variance values of specific coordinate

Output

  • sigma::Array{Float64}: array of standar deviation of specific coordinate

Example

expval=[1.0,2.0,3.0];
var=[0.1,0.2,0.3];
sigma=coord_standar_deviation(expval,var)
source
FEMTISE.coord_standar_deviation — Method
coord_standar_deviation(psi,TrialSpace,Omega,dOmega,x_component)

Aim

  • Compute standar deviation of coordinate (specific component)

Arguments

  • psi::Vector{CellField}: array of FE wave functions
  • TrialSpace::FESpace: Trial finite element space
  • Omega: Finite element domain
  • dOmega::Gridap.CellData.GenericMeasure: integration domain
  • x_component::Int: component of specific coordinate variable

Output

  • sigma::Array{Float64}: array of standar deviation of specific coordinate
source
FEMTISE.density — Method
density(phi)

Aim

  • Compute probability density from set of specific wave functions (FE object)

Arguments

  • phi::Vector{CellField}: array of eigenstates (array of FE objects)

Output

  • rho::Vector{CellField}: Array of probability densities (array of FE objects)
source
FEMTISE.eigenstates_normalization — Method

eigenstates_normalization(ϕ,dΩ)

Aim

  • Check eigenstates normalization.

Arguments

  • ϕ::Vector{CellField}: array of FE eigenstates
  • dΩ::Gridap.CellData.GenericMeasure: integration domain

Output

  • nom_vector::Vector{Float64}: array of norm value for specific eigenstate
source
FEMTISE.norm_l2 — Method
norm_l2(𝜳,dΩ)

Aim

  • Compute de L2 norm for specific FE wave function

Arguments

  • 𝜳::CellField: specific FE wave function
  • dΩ::Gridap.CellData.GenericMeasure: integration domain

Output

  • orthogonality_vector::Real: L2 norm value
source
FEMTISE.orthogonality_check — Method

orthogonality_check(ϕ,dΩ,TrialSpace)

Aim

  • Check eigenstates orthogonality. Each eigenstate is a multifield FE object.

Arguments

  • ϕ::Vector{CellField}: array of FE eigenstates
  • dΩ::Gridap.CellData.GenericMeasure: integration domain
  • TrialSpace::FESpace: Trial FE space

Output

  • orthogonality_vector::Vector{Float64}: array of inner product between differents eigenstates
source
FEMTISE.orthogonality_check — Method

orthogonality_check(ϕ,dΩ)

Aim

  • Check eigenstates orthogonality

Arguments

  • ϕ::Vector{CellField}: array of FE eigenstates
  • dΩ::Gridap.CellData.GenericMeasure: integration domain

Output

  • orthogonality_vector::Vector{Float64}: array of inner product between differents eigenstates
source
FEMTISE.reduced_density — Method
reduced_density(ϕ,r,model)

Aim

  • Compute partial probability density from set of specific wave functions (FE object)

Arguments

  • phi::Vector{CellField}: array of eigenstates (array of FE objects)
  • r::Tuple{Vector{Float64},Vector{Float64}}:
    • x_vector::Vector{Float64}:: array values of first coordinate (first partial domain)
    • y_vector::Vector{Float64}:: array values of second coordinate (second partial domain)
  • model::CartesianDiscreteModel:: Cartesian discrete 2D model

Output

  • result::Tuple{Vector{Float64},Vector{Float64}}
    • reduced_function_DOF1::Vector{Float64}: partial probability density of first coordinate
    • reduced_function_DOF2::Vector{Float64}: partial probability density of second coordinate
source
FEMTISE.reduced_integration — Method
reduced_integration(FE_function,r_vector,Ω,dΩ)

Aim

  • Integration over reduced coordinate (partial domain) of specific two dimensional FE function

Arguments

  • FE_function::Vector{CellField}: specific 2D FE function to integrate over partial domain.
  • r_vector::Tuple{Vector{Float64},Vector{Float64}}
    • x_vector::Vector{Float64}:: array values of first coordinate (first partial domain)
    • y_vector::Vector{Float64}:: array values of second coordinate (second partial domain)
  • Omega: Finite element domain
  • dΩ::Gridap.CellData.GenericMeasure: full integration domain

Output

  • result::Tuple{Vector{Float64},Vector{Float64}}
    • reduced_function_DOF1::Vector{Float64}: integration of 2D FE function over first partial domain.
    • reduced_function_DOF2::Vector{Float64}: integration of 2D FE function over second partial domain.
source
FEMTISE.reduced_time_indep_entropy — Method
reduced_time_indep_entropy(r,rho,renyi_factor)

Aim

  • Compute time independent Reduced Rényi entropy for specific 2D FE wave function and Rényi factor

Arguments

  • r::Tuple{Vector{Float64},Vector{Float64}}:
    • x::Vector{Float64}: array values of first coordinate
    • y::Vector{Float64}: array values of second coordinate
  • rho::Matrix{Float64}: matrix values of probability density (where rows are rho(x) with fixed y and columns are rho(y) with fixed x)
  • renyi_factor::Float64: Rényi factor (need to be a Real number)

Output

  • S::Tuple{Vector{Float64},Vector{Float64}}:
    • Sx_vector::Vector{Float64}: reduced entropy as integration over first coordinate.
    • Sy_vector::Vector{Float64}: reduced entropy as integration over second coordinate.
source
FEMTISE.reduced_time_indep_entropy — Method
reduced_time_indep_entropy(r,rho)

Aim

  • Compute time independent Reduced Shannon entropy for specific 2D FE wave function

Arguments

  • r::Tuple{Vector{Float64},Vector{Float64}}:
    • x::Vector{Float64}: array values of first coordinate
    • y::Vector{Float64}: array values of second coordinate
  • rho::Matrix{Float64}: matrix values of probability density (where rows are rho(x) with fixed y and columns are rho(y) with fixed x)

Output

  • S::Tuple{Vector{Float64},Vector{Float64}}:
    • Sx_vector::Vector{Float64}: reduced entropy as integration over first coordinate.
    • Sy_vector::Vector{Float64}: reduced entropy as integration over second coordinate.
source
FEMTISE.state_population — Method
state_population(psi,TrialSpace,dOmega)

Aim

  • Compute the population of specific quantum state vector (2D)

Arguments

  • psi::Vector{CellField}: multifield quantum state (2D)
  • TrialSpace::FESpace: Trial finite element space
  • dOmega::Gridap.CellData.GenericMeasure: integration domain

Output

  • P::Tuple{Array{Float64},Array{Float64}}:
    • P1::Array{Float64}: population of first state
    • P2::Array{Float64}: population of second state
source
FEMTISE.time_indep_diff_mutual_information — Method
time_indep_diff_mutual_information(Sx,Sy,Sxy)

Aim

  • Compute time independent Differential Mutual Information

Arguments

  • Sx::Vector{Float64}: reduced entropy associated with first coordinate
  • Sy::Vector{Float64}: reduced entropy associated with second coordinate
  • Sxy::Vector{Float64}: total entropy associated with both coordinate

Output

  • I::Vector{Float64}: array of mutual information values
source
FEMTISE.time_indep_entropy — Method
time_indep_entropy(psi,TrialSpace,dOmega,renyi_factor)

Aim

  • Compute time independent Rényi entropy for specific FE wave function and Rényi factor

Arguments

  • psi::Vector{CellField}: specific FE wave function
  • TrialSpace::FESpace: Trial FE space
  • dOmega::Gridap.CellData.GenericMeasure: integration domain
  • renyi_factor::Real: Rényi factor (have to be a Real number)

Output

  • S::Vector{Float64}: Array of entropy values.
source
FEMTISE.time_indep_entropy — Method
time_indep_entropy(psi,TrialSpace,dOmega)

Aim

  • Compute time independent Shannon entropy for specific FE wave function

Arguments

  • psi::Vector{CellField}: specific FE wave function
  • TrialSpace::FESpace: Trial FE space
  • dOmega::Gridap.CellData.GenericMeasure: integration domain

Output

  • S::Vector{Float64}: Array of entropy values.
source
FEMTISE.uniform_trapezoidal_integration_method — Method
uniform_trapezoidal_integration_method(x_vec,fx_vec)

Aim

  • Numeric integration function using trapezoidal method considering uniform discretization.

Arguments

  • x_vec::Vector: integration domain (array of values)
  • fx_vec::Vector: array function evaluated in integration domain

Output

  • result::Vector: integral value

Example

x=0:0.1:10;
fx=sin.(x);
result=uniform_trapezoidal_integration_method(x,fx)
source

Input-file driver

FEMTISE.run_default_eigen_problem — Method
run_default_eigen_problem(simulation_data)

Run the simulation described by an input file and write its results to disk. simulation_data is the tuple returned by set_type_potential(path), where path is the input file without the .dat extension:

run_default_eigen_problem(set_type_potential("path/to/input"))

Input files with optional settings (masses, potential data files, two-parameter sweeps, 3D problems; FEMTISE ≥ v0.2.0) are solved with the general solver.

source
FEMTISE.input_data — Method
input_data(data_file_name)

Aim

  • Read the input file data_file_name * ".dat" of the input-file driver.

Format

  • Lines 1–21 are mandatory and are read by position (see the "Input file reference" page of the documentation): the value is the third whitespace-separated token of each line.
  • Optional lines after line 21 (since v0.2.0) are read by name, as key = value(s); lines starting with # are comments. Keys: masses, element_order, quadrature_degree, potential_data_file, interpolation, analysis_param_2, Lz, nz (see DriverOptions).

Arguments

  • data_file_name::String: name of the input file, without the .dat extension.

Returns

  • InputData1D, InputData2D or InputData3D.

Errors

  • Throws an ArgumentError describing the problem if the file is inconsistent.
source
FEMTISE.read_driver_options — Method
read_driver_options(attributes, params_potential)

Optional settings in the lines after line 21 of an input file, read by key name. Unknown keys raise an error, so that a misspelled option is never ignored silently.

source
FEMTISE.default_solver_eigen_problem — Method
default_solver_eigen_problem(params)

Aim

  • Function to resolve bidimensonal eigen problem over cartesian grid

Arguments

  • params::Params2D: parameters fo 2D potential
  • different_masses::Tuple: keyword to specify if we want to simulate two particles with diferent masses
source
FEMTISE.AnalysisParam — Type
AnalysisParam

Parameter sweep of an input file: the λindex-th potential parameter takes the values λi + k Δλ, k = 1, …, round(|λf − λi| / Δλ).

source
FEMTISE.DriverOptions — Type
DriverOptions

Optional settings of an input file (lines after the 21 mandatory lines, introduced in v0.2.0). Default values reproduce the behavior of earlier versions.

Fields

  • masses: mass of each coordinate in units of the electron mass, or nothing (electron mass for every coordinate).
  • element_order: degree of the Lagrange elements (default 2).
  • quadrature_degree: degree of exactness of the quadrature (default 3).
  • potential_data_file: data file with a tabulated potential, or "".
  • interpolation: :linear or :cubic interpolation of the tabulated potential.
  • analysis_param_2: second swept parameter (AnalysisParam) or false.
  • Lz, nz: third side length and number of cells of 3D problems.
source
FEMTISE.Params3D — Type
Params3D

Settings of a three-dimensional problem read from an input file (Cartesian mesh of nx × ny × nz cells on a box of sides Lx, Ly, Lz).

source

Output and reloading

FEMTISE.read_bin — Method
read_bin(fileName;<keyword arguments>)

Aim

  • Read binary file

Arguments

  • fileName::String: name of file data
  • matrix_data::Bool: optional boolean keyword to specify matrix or array data
  • c_dim::Int: optional column number of matrix data
source
FEMTISE.read_bin — Method
read_bin(io,::Type{T},n,matrix_data,c_dim)

Aim

  • Speeds up the read binary file

Arguments

  • io::IO: in/output variable
  • ::Type{T}: data type
  • n::Int: total number of elements in array/matrix data
  • matrix_data::Bool: boolean keyword to specify matrix or array data
  • c_dim::Int: column number of matrix data
source
FEMTISE.write_bin — Method
write_bin(x,fileName;<keyword arguments>)

Aim

  • Write binary file from matrix data

Arguments

  • x::Matrix{T}: matrix data
  • fileName::String: name of file data
  • existing_file::Bool=false: optional boolean keyword to delete or not delete existing data
source
FEMTISE.write_bin — Method
write_bin(x,fileName;<keyword arguments>)

Aim

  • Write binary file from array data

Arguments

  • x::Array{T,1}: array/vector data
  • fileName::String: name of file data
  • existing_file::Bool=false: optional boolean keyword to delete or not delete existing data
source
FEMTISE.build_input_data — Method
build_input_data(full_path_name)

Aim

  • Build input data from a file

Arguments

  • full_path_name::String: full path name to input data file
source
FEMTISE.collect_result_data — Method
collect_result_data(switch_input_file,full_path_name)

Aim

  • Collect result data

Arguments

  • switch_input_file::Bool: switch input file
  • full_path_name::String: full path name
source
FEMTISE.interpolation_eigenstates! — Method
interpolation_eigenstates!(eigen_states,USpace)

Aim

  • Interpolate eigenstates

Arguments

  • eigen_states::Vector{CellField}: eigenstates
  • USpace::FESpace: FE space
source
FEMTISE.load_input_data — Method
load_input_data(full_path_input_data)

Aim

  • Load input data from a file

Arguments

  • full_path_input_data::String: full path name to input data file
source
FEMTISE.load_results — Method
load_results(id::InputData3D)

Results of a three-dimensional problem (extended driver, JLD2 output).

source
FEMTISE.triangulation_repair — Method
triangulation_repair(model,grid_type)

Aim

  • Repair triangulation

Arguments

  • model::Model: FE grid model
  • grid_type::String: FE grid type (could be "simple_line" or "Cartesian2D")
source
FEMTISE.AnalysisParams2D — Type
AnalysisParams2D

Results of a two-parameter sweep: ϵ_tensor[n, i, j] is the n-th eigenvalue (ascending) for the parameter values λvector[i] and μvector[j].

source
FEMTISE.DefaultBinEigenProblem — Type
DefaultBinEigenProblem

Results reloaded from the bin eigen output format: eigenvalues ϵ, eigenfunctions ϕ sampled on the output grid (one column per state) and grid coordinates r.

source

General solver (v0.2.0)

FEMTISE.TISESolution — Type
TISESolution

Result of solve_tise.

Fields

  • energies::Vector{Float64}: eigenvalues in ascending order (a.u.).
  • states::Vector{CellField}: eigenfunctions in the same order (finite element functions, normalized: $\int|\psi|^2 d\Omega = 1$).
  • Ω, dΩ: triangulation and integration measure.
  • trial, test: finite element spaces.
  • model: the mesh.
source
FEMTISE.discretization — Method
discretization(model; order = 2, quadrature_degree = 2order + 2,
               boundary_tags = "boundary")

Triangulation, measure and finite element spaces (Lagrange elements of degree order, homogeneous Dirichlet conditions on boundary_tags) of a mesh. They do not depend on the potential, so they can be reused for many potentials.

Returns (Ω, dΩ, trial, test).

source
FEMTISE.hamiltonian_forms — Method
hamiltonian_forms(masses, potential, dΩ, dimension; weight = x -> 1.0)

Forms $a(u,v)$ (Hamiltonian) and $b(u,v)$ (overlap) for the kinetic coefficients given by masses (see kinetic_coefficients) and the potential function potential(x). When all masses are equal the isotropic form of bilineal_forms is used.

source
FEMTISE.kinetic_coefficients — Method
kinetic_coefficients(masses, dimension)

Kinetic coefficients $p_k = 1/(2M_k)$ (atomic units) for each of the dimension coordinates. masses is a number (same mass for every coordinate) or a collection with one mass per coordinate, in units of the electron mass.

kinetic_coefficients(1.0, 1)                 # (0.5,)          electron
kinetic_coefficients((1836.15, 1.0, 1.0), 3) # proton, electron, photon mode
source
FEMTISE.nearest_sorted — Method
nearest_sorted(ε, ϕ, nev, sigma)

The nev eigenpairs closest to sigma, sorted by increasing energy (real parts of the eigenvalues).

source
FEMTISE.solve_tise — Method
solve_tise(model, potential; masses = 1.0, order = 2,
           quadrature_degree = 2order + 2, nev = 10, sigma = 0.0,
           tol = 1e-10, maxiter = 1000, guard_states = 4,
           boundary_tags = "boundary")

Solve the time-independent Schrödinger equation

\[\Big[-\sum_k \frac{1}{2M_k}\frac{\partial^2}{\partial x_k^2} + V(\mathbf{x})\Big]\psi = \varepsilon\,\psi\]

on model (a Gridap mesh in 1, 2 or 3 dimensions) with $\psi = 0$ on the boundary, and return the nev eigenpairs closest to sigma as a TISESolution, sorted by energy.

Arguments

  • potential: function of the mesh point x (x[1], x[2], x[3]), e.g. a Julia function or a tabulated_potential.
  • masses: mass of every coordinate, or one mass per coordinate, in units of the electron mass (default: electrons).
  • order: degree of the Lagrange elements.
  • quadrature_degree: degree of exactness of the Gauss quadrature. The default integrates exactly potentials up to degree 2 (eigenvalues are upper bounds).
  • nev, sigma, tol, maxiter: settings of the shift-and-invert eigensolver.
  • guard_states: number of additional eigenpairs computed and discarded. Krylov eigensolvers can miss members of a degenerate level at the edge of the requested window; the extra states make the nev returned eigenpairs reliable.

Example

using FEMTISE, Gridap
model = CartesianDiscreteModel((-10.0, 10.0), (200,))
sol = solve_tise(model, x -> 0.5 * x[1]^2; nev = 5)
sol.energies          # ≈ [0.5, 1.5, 2.5, 3.5, 4.5]
source
FEMTISE.sweep_eigenvalues — Method
sweep_eigenvalues(model, potential, values1[, values2]; masses = 1.0, order = 2,
                  quadrature_degree = 2order + 2, nev = 10, sigma = 0.0,
                  tol = 1e-10, maxiter = 1000, guard_states = 4,
                  boundary_tags = "boundary")

Eigenvalues as functions of one or two potential parameters. potential(x, λ) (one parameter) or potential(x, λ, μ) (two parameters) is evaluated for every value in values1 (and values2). The mesh, measures and finite element spaces are built once and reused.

Returns a matrix energies[n, i] (one parameter) or an array energies[n, i, j] (two parameters) with the nev eigenvalues closest to sigma, in ascending order at every point.

Example

model = CartesianDiscreteModel((-10.0, 10.0), (200,))
V(x, ω) = 0.5 * ω^2 * x[1]^2
E = sweep_eigenvalues(model, V, 0.5:0.1:2.0; nev = 3)    # E[n, i] ≈ ωᵢ (n - 1/2)
source

Tabulated potentials (v0.2.0)

FEMTISE.locate — Method

Index i of the interval [grid[i], grid[i+1]] that contains z, applying the extrapolation rule.

source
FEMTISE.natural_spline_second_derivatives — Method
natural_spline_second_derivatives(x, y)

Second derivatives at the nodes of the natural cubic spline through (x, y) (zero second derivative at both ends), from the standard tridiagonal system.

source
FEMTISE.tabulated_potential — Method
tabulated_potential(path; interpolation = :linear, extrapolation = :error)
tabulated_potential(x, values; interpolation = :linear, extrapolation = :error)
tabulated_potential(x, y, values; extrapolation = :error)

Build a potential function from tabulated values, read from the data file path or given as arrays.

File formats

  • 1D: two columns, $x$ and $V(x)$, with $x$ strictly increasing.
  • 2D: three columns, $x$, $y$ and $V(x,y)$, containing every point of a regular (tensor-product) grid in any order.

Lines starting with # are comments.

Keyword arguments

  • interpolation: :linear (1D and 2D, bilinear in 2D) or :cubic (natural cubic spline, 1D only). Cubic splines are recommended for smooth potentials: their error decreases as $\Delta^4$ with the spacing $\Delta$ of the table, against $\Delta^2$ for linear interpolation.
  • extrapolation: :error (default) raises an error if the potential is evaluated outside the table, which usually means that the mesh is larger than the table; :flat uses the value at the nearest edge of the table.

Example

V = tabulated_potential("potential.dat"; interpolation = :cubic)
sol = solve_tise(CartesianDiscreteModel((-8.0, 8.0), (320,)), V; nev = 5)
source

Autocorrelation and spectra (v0.2.0)

FEMTISE.autocorrelation — Method
autocorrelation(coefficients, energies, t)

Autocorrelation $C(t) = \sum_n |c_n|^2 e^{-i\varepsilon_n t}$ (ħ = 1) at the times t (a number or a collection), from the expansion coefficients of the wave packet (see expansion_coefficients) and the eigenvalues.

$|C(t)|^2$ is the survival probability of the initial state.

source
FEMTISE.autocorrelation_spectrum — Method
autocorrelation_spectrum(coefficients, energies, ω; width, lineshape = :lorentzian)

Spectrum of the wave packet, $\sigma(\omega) = \sum_n |c_n|^2 L(\omega-\varepsilon_n)$, on the frequencies (energies) ω, with every line broadened by

  • lineshape = :lorentzian: $L(\Delta) = \frac{1}{\pi}\frac{w}{\Delta^2 + w^2}$ (half width at half maximum w);
  • lineshape = :gaussian: $L(\Delta) = \frac{1}{\sqrt{2\pi}\,w}e^{-\Delta^2/(2w^2)}$ (standard deviation w).

These are the Fourier transforms of $C(t)$ damped by $e^{-wt}$ and by $e^{-w^2t^2/2}$, respectively, so they coincide with fourier_transform of the sampled autocorrelation with the matching window. Each line has unit area, so $\int\sigma\,d\omega = \sum_n|c_n|^2$.

source
FEMTISE.expansion_coefficients — Method
expansion_coefficients(ψ₀, states, dΩ)

Coefficients $c_n = \langle\phi_n|\psi_0\rangle = \int \phi_n^*\,\psi_0\,d\Omega$ of the wave packet ψ₀ in the eigenstates states (e.g. sol.states of solve_tise). ψ₀ can be a Julia function of the mesh point or a finite element function.

$\sum_n |c_n|^2$ equals the norm of ψ₀ only if the eigenstates span it: check it to make sure that enough eigenstates were computed.

Note

Eigenvectors of a degenerate level are linearly independent but not necessarily orthogonal; in that case orthonormalize them before computing the coefficients.

source
FEMTISE.fourier_transform — Method
fourier_transform(t, C, ω; window = :none, width = 0.0)

Spectrum $\sigma(\omega) = \frac{1}{\pi}\,\mathrm{Re}\int_0^{T} C(t)\,w(t)\,e^{i\omega t}\,dt$ of an autocorrelation function sampled at equally spaced times t (starting at $t=0$), evaluated at the frequencies ω with the trapezoidal rule.

Windows

  • :none: $w = 1$. Lines have width $\sim\pi/T$ and side lobes.
  • :exponential: $w = e^{-\gamma t}$ with $\gamma =$ width. Lorentzian lines (HWHM $\gamma$); requires $\gamma T \gg 1$.
  • :gaussian: $w = e^{-\gamma^2t^2/2}$ with $\gamma =$ width. Gaussian lines (standard deviation $\gamma$); requires $\gamma T \gg 1$.

With the same width, the result agrees with autocorrelation_spectrum(c, ε, ω; width, lineshape). The cost is $O(N_t N_\omega)$.

source

Pauli–Fierz Hamiltonian (v0.2.0)

FEMTISE.pauli_fierz_potential — Method
pauli_fierz_potential(matter_potential, dipole; frequency, coupling,
                      dipole_self_energy = true)

Potential energy of the Pauli–Fierz Hamiltonian (length gauge, dipole approximation) for matter coupled to one cavity mode, as a function of the mesh point $\mathbf{x} = (x_1, \dots, x_{d-1}, q)$, whose last coordinate is the photon displacement $q$:

\[V(\mathbf{x}) = V_{\rm matter}(\mathbf{r}) + \frac{\omega^2 q^2}{2} + g\sqrt{2\omega}\, q\, d(\mathbf{r}) + \frac{g^2}{\omega}\, d(\mathbf{r})^2, \qquad \mathbf{r} = (x_1,\dots,x_{d-1}).\]

Arguments

  • matter_potential(r), dipole(r): functions of the matter coordinates r = (x₁, …) (a tuple), in atomic units. For an electron at $z$ and a nucleus of charge $Z$ at $R$, the dipole is $d = ZR - z$.
  • frequency: cavity frequency $\omega$.
  • coupling: light–matter coupling $g$ (a.u.).
  • dipole_self_energy: include the term $(g^2/\omega)\,d^2$ (default). Omitting it makes the Hamiltonian unbounded from below for large couplings.

The photon coordinate has unit mass: pass masses (M₁, …, 1.0) to solve_tise.

Example: nucleus–electron–photon

V_matter(r) = my_molecular_potential(r[1], r[2])   # user function, r = (R, z)
d(r) = r[1] - r[2]                              # Z = 1
V = pauli_fierz_potential(V_matter, d; frequency = 0.1, coupling = 0.01)
model = CartesianDiscreteModel((0.5, 6.0, -8.0, 8.0, -20.0, 20.0), (30, 40, 40))
sol = solve_tise(model, V; masses = (918.0, 1.0, 1.0), nev = 6, sigma = -1.0)
source

Extended input-file driver (v0.2.0)

FEMTISE.driver_potential — Method
driver_potential(id)

Potential family V(x, λ, μ) of the input file: the tabulated potential if a data file is given (it does not depend on λ, μ), otherwise the user function potential_function_name(x, params) with the swept parameters replaced by λ and μ.

source
FEMTISE.sweep_values — Method

Values λᵢ + kΔλ, k = 1, …, round(|λf − λi|/Δλ), of a parameter sweep (same rule as the original driver).

source

Plotting (v0.2.0, requires a Makie backend)

FEMTISE.plot_energy_curves — Function
plot_energy_curves(λ, energies; states = 1:size(energies, 1),
                   parameter_label = "Parameter, λ", energy_label = "Energy, εₙ (a.u.)",
                   size = (400, 260))

Eigenvalues as functions of one parameter, energies[n, i] for the values λ[i] (e.g. from sweep_eigenvalues or a one-parameter sweep of the input-file driver). The ground state is drawn as a thick coloured line and the excited states as thin gray lines, so the figure can be printed in black and white. size is the figure size in points.

Requires a Makie backend: using CairoMakie. Returns a Makie.Figure.

source
FEMTISE.plot_energy_map — Function
plot_energy_map(λ, μ, energies; level = 1, gap = nothing,
                labels = ("First parameter, λ", "Second parameter, μ"),
                energy_label = nothing, colormap = :inferno, contours = 8,
                colorscale = identity, size = (400, 300))

Two-dimensional map of an eigenvalue over two parameters, from a two-parameter sweep (energies[n, i, j] for λ[i], μ[j]):

  • gap = nothing: the eigenvalue energies[level, :, :];
  • gap = (m, n): the energy difference energies[n, :, :] - energies[m, :, :] (e.g. (1, 2) for the gap between the two lowest levels).

States are numbered from 0 in the default colour-bar label ($\varepsilon_0$ is the ground state); energy_label replaces it.

colorscale = log10 shows quantities that vary over orders of magnitude (e.g. tunnelling splittings); contour lines are then equally spaced in $\log_{10}$.

The map uses a perceptually uniform colour map with monotonic lightness and contours level lines (black over a white halo, visible on any background), so that it remains readable in black and white.

Requires a Makie backend: using CairoMakie. Returns a Makie.Figure.

source