akio-tomiya / latticeqcd.jl

A native Julia code for lattice QCD with dynamical fermions in 4 dimension.

LatticeQCD.jl

This code enabales you to perform lattice QCD calculations! A native Julia code for Lattice QCD.

• What is lattice QCD? (PDG) : Lattice regulated quantum chromo-dynamics used in high energy physics.

• What is Julia? : An easy and fast scientific programming launguage with the JIT compiler

Star History

Tutorial

You can start it in Google Colab

Quick start

You can start lattice QCD in 5 steps!

1.Download a Julia binary from Julialang.org. Set a path to the binary of Julia. Julia 1.6 (or higher) is supported. Julia 1.9 (or higher) is supported in LatticeQCD.jl 1.0.4 (or higher).

2.In Julia REPL, push "]" key to enter the package mode and type

add LatticeQCD

and "return" key. Press "backspace" key ( "delete" key for mac) to exit the package mode. You can get the latest version via add LatticeQCD#master.

(All dependence will be solved automatically)

3.Include the package with

using LatticeQCD

4.Make a parameter file with wizard,

run_wizard()

Choose parameters as you want!

5.Start simulation with created your parameter file!

 run_LQCD("my_parameters.toml")

You'll get results!

Of cource, you can write/modify a parameter file by yourself.

Enjoy life with lattice QCD.

To see our demonstration above, execute,

using Plots
using LatticeQCD 
demo()

it takes time before showing up the window.

What is supported?

We support lattice gauge theory in 4 dimensional euclidean spacetime.

• Wizard for parameter files
• Gauge fields
  • Optimized SU(2), SU(3)
  • General SU(N)
  • General gauge action = plaquette + rect + etc action
• Fermions
  • Wilson (2 flavor)
  • Staggered fermion (1-8 tastes ~ flavor)
  • Standard Domain-wall (2 flavor, experimental)
• Configuration generation algorithms
  • Cold/Hot start for SU(N). One instanton configuration for SU(2)
  • Heatbath for SU(N) & overelaxation for a general gauge action
  • Even-odd heatbath for the plaquette action
  • Quenched HMC with SU(N) for a general gauge action
  • HMC (2 flavor Wilson) with SU(N) with a general gauge action
  • HMC (4 taste staggered fermions) with SU(N) with a general gauge action
  • RHMC (any flavor staggered) with SU(N) for a general gauge action*
  • SU(N) stout smeared dynamical fermions (experimental)
  • Self-learning HMC with the plaquette action
• Measurements
  • Plaquette
  • Polyakov loop
  • Chiral condensates (Wilson, staggered)
  • Momentum projected pion correlator (Wilson fermion, staggered)
  • RxT Wilson loop
  • Energy density
  • Topological charge (plaquette, clover and O(a^2) improved definition)
  • Load & measurement mode (load and measure all configurations in a directory)
• Smearing
  • Stout
  • Gradient flow for a generic action (experimental)
• I/O for gauge configurations
  • ILDG format (Binary)
  • JLD format (Default binary file for Julia, one of HDF5)
  • Text file for Bridge++ (Bridgetext)

*If you specified other than Nf=4, 8 with the staggered fermion HMC, RHMC is automatically used. For a machine with the apple silicon, Nf=1-8 is avalable.

To use following functions, please use v 0.1.2

• Fermion integrated HMC with a general gauge action
• Self-learning Monte-Carlo with a general action (ref. this paper )

*Version below 1.0, it uses ***.jl as a default parameter file, and now it uses ***.toml. Version 1.0 supports both parameter file formats.

*Parallelazation is supported by LatticeDiracOperators.jl. See below.

Related packages

LatticeQCD.jl is basically a wrapper of the following packages

• Wilsonloop.jl :Wilsonloop.jl helps us to treat with the Wilson loops and generic Wilson lines in any Nc and dimensions. Wilson lines can be defined in symbolly.
• Gaugefields.jl: Gaugefields.jl is a package for lattice lattice SU(N) gauge fileds. Treating gauge fields (links), gauge actions with MPI and autograd. This can generate quenched configurations.
• LatticeDiracOperators.jl: LatticeDiracOperators.jl is a package for Dirac operators and fermions on the lattice. Treating pseudo-femrion fields with various lattice Dirac operators, fermion actions with MPI. This can generate configurations with dynamical fermions.
• QCDMeasurements.jl: QCDMeasurements.jl is a package for measuring physical quantities. This has measurements for basic quantities like chiral condensates, plaquettes. Moreover, pion correlators and topological charge with several definitions. This also has the gradient flow with several actions.

