View source for Real-time dynamics with external field read from file

[[File:Modulated-Gaussian-pulse.png|right|500px |external field from file]]

'''In this tutorial we will see how to generate an external field in a format compatible with Lumen and then use it to run real-time simulation (see for instance Ref. <ref name="sangalli"/>).'''

We will also prove a simple python script to do it, that you can easily modify to create your own external field.

The tutorial is divided in two sections: 1) generate an external field, either with ''YamboPy'' (1.a) or with ''ypp_rt'' (1.b); 2) use the external field in the real-time calculations.

== Generate external field ==

The idea is to generate a file, which we call here <code>EXTFIELD.time</code>, containing the time dependent vector . <code>EXTFIELD.time</code> will be later used in a real-time simulation.
The structure of the file will be the following

        8001   5.00000035E-03
   0.00000000       0.00000000       8.00802198E-08   5.33216726E-03
   5.00000035E-03   0.00000000       1.10453682E-03   5.34489006E-03
   1.00000007E-02   0.00000000       2.20612506E-03   5.30774519E-03
   1.50000006E-02   0.00000000       3.29522160E-03   5.22070238E-03
   2.00000014E-02   0.00000000       4.36120294E-03   5.08422730E-03
   2.50000022E-02   0.00000000       5.39377611E-03   4.89927875E-03
   3.00000012E-02   0.00000000       6.38338085E-03   4.66719037E-03
   3.50000039E-02   0.00000000       7.32029136E-03   4.38982388E-03
   4.00000028E-02   0.00000000       8.19511060E-03   4.06956300E-03
   4.50000018E-02   0.00000000       8.99977796E-03   3.70889902E-03
   5.00000045E-02   0.00000000       9.72598325E-03   3.31101404E-03
   5.49999997E-02   0.00000000       1.03663849E-02   2.87936884E-03
   6.00000024E-02   0.00000000       1.09142270E-02   2.41791131E-03
   6.50000051E-02   0.00000000       1.13641499E-02   1.93037838E-03
   7.00000077E-02   0.00000000       1.17109315E-02   1.42144389E-03
   7.50000030E-02   0.00000000       1.19506177E-02   8.95809906E-04
   8.00000057E-02   0.00000000       1.20803779E-02   3.57942627E-04
   8.50000083E-02   0.00000000       1.20981205E-02  -1.87048965E-04
   9.00000036E-02   0.00000000       1.20029533E-02  -7.33944471E-04
   9.50000063E-02   0.00000000       1.17948940E-02  -1.27798819E-03
   0.100000009      0.00000000       1.14751300E-02  -1.81389856E-03
   ...

The first column contains the time, then in order <math>a(t)</math>, <math>a'(t)</math>, and <math>a''(t)</math>. Befor this info there is a row indicating the length of the file (number of time steps), and the time step duration (<math>dt_f</math>).
Since in the simulation a discrete time step (<math>dt</math>) is also used, <code>EXTFIELD.time</code> must contain all the time steps needed. When generating an external field, care must be taken in choosing the time step to ensure compatibility with the integrator.

* EULER and INVINT are single-time integrators; therefore, the field time step must be equal to the one used in the simulation or an integer fraction of it: <math>dt_f=dt/n</math>.
* CRANKNIC, RK2EXP and RK2 are two-time integrators; the field time step should be half the one used in the simulation or an integer fraction of it: <math>dt_f=dt/(2n)</math>.
* RK4 and RK4EXP are four-time integrators that requires 1/2 and 1/3 of the time-step, therefore the field time-step should be one sixth of the one used in the simulation or and integer fraction of it: <math>dt_f=dt/(6n)</math>.

The code will check that these prescriptions are respected before start simulations. In practice, if you generate a field with <math>dt_f=dt/(6n)</math> this will be ok for all available integrators.

=== Generate external field with YamboPy ===

In YamboPy you can find a tutorial to generate external field in the folder <code>yambopy/tutorial/external_field/generate_field.py</code>You can define your external field in this way:

 def gauss_field(t_steps):
     # In this example we generate a guassian external field
     sigma=5.0*fs2aut # Field width
     T_0  =3.0*sigma
     Expf =np.exp(-(t_steps-T_0)**2/(2.0*sigma**2) )
     a_t  =sigma*np.sqrt(math.pi/2.0)*(special.erf((t_steps-T_0)/(sigma*np.sqrt(2.0)))+1.0)
     ap_t =Expf
     app_t=-Expf*(t_steps-T_0)/sigma**2
     return  a_t,ap_t,app_t

Just a function that generate <math>a(t)</math>, <math>a'(t)</math>, and <math>a''(t)</math> that will be then read from Yambo_rt/Yambo_nl. You can add you function to <code>generate_field.py</code>scritp or use the two that are already implemented

SIN and GAUSS fields.  Notice that the electric field correspond to <math>E(t) = -E_{amp} a'(t)</math>. 

The field amplitude (intensity) and versor are not required because it will be read from the Yambo input

'''Warning:''' only linear polarized external field can generated with YamboPY (to be generlized)

