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 createparams::Tuple: parameters to create the grid
Returns
model::GmshDiscreteModel: mesh model
References
- https://gitlab.onelab.info/gmsh/gmsh/blob/master/api/gmsh.jl
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 gridBC_type::String: type of boundary conditionsTypeData::Type: type of data<keyword arguments>:homogeneous::Bool=true: if boundary conditions are homogeneousparams::Tuple=(nothing,nothing): parameters for boundary conditions
Returns
BC_values::Array{TypeData,1}: values of boundary conditionsBC_tags::Array{String,1}: tags of boundary conditions
Example
BC_values,BC_tags=make_boundary_conditions("simple_line","FullDirichlet",Float64)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
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,)
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.
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.
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ébilweakform_m::Function: forma bilineal lado derecho de la formulación débiltest::FESpace: espacio de prueba, puede ser MultiFieldFESpacetrial::FESpace: espacio de solución, puede ser MultiFieldFESpacenev::Int=10: número de autovalores requeridostol::Float64=10e-6: relative tolerance for convergence of Ritz valuesmaxiter::Integer=100: maximum number of iterationsexplicittransform::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
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}: eigenvalueseigenvectors::Vector{CellField}: eigenvectors
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 formulationdΩ::Gridap.CellData.GenericMeasure: measure of FE gridUSpace::FESpace: trial FE SpaceVSpace::FESpace: test FE Spaceparams::Tuple=(nev,tol,maxiter,explicittransform,sigma): params to Arpack eigs function.nev::Integer=10: quantity of eigendata to calculatetol::Float64=10e-9: relative tolerance for convergence of Ritz valuesmaxiter::Integer=100: maximum number of iterationsexplicittransform::Symbol=:none: shift and invert should be explicitly invoked in julia codesigma::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)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 formulationdΩ::Gridap.CellData.GenericMeasure: measure of FE gridUSpace::FESpace: trial FE SpaceVSpace::FESpace: test FE Spaceparams::Tuple=(nev,tol,maxiter,explicittransform,sigma): params to Arpack eigs function.nev::Integer=10: quantity of eigendata to calculatetol::Float64=10e-9: relative tolerance for convergence of Ritz valuesmaxiter::Integer=100: maximum number of iterationsexplicittransform::Symbol=:none: shift and invert should be explicitly invoked in julia codesigma::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)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}: parametersx₀::Float64: specific point to centre dirac functionδnorm::Float64: norm value to obtain normalized delta functioncomponent::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)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 functionsTrialSpace::FESpace: Trial finite element spaceOmega: Finite element domaindOmega::Gridap.CellData.GenericMeasure: integration domainx_component::Int: component of specific coordinate variable
Output
expval::Array{Float64}: array of expectation values of specific coordinate
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 functionsTrialSpace::FESpace: Trial finite element spaceOmega: Finite element domaindOmega::Gridap.CellData.GenericMeasure: integration domainx_component::Int: component of specific coordinate variable
Output
var::Array{Float64}: array of variance values of specific coordinate
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 coordinatevar::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)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 functionsTrialSpace::FESpace: Trial finite element spaceOmega: Finite element domaindOmega::Gridap.CellData.GenericMeasure: integration domainx_component::Int: component of specific coordinate variable
Output
sigma::Array{Float64}: array of standar deviation of specific coordinate
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)
FEMTISE.domain_side_lengths — Method
domain_side_lengths(Ω)Side lengths (L₁, L₂) of the bounding box of a two-dimensional triangulation Ω.
FEMTISE.eigenstates_normalization — Method
eigenstates_normalization(ϕ,dΩ)
Aim
- Check eigenstates normalization.
Arguments
ϕ::Vector{CellField}: array of FE eigenstatesdΩ::Gridap.CellData.GenericMeasure: integration domain
Output
nom_vector::Vector{Float64}: array of norm value for specific eigenstate
FEMTISE.norm_l2 — Method
norm_l2(𝜳,dΩ)Aim
- Compute de L2 norm for specific FE wave function
Arguments
𝜳::CellField: specific FE wave functiondΩ::Gridap.CellData.GenericMeasure: integration domain
Output
orthogonality_vector::Real: L2 norm value
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 eigenstatesdΩ::Gridap.CellData.GenericMeasure: integration domainTrialSpace::FESpace: Trial FE space
Output
orthogonality_vector::Vector{Float64}: array of inner product between differents eigenstates
FEMTISE.orthogonality_check — Method
orthogonality_check(ϕ,dΩ)
Aim
- Check eigenstates orthogonality
Arguments
ϕ::Vector{CellField}: array of FE eigenstatesdΩ::Gridap.CellData.GenericMeasure: integration domain
Output
orthogonality_vector::Vector{Float64}: array of inner product between differents eigenstates
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 coordinatereduced_function_DOF2::Vector{Float64}: partial probability density of second coordinate
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 domaindΩ::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.
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 coordinatey::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.
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 coordinatey::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.
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 spacedOmega::Gridap.CellData.GenericMeasure: integration domain
Output
P::Tuple{Array{Float64},Array{Float64}}:P1::Array{Float64}: population of first stateP2::Array{Float64}: population of second state
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 coordinateSy::Vector{Float64}: reduced entropy associated with second coordinateSxy::Vector{Float64}: total entropy associated with both coordinate
Output
I::Vector{Float64}: array of mutual information values
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 functionTrialSpace::FESpace: Trial FE spacedOmega::Gridap.CellData.GenericMeasure: integration domainrenyi_factor::Real: Rényi factor (have to be a Real number)
Output
S::Vector{Float64}: Array of entropy values.
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 functionTrialSpace::FESpace: Trial FE spacedOmega::Gridap.CellData.GenericMeasure: integration domain
Output
S::Vector{Float64}: Array of entropy values.
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)Input-file driver
FEMTISE.load_potential_file — Method
Include the potential file of the input (none is needed for a tabulated potential).
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.
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(seeDriverOptions).
Arguments
data_file_name::String: name of the input file, without the.datextension.
Returns
InputData1D,InputData2DorInputData3D.
Errors
- Throws an
ArgumentErrordescribing the problem if the file is inconsistent.
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.
FEMTISE.default_solver_eigen_problem — Method
default_solver_eigen_problem(params)Aim
- Function to resolve unidimensonal eigen problem
Arguments
params::Params1D: parameters of 1D potential
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 potentialdifferent_masses::Tuple: keyword to specify if we want to simulate two particles with diferent masses
FEMTISE.AnalysisParam — Type
AnalysisParamParameter sweep of an input file: the λindex-th potential parameter takes the values λi + k Δλ, k = 1, …, round(|λf − λi| / Δλ).
FEMTISE.DriverOptions — Type
DriverOptionsOptional 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, ornothing(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::linearor:cubicinterpolation of the tabulated potential.analysis_param_2: second swept parameter (AnalysisParam) orfalse.Lz,nz: third side length and number of cells of 3D problems.
FEMTISE.InputData3D — Type
InputData3DParsed input file of a three-dimensional problem (dimension = 3D).
FEMTISE.Params3D — Type
Params3DSettings 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).
Output and reloading
FEMTISE.read_bin — Method
read_bin(fileName;<keyword arguments>)Aim
- Read binary file
Arguments
fileName::String: name of file datamatrix_data::Bool: optional boolean keyword to specify matrix or array datac_dim::Int: optional column number of matrix data
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 typen::Int: total number of elements in array/matrix datamatrix_data::Bool: boolean keyword to specify matrix or array datac_dim::Int: column number of matrix data
FEMTISE.write_bin — Method
write_bin(x,fileName;<keyword arguments>)Aim
- Write binary file from matrix data
Arguments
x::Matrix{T}: matrix datafileName::String: name of file dataexisting_file::Bool=false: optional boolean keyword to delete or not delete existing data
FEMTISE.write_bin — Method
write_bin(x,fileName;<keyword arguments>)Aim
- Write binary file from array data
Arguments
x::Array{T,1}: array/vector datafileName::String: name of file dataexisting_file::Bool=false: optional boolean keyword to delete or not delete existing data
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
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 filefull_path_name::String: full path name
FEMTISE.interpolation_eigenstates! — Method
interpolation_eigenstates!(eigen_states,USpace)Aim
- Interpolate eigenstates
Arguments
eigen_states::Vector{CellField}: eigenstatesUSpace::FESpace: FE space
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
FEMTISE.load_results — Method
load_results(id)Aim
- Load results from a file
Arguments
id::InputData1D: input data
FEMTISE.load_results — Method
load_results(id)Aim
- Load results from a file
Arguments
id::InputData2D: input data
FEMTISE.load_results — Method
load_results(id::InputData3D)Results of a three-dimensional problem (extended driver, JLD2 output).
FEMTISE.load_results — Method
load_results(id)Aim
- Load results from a file
Arguments
id::InputData: input data
FEMTISE.load_two_parameter_sweep — Method
Results of a two-parameter sweep written by the extended driver.
FEMTISE.triangulation_repair — Method
triangulation_repair(model,grid_type)Aim
- Repair triangulation
Arguments
model::Model: FE grid modelgrid_type::String: FE grid type (could be "simple_line" or "Cartesian2D")
FEMTISE.AnalysisParams2D — Type
AnalysisParams2DResults of a two-parameter sweep: ϵ_tensor[n, i, j] is the n-th eigenvalue (ascending) for the parameter values λvector[i] and μvector[j].
FEMTISE.DefaultBinEigenProblem — Type
DefaultBinEigenProblemResults reloaded from the bin eigen output format: eigenvalues ϵ, eigenfunctions ϕ sampled on the output grid (one column per state) and grid coordinates r.
FEMTISE.DefaultBinEigenProblemReducedDensity — Type
DefaultBinEigenProblemReducedDensityAs DefaultBinEigenProblem, plus the reduced densities rhoDOF1 and rhoDOF2 (one column per state) of a two-dimensional problem.
General solver (v0.2.0)
FEMTISE.TISESolution — Type
TISESolutionResult 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.
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).
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.
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 modeFEMTISE.nearest_sorted — Method
nearest_sorted(ε, ϕ, nev, sigma)The nev eigenpairs closest to sigma, sorted by increasing energy (real parts of the eigenvalues).
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 pointx(x[1],x[2],x[3]), e.g. a Julia function or atabulated_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 thenevreturned 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]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)Tabulated potentials (v0.2.0)
FEMTISE.TabulatedPotential1D — Type
TabulatedPotential1DPotential $V(x)$ interpolated from a table (see tabulated_potential). Callable as V(x) with x a mesh point or a number.
FEMTISE.TabulatedPotential2D — Type
TabulatedPotential2DPotential $V(x, y)$ interpolated bilinearly from a table on a regular grid (see tabulated_potential). Callable as V(x) with x a 2D mesh point.
FEMTISE.locate — Method
Index i of the interval [grid[i], grid[i+1]] that contains z, applying the extrapolation rule.
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.
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;:flatuses 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)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.
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 maximumw);lineshape = :gaussian: $L(\Delta) = \frac{1}{\sqrt{2\pi}\,w}e^{-\Delta^2/(2w^2)}$ (standard deviationw).
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$.
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.
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)$.
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 coordinatesr = (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)Extended input-file driver (v0.2.0)
FEMTISE.driver_cells — Method
Number of cells in each direction.
FEMTISE.driver_domain — Method
Domain (x₁, x₂, y₁, y₂, ...) of the Cartesian mesh described by the input parameters.
FEMTISE.driver_masses — Method
Masses of the coordinates, from the optional masses line or the legacy different_masses field.
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 μ.
FEMTISE.run_extended_eigen_problem — Method
run_extended_eigen_problem(id)Solve the problem described by an input file that uses optional settings or is three-dimensional, and write the results to id.full_path_name * "_eigen_data.jld2". Called by run_default_eigen_problem; not meant to be called directly.
FEMTISE.sampling_grid — Method
Regular sampling grid of the outputs (same points as the original driver for 1D and 2D).
FEMTISE.sweep_values — Method
Values λᵢ + kΔλ, k = 1, …, round(|λf − λi|/Δλ), of a parameter sweep (same rule as the original driver).
FEMTISE.uses_extended_driver — Method
True if the input file needs the extended driver (optional settings or 3D).
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.
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 eigenvalueenergies[level, :, :];gap = (m, n): the energy differenceenergies[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.