USAGE/User interface

We support following two user interfaces

1. Julia REPL interface (For beginners, just after the lattice QCD textbook)
2. Genral interface (Experience with another code, for batch job, customised purpose)

Usage 1 was already explained.

For Usage 2, in Julia REPL, push "]" key to enter the package mode and type

add LatticeQCD

Then, LatticeQCD.jl is installed on your machine.

The "PARAMETER_FILE" can be created through the wizard. To use the wizard on the shell, you write the following code (& save as wizard.jl):

using LatticeQCD
run_wizard()

Then, you can run the wizard:

julia wizard.jl

You write the following code (& save as run.jl):

using LatticeQCD
run_LQCD(ARGS[1])

Then, you can execute like

julia run.jl PARAMETER_FILE

then, you get results though standard I/O.

Purpose of the code

We develop this code to achive following things:

1. Good portability (If one has Julia, this code is runnable. All dependences are under control.)
2. Easy to start/ pedagogical (start in 10 minutes)
3. Suite (configuration generation with and without fermions, and measurements)
4. Easy to modify (Good for prototyping)
5. Compatitive speed with Fortran 90 codes

This is the first open source Julia code for lattice QCD. High performance is out of our scope.

How has it been tested?

We compared results to following papers/codes

• Nf=4 SU(3) staggered HMC with https://inspirehep.net/literature/283285
• Quenched SU(2) improved thermodynamics https://inspirehep.net/literature/1614325
• RHMC https://doi.org/10.1051/epjconf/201817507041
• HMC for Wilson and Clover Wilson fermions "Lattice Tool Kit": https://nio-mon.riise.hiroshima-u.ac.jp/LTK/
• Pion correlator with the Wilson-Dirac operator https://inspirehep.net/literature/37901
• Pion correlator with the staggered Dirac operator https://inspirehep.net/literature/21821

Reference

We refer "Lattice Tool Kit" https://nio-mon.riise.hiroshima-u.ac.jp/LTK/ written in Fortran 90.

Acknowledgement

If you write a paper using this package, please refer this code.

