Tips for ABINIT users and developers

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== December 2020 beautification ======

//Organisation of the ABINIT December 2020 beautification, December 11-23 2020.//

**PLEASE, DO NOT BEGIN THE BEAUTIFICATION UNTIL v9.3.3 IS STARTED**

We plan to work on the tutorials: upgrade the input and reference files, as well as the tutorial web pages. 
For most tutorials, the list of tasks is:

  - [[beauty:2020:tasks|Update pseudopotentials]] used in current tutorials to more recently generated pseudopotentials.
  - Adjust the input variables to the best values to be used.
  - Structure the input files according to a model.
  - Remove superfluous variables (Abinit input files for tutorials should be as short as possible).
  - If any, remove the use of ixc in tutorial. 
  - Get rid of the files file mention in the tutorial.
  - Change the input file suffix from .in to .abi, and the output file suffix from .out to .abo
  - Upgrade the pieces of input and output files that are present in the tutorial, and upgrade associated comments
  - Translate mathematical objects to latex formulas if not yet done, also improve markdown style/formatting ...

Steps 1-5 will need upgrading the input and reference files, without modifying the text of the tutorial.
Steps 6-9 needs the input files and reference output files to be "frozen", at which time you can go through the text of the tutorial and upgrade it. 
All this cannot be done automatically: human work is needed. 

Some developers will also focus on enabling automatic testing (on the test farm) of several tutorials for parallelism (24 cores or more). This is
indeed missing for tests in tutoparal: dfpt_01-02, all dmft, gspw_02-05, all gswvl, all mbt, all moldyn, all string,
ucrpa_03-05 . Also, some new tutorials will be written.
===== In practice : branch, evaluate, do, merge   =====

Please make your contribution in a branch named "user_name"/beauty.
So, start from your develop branch (v9.3.3 of ABINIT), branch your own "beauty" branch, upgrade it to the latest trunk/develop, work in it,
then issue a merge request (using Gitlab) from "user_name"/beauty to trunk/develop.

Explicitly, issue for example 

  - git checkout develop
  - git branch beauty
  - git checkout beauty
  - git merge remotes/trunk/develop (or your method to sync with the trunk)

Then gauge what is to be done :
  - First visualize the current status of your tutorial, using ./mksite.py serve, which needs [[beauty:2020#i_have_not_yet_familiarized_myself_with_abimkdocs_markdown|familiarization with abimkdocs]]. Perhaps go through your tutorial(s) quickly.
  - Look at an example : the first basic tutorial, first from the Web, <https://docs.abinit.org/tutorial/base1>, then from the current ABINIT, likely your local http://127.0.0.1:8000 after you have issued */*/makemake and launched the server with ./mksite.py serve.

Then beautify the tutorial. The five first steps might induce modification of the input files and reference output files. In order to save your (human) time,
prepare them on your own machine. Then, when you think the input file is ready, recreate the reference output file from the reference machine "alps" (LPR)

==== Pseudopotential ====
Please, see the [[beauty:2020:tasks|suggestions]]. 

==== Adjust input variables ====
As an example, in tbase1_3.abi, previously toldff was used for the structural relaxation, while the current practice favors using tolrff .
So toldff has been replaced by tolrff.

==== Structure the input files according to a model ====
Please, have a look at tbase1_1.abi . It is not very long, sections are clearly identified, with relevant comments. It starts with a short description of the input file. It ends (as usual) with the metadata for automatic testing. This section is also clearly identified.
Then in tbase1_2.abi, tbase1_3.abi, tbase1_4.abi and tbase1_5.abi , note that the specific changes with respect to tbase1_1.abi
are first mentioned. The remaining of the input file is kept unchanged with respect to tbase1_1.abi .


==== Remove superfluous variables ====

No superfluous input variable has been removed in tbase1_*.in. 

Still, there is the possibility to have a large simplification of the input files
if several of them share exactly the same set of atoms and their positions.
In this case, think using the "structure" variable (see the description of this input variable from the doc), and define the structure once for all in a separate common file. You will have to choose between the abivar, poscar or netcdf format for such file.

Well, this might have been possible in the tbase1 tutorial, but after consideration, such simplification was discarded in order not to introduce one more concept in this tutorial, which is already quite long.

==== Remove the use of ixc ====
The choice of ixc should be governed by the choice of pseudopotential by default. It is mentioned in tutorial base1.
Of course, in your tutorial(s), you might mention explicitly the flavor of xc functional that is used, following the mention of the pseudopotential used.


==== Removal of files file mention ====
When the input files and reference files are ready, it is time to focus on the text of the tutorial itself. Advice : redo it step-by-step,
checking that the user will not meet an incoherency, either preexisting to this beautification, or created by the beautification.
While redoing the tutorial step-by-step, pay attention to the fact that the files file does not exist anymore. There were a couple of such mentions in tbase1.

==== Change file suffixes ====
Change the input file suffix from .in to .abi, and the output file suffix from .out to .abo . In the tbase1_1.md file, this was needed at numerous places, in the main text, but also in the dialog boxes :
replacing 

    {% dialog tests/tutorial/Input/tbase1_1.in %}
by 

    {% dialog tests/tutorial/Input/tbase1_1.abi %}


==== Upgrade the pieces of input/output files present in the tutorial ====
Changing the pseudopotential, or any other change to active input variable in the input file will trigger modification of the output file as well.
In order for the students not to be lost (and for the tutorial to be clean), it is important to copy again the excerpts of the input/output files that are obsolete. This is also to be done for the figures, that must be regenerated ... In case of difficulty, do not hesitate to start an issue on gitlab, or contact the other developers (abidev@abinit.org). We might benefit from each other expertise using the gitlab channel, but do not stay stucked, or do not simply ignore a real problem.

==== Latex formulas or other markdown style improvement ====
Although most formulas in tutorials are already in Latex, I have spotted a couple of mathematical quantities in tbase1 that were still in text mode ... Using Latex is very easy with the present infrastructure, see the markdown reference below.

**Finally, issue the proper merge request to trunk/develop, then mention in the beautification Google spreadsheet (second sheet, column G) - see the mail sent on 11 December, that you have done the job !**

===== I have not yet familiarized myself with abimkdocs / markdown  =====

All the needed documentation is available at :

  * https://docs.abinit.org/developers/abimkdocs 
  * https://docs.abinit.org/developers/markdown

Going through it for the first time might be 15-20 minutes. 
Training might be another 15 minutes (e.g. first ''*/*/makemake'' then starting the server with ''./mksite.py serve --dirtyreload'',
then trying to make some fake modifications).


===== I have made most modifications to the input file but I need a reference output  =====

I have modified the input file: the mention of the files file is eliminated, the pseudopotential is a brand new one,
the run is proceeding without any problem on my machine, etc. I have upgraded the output reference file from the output on my machine.  What should I do ?

One should indeed rely on reference output files produced on the reference bot, namely alps_gnu_9.3_openmpi (LPR). So, first launch the test of your branch on this bot using the bbportal <https://bbportal.abinit.org>. Then access this bot: follow the instruction given on <https://wiki.abinit.org/doku.php?id=bb:misc#accessing_directly_some_slave>. Then, update the reference output files from the one produced by this bot. Until now, this is a standard procedure when setting up or upgrading an output reference file. **Then, also upgrade the specific excerpts from the output files that are explicitly mentioned in the body of the tutorial**.