TETHYS - Two-dimensional Emitter of THz, Hydrodynamic Simulation.

Version 2.7.0

Companion paper:

Pedro Cosme, João S. Santos, João P.S. Bizarro, Ivan Figueiredo, TETHYS: A simulation tool for graphene hydrodynamic models, Computer Physics Communications, Volume 282, (2023)

Documentation

The full documentation can be generated with Doxygen simply running

$ doxygen Doxyfile

from the root directory , and then accessed from the Documentation.html file.

Simplified flowchart of the code

Requirements

• gcc compiler

• cmake (version 3.16)

  To generate the makefiles

• OpenMP^®

  Responsible for CPU parallelization.

• HDF5^® libraries (version 1.8.20 or higher)

  For the writing of the complete data.

As an example in Fedora systems it should be enough to install the packages: cmake; libgomp; libomp; hdf5; hdf5-devel; hdf5-static. Whereas for Ubuntu,: cmake; libhdf5-103; libhdf5-cpp-103; libhdf5-dev; libhdf5-openmpi-103.

Optional

• Doxygen

  For generating the documentation

• Gnuplot & Python

  For the plotting

Usage

Compilation

For the compilation of the source code a makefile can ge automatically generated with cmake. It is generally a sensible idea to create an empty directory to hold the executable files

$ mkdir build
$ cd build

And then, for the compilation itself.

$ cmake ..
$ make all

Files and Directory structure

At the moment of download the directoy structure looks like the following tree

📂./
│ README.md
│ LICENSE
│ CMakeLists.txt
│ 2DTESTparameters.ini
│ Doxyfile
└─📁.images
└─📁doc
└─📂src
  │ 📄 <...>.cpp
  └─📂 includes 
    └─📄 <...>.h

Thus, all the code source files are at src and header files at includes directory. The doc and .images have the auxilliary files for the correct generation of this README and the rest of the documentation generated by Doxygen. After compilation a lib directory will be created to sore the library archive.

Testing

Two automatic test are included by default in the cmake: the first one for the simulation itself, and the second for the electrical computations. First of all you should copy or move the test .ini file to the build directory

$ mv 2DTESTparameters.ini ./build

Then, to run them both tests use

$ ctest --extra-verbose 

or, if you want to run each one seperatly ctest --extra-verbose -I 1,1,,1 or ctest --extra-verbose -I 2,2,,2 respectively. N.b. those test are intended to simultaneously assess all the different parameters and capabilities of the simulation code but they do not represent any particular physical scenario.

Reconfiguring a simulation

TETHYS was designed and is meant to primarily simulate and study Dyakonov-Shur instability and therefore the boundary conditions required to excite such response are implemented. However, if the user wish to configure the boundary conditions applied to the system differently, he is expected to edit the TETHYS_2D_Main_v<...>.cpp file according to his needs. The default boundary conditions are the following:

DyakonovShurBoundaryCondition::DyakonovShurBc(graph);
DirichletBoundaryCondition::YClosedNoSlip(graph);
if(graph.GetThermDiff()!=0.0){
    DirichletBoundaryCondition::Temperature(graph,0.22f, 0.22f, 0.22f, 0.22f);  
}

to be applied imediatly after both numerical methods. See doxygen documentation for further details.

Running a simulation

1) Fluid simulation

To run a simulation one can simply invoke

$ ./TETHYS_2D 

and the program will prompt the user to provide the necessary parameters for the simulation. The necessary inputs are:

• Sound velocity S (vel_snd)
• Fermi velocity v_F (vel_fer)
• Collision, of the electrons with impurities or defects, frequency (col)
• Shear viscosity (vis)
• Odd viscosity (odd)
• Cyclotron frequency (cyc)
• Thermal diffusivity (therm)
• Saving option (save_mode) and optionally:
• Aspect ratio of the simulation grid x:y (aspect_ratio)

Alternatively, the user can pass directly such parameters as command arguments with

$ ./TETHYS_2D vel_snd vel_fer col vis odd cyc therm save_mode aspect_ratio

Moreover, the parameters can also be passed via a .ini file

$ ./TETHYS_2D parameters.ini

As standard with .ini files sections can be indicated by square brackets as in [section] and comment lines start with a semicolon ; The readble keywords are

