Input file reference

The input-file driver solves 1D and 2D problems described by two files:

  • an input file name.dat with the settings, and
  • a potential file name.jl with a Julia function for the potential.
using FEMTISE
run_default_eigen_problem(set_type_potential("path/to/name"))   # without ".dat"
Calling the driver from inside a function

set_type_potential defines the potential by include-ing the potential file. At the top level of a script or the REPL this is transparent. If the driver is called from inside a function (or a do block), that function was compiled before the potential existed and Julia reports "method too new to be called from this world context". Call the driver in the latest world:

function my_workflow(path)
    simulation = set_type_potential(path)
    Base.invokelatest(run_default_eigen_problem, simulation)
end

Format rules

The layout is fixed

The parser reads the file by line number and takes the third whitespace-separated token of each line as the value. Therefore:

  • the file must have exactly the 21 lines shown below, in this order, including the two ## ONLY FOR ... lines;
  • the separator must be = with spaces on both sides;
  • fields that do not apply are left empty, but the line must be present;
  • lists of values (params_potential, analysis_param, output_format_type) are separated by spaces.
full_path_name              = ./results/my_run
dom_type                    = s
nev                         = 10
dimension                   = 2D
sigma                       = -10.0
adhoc_file_name             = ./my_potential
potential_function_name     = my_potential
params_potential_types      = f f f
params_potential            = 1.0 0.0 0.0
analysis_param              = false
output_format_type          = jld2 eigen
## ONLY FOR 1D EIGENPROBLEMS
L                           =
Δx                          =
## ONLY FOR 2D EIGENPROBLEMS
Lx                          = 12.0
Ly                          = 12.0
nx                          = 72
ny                          = 72
different_masses            = false
reduced_density             = false

Fields

LineFieldTypeMeaning
1full_path_namepathPrefix of all output files, e.g. ./results/run → ./results/run_eigen_data.jld2. The folder must exist.
2dom_types, ns (+ sns, nss in 2D)s: symmetric domain $(-L/2, L/2)$; ns: $(0, L)$. In 2D, sns is symmetric in $x$ and $(0,L_y)$ in $y$; nss the opposite.
3nevintegerNumber of eigenpairs.
4dimension1D, 2D or 3DDimension of the problem (3D since v0.2.0, see the optional settings).
5sigmarealShift $\sigma$ of the eigensolver: the nev eigenvalues closest to sigma are returned. Put it below the ground state to obtain the lowest levels.
6adhoc_file_namepathPotential file without the .jl extension.
7potential_function_namenameName of the potential function defined in that file.
8params_potential_typeslist of f, i, cType of each parameter: f = Float64, i = Int, c = ComplexF64.
9params_potentiallistValues of the parameters, passed to the potential as a Tuple.
10analysis_paramfalse or 4 valuesParameter sweep, see below.
11output_format_type2 wordsbin eigen, jld2 eigen or jld2 all, see Output files and reloading results. Sweeps accept bin eigen and jld2 eigen.
13Lreal1D: length of the domain.
14Δxreal1D: element size. L/Δx should be an integer.
16, 17Lx, Lyreal2D: side lengths.
18, 19nx, nyinteger2D: number of cells in each direction (element size Lx/nx, Ly/ny).
20different_massesfalse or realfalse: both coordinates have the electron mass. A real number $\mu$ sets $p_2 = \mu/2$, i.e. $\mu = M_1/M_2$ with $M_1 = 1$.
21reduced_densitytrue/false2D: also compute the reduced densities $\rho^{(1)}(x)$, $\rho^{(2)}(y)$.

Optional settings (since v0.2.0)

Lines after line 21 are optional and are read by name (key = value), in any order. Lines starting with # are comments. A misspelled key raises an error instead of being ignored.

## OPTIONAL SETTINGS
masses                      = 1836.15
element_order               = 3
quadrature_degree           = 8
potential_data_file         = ./potential.dat
interpolation               = cubic
analysis_param_2            = 2 0.0 1.0 0.1
Lz                          = 12.0
nz                          = 16
KeyValuesMeaning
massesone value, or one per coordinatemasses in units of the electron mass (default 1)
element_orderintegerdegree of the Lagrange elements (default 2)
quadrature_degreeintegerdegree of exactness of the quadrature (default 3); use $2\ell+2$ or more for guaranteed upper bounds
potential_data_filepathtabulated potential (see Masses, data files and sweeps); leave lines 6–9 empty
interpolationlinear, cubicinterpolation of the tabulated potential
analysis_param_2j λᵢ λ_f Δλsecond swept parameter (needs analysis_param)
Lz, nzreal, integerthird side and number of cells when dimension = 3D

Input files with optional settings, and all 3D problems, are solved with the general solver solve_tise. They require output_format_type = jld2 eigen and return the eigenvalues in ascending order. Input files without optional settings are solved exactly as in v0.1.

Three-dimensional problems. Set dimension = 3D, use the 2D lines for Lx, Ly, nx, ny (lines 20–21 are ignored) and add Lz and nz. The potential receives x[1], x[2], x[3].

The potential file

The potential receives the point x (x[1], and x[2] in 2D) and the tuple of parameters, in the order given in the input file:

# my_potential.jl  —  params = (ω, x0, y0)
function my_potential(x, params::Tuple)
    ω, x0, y0 = params
    return 0.5 * ω^2 * ((x[1] - x0)^2 + (x[2] - y0)^2)
end

Guidelines:

  • Use only arithmetic and functions available in FEMTISE (Base, SpecialFunctions); the file is loaded inside the FEMTISE module.
  • Keep the function type-stable and allocation-free: it is evaluated at every quadrature point of every cell.
  • In 2D, the two coordinates may be two particles (e.g. two electrons on a line). Then the potential contains one-body terms $V(x_1)+V(x_2)$ and the interaction $W(x_1-x_2)$.

Parameter sweeps

analysis_param = j λᵢ λ_f Δλ computes the nev eigenvalues for a sweep of the j-th potential parameter. The mesh is built only once. The computed values are

\[\lambda_k = \lambda_i + k\,\Delta\lambda,\qquad k = 1, 2, \dots, \operatorname{round}\!\big(|\lambda_f-\lambda_i|/\Delta\lambda\big).\]

First value of the sweep

In version 0.1.0 the first computed value is $\lambda_i+\Delta\lambda$, not $\lambda_i$. To include $\lambda_i$, start the sweep one step earlier.

Example: analysis_param = 1 0.5 2.0 0.1 sweeps the first parameter over $0.6, 0.7, \dots, 2.0$. Only eigenvalues are stored (ϵ_matrix, of size nev × number of values, and λvector).

Interactive console

run_default_eigen_problem(set_type_potential()) asks for the same information interactively. Option 5 asks for the path of an input file. Options 1–4 run built-in potentials:

OptionPotentialParameters
11D harmonic oscillator $\tfrac12\omega^2(x-x_1)^2$$\omega$, $x_1$
21D symmetric finite Kronig–Penney chaindepth $V_0$ (negative), period, well width, number of wells (odd)
31D finite square welldepth $V_0$ (negative), width
42D isotropic harmonic oscillator$\omega$, $x_1$, $y_1$

Interactive runs also write name_eigen_problem_attributes.dat, a summary of the settings that collect_result_data(false, name) uses to reload the results.