E.g. This work is in part based on LatticeQCD.jl (https://github.com/akio-tomiya/LatticeQCD.jl).

latticeqcd.jl's Issues

register v0.1.1

@JuliaRegistrator register

register v0.1.0

@JuliaRegistrator register

Adjoint fermions

Current code does not support fermions in the adjoint representations.

v1.0.5

@JuliaRegistrator register

register v0.1.0

@JuliaRegistrator register

run_wizard() ends with error

Hi,

I was looking to play with this package and I encountered an issue with run_wizard()
First of all I have julia v1.9.1 and I have an environment where only LatticeQCD.jl v.1.0.6 has been installed.
Then I start the REPL and run using LatticeQCD; run_wizard().
If I keep pressing Enter using all the default values, the process ends correctly and I can then run run_LQCD("my_parameters.toml") .

The first problem here is that the wizard ends also explaining that one can run run_LQCD(params_set) directly and that is not working. There is no variable params_set in the session.

The second problem arises if I run the wizard in expert mode and I try to setup a pure gauge SU(2) run.
Here is the entire process as I did it, ending with the error:

julia> using LatticeQCD

julia> 

julia> run_wizard()
--------------------------------------------------------------------------------  
run_wizard       
　　　　　格　　　　　　　格　　　　　　　
　　　　　色　　　　　　　格　　　　
　　　　色色色　　　　　　格　　　
　子子色色色色色子子子子子格子子子子
　　　　色色色　　　　　　格　　　　
　　　　　色　　　　　　　格　　　
　　　　　格　　　　　　　格　　　
　　　　　力　　　　　　　学　　　　　　LatticeQCD.jl
　　　　力力力　　　　　学学学　　　
　子子力力力力力子子子学学学学学子子　　
　　　　力力力　　　　　学学学　　　　　
　　　　　力　　　　　　　学　　　　　　
　　　　　格　　　　　　　格　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　
    
Welcome to a wizard for Lattice QCD.
We'll get you set up simulation parameters in no time.
--------------------------------------------------------------------------------
If you leave the prompt empty, a default value will be used.
To exit, press Ctrl + c.
Choose wizard mode
   simple
 > expert
put the name of the parameter file you make [my_parameters.toml]: su2_ym.toml         
Input Lattice size, L=(Nx,Ny,Nz,Nt)
Nx ? [4]: 16
Ny ? [4]: 16
Nz ? [4]: 16
Nt ? [4]: 4
Lattice is [16, 16, 16, 4]
Choose a gauge group
   SU(3)
 > SU(2)
SU(2) will be used
β ? [2.7]: 2.25
Input random seed. [111]: 1
verbose level ? [2]: 2
verbose level = 2
Do you perform only measurements on configurations in a directory? (no update)
 > No
   Yes
Choose initial configurations
   cold start
 > hot start
   start from a file
   start from one instanton (Radius is half of Nx)
Choose a dynamical fermion
 > Nothing (quenched approximation)
   Wilson Fermion (2-flavor)
   Staggered Fermion
   Domain-wall Fermion (Experimental)
Choose an update method
 > Heatbath
   Hybrid Monte Carlo
Use overrelazation method?
 > true
   false
How many times do you want to do the OR? [3]: 4
Input the number of thermalization steps (no mearurement) [0]: 10
Input the number of total trajectories after the thermalization [101]: 101
Select the measurement methods you want to do:
[press: Enter=toggle, a=all, n=none, d=done, q=abort]
   [X] Plaquette
   [X] Polyakov_loop
   [X] Topological_charge
   [ ] Chiral_condensate
   [ ] Pion_correlator
   [ ] Wilson_loop
 > [X] Energy_density
You measure Energy density
How often measure Plaquette loops? [1]: 10
You measure Polyakov loops
How often measure Polyakov loops? [1]: 10
You measure a topological charge
How often measure a topological charge? [1]: 10
You measure Plaquette loops
How often measure Plaquette loops? [1]: 10
base directory for measurements [./measurements]: 
directory for measurements in ./measurements/ [Heatbath_L16161604_beta2.25_quenched]: 
Perform measurements with the gradient flow?
   No
 > Yes
---------------------------------------------
---set measurements in gradient flow----------
time step for gradient flow? [0.01]: 
How many times do you want to flow gauge fields? [100]: 50
Select the measurement methods you want to do:
[press: Enter=toggle, a=all, n=none, d=done, q=abort]
   [X] Plaquette
   [X] Polyakov_loop
   [X] Topological_charge
   [ ] Chiral_condensate
   [ ] Pion_correlator
   [ ] Wilson_loop
 > [X] Energy_density
You measure Polyakov loops
How often measure Polyakov loops? [1]: 10
You measure a topological charge
How often measure a topological charge? [1]: 10
You measure Plaquette loops
How often measure Plaquette loops? [1]: 10
---done for gradient flow----------
---------------------------------------------
log directory [./logs]: 
logfile name [Heatbath_L16161604_beta2.25_quenched.txt]: 
Choose a configuration format for saving
   no save
   JLD
   ILDG
 > Text format (BridgeText)
How often do you save a configuration in file (Save every)? [10]: 100
Saving directory [./confs_Heatbath_L16161604_beta2.25_quenched]: 
ERROR: UndefRefError: access to undefined reference
Stacktrace:
 [1] getindex
   @ ./essentials.jl:13 [inlined]
 [2] iterate (repeats 2 times)
   @ ./array.jl:893 [inlined]
 [3] construct_dict_from_measurement!(x::Dict{String, Any}, value::Vector{QCDMeasurements.Measurement_parameters})
   @ LatticeQCD.Parameter_structs ~/.julia/packages/LatticeQCD/x0lbR/src/system/parameter_structs.jl:1094
 [4] remove_default_values!(x::Dict{String, Any}, defaultsystem::LatticeQCD.Parameter_structs.Print_Physical_parameters)
   @ LatticeQCD.Parameter_structs ~/.julia/packages/LatticeQCD/x0lbR/src/system/parameter_structs.jl:1072
 [5] remove_default_values!(x::Dict{Any, Any})
   @ LatticeQCD.Parameter_structs ~/.julia/packages/LatticeQCD/x0lbR/src/system/parameter_structs.jl:1115
 [6] run_wizard()
   @ LatticeQCD.Wizard ~/.julia/packages/LatticeQCD/x0lbR/src/system/wizard.jl:600
 [7] top-level scope
   @ REPL[6]:1

I tried a couple of times with different "expert" mode configurations and the wizard was never able to terminate successfully.

What is going wrong here?

`julia src/run.jl PARAMETER_FILE ` fails when `PARAMETER_FILE` is a absolute path

As the title says:

$ julia src/run.jl ~/tmp/LatticeQCD.jl/my_parameters.jl
ERROR: LoadError: SystemError: opening file "/Users/terasaki/tmp/LatticeQCD.jl/Users/terasaki/tmp/LatticeQCD.jl/my_parameters.jl": No such file or directory
Stacktrace:
  [1] systemerror(p::String, errno::Int32; extrainfo::Nothing)
    @ Base ./error.jl:168
  [2] #systemerror#62
    @ ./error.jl:167 [inlined]
  [3] systemerror
    @ ./error.jl:167 [inlined]
  [4] open(fname::String; lock::Bool, read::Nothing, write::Nothing, create::Nothing, truncate::Nothing, append::Nothing)
    @ Base ./iostream.jl:293
  [5] open
    @ ./iostream.jl:282 [inlined]
  [6] open(f::Base.var"#326#327"{String}, args::String; kwargs::Base.Iterators.Pairs{Union{}, Union{}, Tuple{}, NamedTuple{(), Tuple{}}})
    @ Base ./io.jl:328
  [7] open
    @ ./io.jl:328 [inlined]
  [8] read
    @ ./io.jl:434 [inlined]
  [9] _include(mapexpr::Function, mod::Module, _path::String)
    @ Base ./loading.jl:1166
 [10] include(mod::Module, _path::String)
    @ Base ./Base.jl:386
 [11] include
    @ ~/tmp/LatticeQCD.jl/src/system/mainrun.jl:1 [inlined]
 [12] run_LQCD(filenamein::String)
    @ Main.LatticeQCD.Mainrun ~/tmp/LatticeQCD.jl/src/system/mainrun.jl:36
 [13] runtest
    @ ~/tmp/LatticeQCD.jl/src/run.jl:19 [inlined]
 [14] top-level scope
    @ ./timing.jl:210
in expression starting at /Users/terasaki/tmp/LatticeQCD.jl/src/run.jl:26

This error causes due to these lines

LatticeQCD.jl/src/system/mainrun.jl

Lines 31 to 41 in 63cc791

	function run_LQCD(filenamein::String)
	#if isdemo
	# params_set = Params_set(Demo.system,Demo.actions,Demo.md,Demo.cg,Demo.wilson,Demo.staggered,Demo.measurement)
	#else
	filename = filenamein
	include(pwd()*"/"*filename)
	params_set = Params_set(system,actions,md,cg,wilson,staggered,measurement)
	#end
	plaq = run_LQCD(params_set)
	end

especially include(pwd()*"/"*filename)

here is my suggestion, that is, just use abspath(filename)

help?> abspath
search: abspath isabspath AbstractPattern AbstractDisplay

  abspath(path::AbstractString) -> String

  Convert a path to an absolute path by adding the current directory if necessary. Also
  normalizes the path as in normpath.

  ──────────────────────────────────────────────────────────────────────────────────────

  abspath(path::AbstractString, paths::AbstractString...) -> String

  Convert a set of paths to an absolute path by joining them together and adding the
  current directory if necessary. Equivalent to abspath(joinpath(path, paths...)).

Hadron spectrum for arbitral hadrons

The current code can calculate pion correlators and the hadron matrix is there.
Reconstruction of hadron correlator is better to implement.

Debug for gradient flow for a generic actions

Current version supports the gradient flow but it requires further debug.
The scale of flow time does not seems correct.
Debug for flow for a specific action (e.g. Wilson flow) is enough.

v1.0.3

@JuliaRegistrator register

TagBot trigger issue

This issue is used to trigger TagBot; feel free to unsubscribe.

If you haven't already, you should update your TagBot.yml to include issue comment triggers.
Please see this post on Discourse for instructions and more details.

If you'd like for me to do this for you, comment TagBot fix on this issue.
I'll open a PR within a few hours, please be patient!

v1.0.6

@JuliaRegistrator register

v1.0.0

@JuliaRegistrator register

v1.0.7

@JuliaRegistrator register

License issue

It looks like the Fortran code you reference is GPL based,which probably means this package has to be GPL as well

v1.0.2

@JuliaRegistrator register

v1.0.4

@JuliaRegistrator register

Domain-wall fermions

The current code does not support the domain-wall fermion, which
is widely used in lattice QCD.
The code has Wilson fermion and the domain-wall fermion can be realized by
multiple of Wilson fermions.

where can i get the tutorials ??

:P