=== Generate external field with ypp_rt ===
With <code>ypp_rt</code> one can generate all external fields that implemented in the Yambo code in the file <code>src/modules/mod_fields.F</code>. This can be usefull to visualize external fields used in Yambo without the need of running a real simulation. However if you want to add a new external field you have to code it in the file <code>src/modules/mod_fields.F</code>. The command to generate external field on file is: <code>ypp_rt -rtplot f</code>. This will generate the following input file:

 TDplots                          # [R] TD observables plot
 RTtime                           # [R] Post-Processing kind: function of time
 RTfields                         # [R] Analize time-dependent fields
 TimeStep= <span style="color:red">1.6666667 </span>         as    # Time step
 % TimeRange
 <span style="color:red">0.000000 |100.000000 | </span>        fs    # Time-window where processing is done
 %
 % EnRngeRt
   0.00000 | 20.00000 |         eV    # Energy range
 %
 ETStpsRt= 200                    # Total Energy steps
 ChirpFac= 0.000000         fs    # Prefactor for linear chirping in frequency space
 Field1_Freq= <span style="color:red">2.000000 </span>     eV    # [RT Field1] Frequency
 Field1_Int= 1000.000000       kWLm2 # [RT Field1] Intensity
 Field1_Width= 0.000000     fs    # [RT Field1] Width
 Field1_kind= "<span style="color:red">SIN</span>"              # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
 Field1_pol= "<span style="color:red">linear</span>"               # [RT Field1] Pol(linear|circular)
 % Field1_Dir
 1.000000 | 0.000000 | 0.000000 |       # [RT Field1] Versor
 %
 Field1_Tstart= <span style="color:red">0.010000</span>   fs    # [RT Field1] Initial Time
In the input file you have to specify a series of parameters, in red: the time step (<code>TimeSpep</code>), the time range (<code>TimeRange</code>), the field kind (<code>Field1_kind</code>), its parameters (<code>Field1_Width</code>, <code>Field1_Freq</code>, etc...) and finally the starting time (<code>Field1_Tstart</code>), usually the first step of the dynamics. <br> Notice that Field direction (<code>Field1_Dir</code>) field intensity (<code>Field1_Int</code>) are not used in the external field generation but read from Yambo input.<br>
Then you run <code>ypp_rt</code> with this input and it will produce a series of files:  <code>YPP_EXTFIELD1_P1.time</code>, <code>YPP_EXTFIELD1_P2.time</code>, <code>YPP_EXTFIELD1_P1.freq</code>, <code>YPP_EXTFIELD1_P2.freq</code><code>.</code>

These files contain the external field and its Fourier transform. In the next section we will see how to use them in real-time dynamics.

== Use generated external field with yambo_rt/yambo_nl ==
In yambo_rt/yambo_nl you can tell to the code to read an external field from file. For example in yambo_nl you generate your input wil the command <code>yambo_nl -u p</code>

 nloptics                         # [R] Non-linear spectroscopy
 % NLBands
  7 |  10 |                           # [NL] Bands range
 %
 NLverbosity= "high"              # [NL] Verbosity level (low | high)
 <span style="color:red">NLstep= 10.0       as</span>    # [NL] Real Time step length
 <span style="color:red">NLtime=120.000000</span>           fs    # [NL] Simulation Time
 NLintegrator= "INVINT"           # [NL] Integrator ("EULEREXP/RK2/RK4/RK2EXP/HEUN/INVINT/CRANKNIC")
 NLCorrelation= "IPA"             # [NL] Correlation ("IPA/HARTREE/TDDFT/LRC/LRW/JGM/SEX/LSEX/LHF")
 NLLrcAlpha= 0.000000             # [NL] Long Range Correction
 NLDamping= 0.200000        eV    # [NL] Damping (or dephasing)
 RADLifeTime=-1.000000      fs    # [RT] Radiative life-time (if negative RADLifeTime=Phase_LifeTime)
 #EvalCurrent                   # [NL] Evaluate the current
 HARRLvcs= 11529            RL    # [HA] Hartree     RL components
 EXXRLvcs= 11529            RL    # [XX] Exchange    RL components
 CORRLvcs= 11529            RL    # [GW] Correlation RL components
 Field1_Freq= 0.100000      eV    # [RT Field1] Frequency
 Field1_Int=  <span style="color:red">1000.00  </span>     kWLm2 # [RT Field1] Intensity
 Field1_Width= 0.000000     fs    # [RT Field1] Width
 <span style="color:red">Field1_kind= "FROM_FILE ./YPP_EXTFIELD1_P1.time"</span> # [RT Field1] Kind(SIN|COS|RES|ANTIRES|GAUSS|DELTA|QSSIN)
 Field1_pol= "linear"             # [RT Field1] Pol(linear|circular)
 % Field1_Dir
   <span style="color:red"> 1.000000 | 0.000000 | 0.000000 |  </span>      # [RT Field1] Versor
 %
You have to specify the file kind <code>FROM_FILE</code> and give the path of the file containing the external field. Do not forget also to use the same <code>NLtime</code> and  in the <code>ypp</code> and <code>yambo</code> inputs. Notice that field intensity and field versor is specified in the <code>Yambo</code> input only.

Notice that <code>NLtime</code> in the simulation can be larger then the one used in the external field generation, the code will assume that field that after a given time the field is zero.

== References ==
<references>
<ref name="sangalli" >D. Sangalli, ''Excitons and carriers in transient absorption and time-resolved ARPES spectroscopy: An ab initio approach'', [https://arxiv.org/pdf/2106.03592 Phys. Rev. Materials 5, 083803, (2021)]. </ref>
</references>