Keywords	Parameter
sound	Sound velocity	S
fermi	Fermi velocity	v0
shear	Shear viscosity	νs
odd	Odd/Hall viscosity	νo
col	Collision frequency	1/τ
cycl	Cyclotron frequency	ωc
therm	Thermal diffusivity	α
aspect	Aspect ratio	AR
time	Simulation time	Tmax
save	Save mode	-

2) Electrical response

To later extract the electronic quantities from the fluid simulation data one should run

$ ./TETHYS_ELEC_2D hdf5_2D<...>.h5

Output description

The user can opt for simplified or full output.

In the simplified version the output is a data file named preview_2D<...>.dat organised by tab separated columns with the (normalised) values of time, density at x=L, x component of velocity at x=L , density at x=0 and x component of velocity at x=0 (by this order).

The full output option will return a HDF5 file, hdf5_2D<...>.h5, with the data of density, both velocity components and temperature, besides all the relevant simulation parameters saved as attributes of the file. Each HDF5 file has a root group called Data that houses the simulation attributes as well as the groups Density, VelocityX, VelocityY and Temperature, inside each of these three groups the simulation results are stored for each temporal snapshot, organised in a matricial form.

hdf5_2D<...>.h5
└─📂Data
    │ Atributes
    │ Sound Velocity
    └─📂 Density
    │ │ 📄 snapshot_00000
    │ │ 📄 snapshot_00001
    │ │ 📄 snapshot_00002
    │ ... 
    └─📁 VelocityX
    └─📁 VelocityY
    └─📁 Temperature

Class Hierarchy

Style guide

Semantic Versioning

Standard form of numeric major.minor.patch starting with the initial commit 1.0.0. Small (but relevant) bugs are considered lower level patches and new features (such as updating physical model) are minor level. Major level versions should be saved for breaking updates (like 2D implementation or parallelization)

Version history

1.0.0 Initial commit [16 Sep. 2019]

1.1.0 Updated nonlinear terms in velocity flux, explicit pressure term. (minor changes in variables).

1.2.0 Addition of collisional loss term.
 1.2.1 Mean free path added as command line parameter.
 1.2.2 Update of frequency functions + minor changes in appearance.
 1.2.3 Added warning for the case on non-propagating plasmons + beginning implementation of CI tasks. [17 Nov. 2019]
 1.2.4 New CFL condition.
 1.2.5 Output in HDF5 format. [8 Jan. 2020]

1.3.0 Transition to object-oriented code. Addition of Time Series Analysis and Electronic properties extraction. [1 May. 2020]
 1.3.1 Stored energy at the capacitor gate calculated.

 1.3.2 Viscosity term for Reynolds >10 implemented. [26 May. 2020]
 1.3.3 New class hierarchy on 1D algorithms. [26 Jun. 2020]
 1.3.4 Boundary conditions implemented as a separate class [28 Jun. 2020]

2.0.0 Two dimensional code implementation. 1D version maintained for fast/simpler simulations. [22 Jun. 2020]
 2.0.1 New class hierarchy on 2D algorithms. New organization of header files [26 Jun. 2020]
 2.0.2 Boundary conditions implemented as a separate class [28 Jun. 2020]
 2.0.3 Linear for loops [29 Jun. 2020]
 2.1.0 Magnetic Field inclusion with Godunov Splitting [22 Jul. 2020]
 2.2.0 Shear viscosity with FTCS method. Variable Aspect ratio [20 Sep. 2020]
 2.2.1 Momentum relaxation in 2D simulations [24 Oct. 2020]
 2.3.0 (1,9) Weighted explicit method for viscous terms [17 Nov. 2020]
 2.3.1 Parallelization with OpenMP [25 Nov. 2020]
 2.4.0 Simulation with odd viscosity [12 Feb. 2021]
 2.5.0 Energy transport by conduction and convection [22 May. 2021]
 2.5.1 Initialization by .ini file import [30 Jun. 2021]
 2.5.2 cmake update [29 Aug. 2021]
 2.6.0 Joule heating source added [6 Oct. 2021]
 2.6.1 Documentation revision [8 Oct. 2021]
 2.6.2 Feedback w/ delay in the 1D boundary conditions [15 Jun. 2022]
 2.7.0 Reaction diffusion module of charge neutrality point [22 Jun. 2022]

Internal syntax

Type	Style	E.g.
Macros	Prefix + _ + Upper-case	MAT_PI
Functions	Camel case	InitialCondRand
Variables	Lower-case 3 letters code + suffix	den_mid