Skip to content

GitLab

Commit 63df7ad5 authored by Nick R. Papior's avatar Nick R. Papior
Browse files

Merged documentation, see Docs/branch-changes/NOTES.documentation 

This merge introduces a new documentation scheme for LaTeX.
It intrinsically introduces clickable fdf-flags and creates 3
relevant indices, 1) regular index, 2) fdf-flag (only!) index
and a files index.

Test-suite ran. No problems (some of them, however, needs to be 
updated such that problems shouldn't occur)
parents 93a67ec8 c23d7c51
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 17732 additions and 6388 deletions
Docs/Contributors.txt
View file @ 63df7ad5
......@@ -64,6 +64,7 @@ Andrew Walkingshaw
Toby White
Francois Willaime
Chao Yang
Ramon Cuadrado
O.F. Sankey, D.J. Niklewski and D.A. Drabold made the FIREBALL code
available to P. Ordejon. Although we no longer use the routines in
......
Docs/Makefile
View file @ 63df7ad5
SHELL := /bin/bash
rerun = "(There were undefined references|Rerun to get (cross-references|the bars) right)"
doc = siesta
latex = pdflatex -shell-escape
grep = @-grep -i -s
splitidx = splitindex
docidx = $(doc).idx
bibtex = echo "BIBTEX"
bibtex = bibtex
makeidx = makeindex
pdf: $(doc)
@echo "Done"
# Handler for creating the documentation in different
# text-sizes
SIZE ?= 11
input = "\\def\\siestatextsize{$(SIZE)pt}"
$(doc): $(doc).tex
$(latex) $(doc).tex
compress:
gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.5 \
-dNOPAUSE -dQUIET -dBATCH \
-sOutputFile=$(doc)-compressed.pdf $(doc).pdf
# Default build both
pdf: tbtrans siesta
all: final-screen final
doc: $(doc).tex
# Currently there are two manuals
%.pdf: %.tex FORCE
$(latex) "$(input) \\input{$<}"
%-screen.pdf: %.tex FORCE
$(latex) "$(input) \\def\\siestascreen{1} \\input{$<}"
# Basic targets
.PHONY: siesta siesta-screen
siesta: siesta.pdf
siesta-screen: siesta-screen.pdf
.PHONY: tbtrans tbtrans-screen
tbtrans: tbtrans.pdf
tbtrans-screen: tbtrans-screen.pdf
extra-siesta:
$(bibtex) siesta
$(splitidx) siesta.idx
$(makeidx) siesta
extra-tbtrans:
$(bibtex) tbtrans
$(splitidx) tbtrans.idx
$(makeidx) tbtrans
extra:
$(bibtex) $(doc)
$(makeidx) $(doc)
# Create final SIESTA manual
final-siesta:
$(MAKE) siesta
$(MAKE) siesta
$(MAKE) extra-siesta
$(MAKE) siesta
$(MAKE) siesta
final: clean $(doc).tex
$(latex) $(doc).tex
$(bibtex) $(doc)
$(makeidx) $(doc)
$(latex) $(doc).tex
$(latex) $(doc).tex
# Create final SIESTA manual for the screen
final-siesta-screen:
$(MAKE) siesta-screen
$(MAKE) siesta-screen
$(MAKE) extra-siesta
$(MAKE) siesta-screen
$(MAKE) siesta-screen
-mv siesta.pdf siesta-screen.pdf
# Create final tbtrans manual
final-tbtrans:
$(MAKE) tbtrans
$(MAKE) tbtrans
$(MAKE) extra-tbtrans
$(MAKE) tbtrans
$(MAKE) tbtrans
# Create final tbtrans manual for the screen
final-tbtrans-screen:
$(MAKE) tbtrans-screen
$(MAKE) tbtrans-screen
$(MAKE) extra-tbtrans
$(MAKE) tbtrans-screen
$(MAKE) tbtrans-screen
-mv tbtrans.pdf tbtrans-screen.pdf
final: clean final-siesta final-tbtrans
final-screen: clean final-siesta-screen final-tbtrans-screen
# Clean targets
clean:
rm -f $(doc).{lot,oct,aux,auxlock,makefile,figlist,bbl,log,ilg,lof,ind,out,blg,gls,glo,glg,idx,toc,bcf,run.xml} $(doc)-blx.bib
rm -f {siesta,tbtrans}.{lot,oct,aux,auxlock,makefile,figlist,bbl,log,ilg,lof,ind,out,blg,gls,glo,glg,idx,toc,bcf,run.xml} {siesta,tbtrans}-*.[^p]*
cleanpdf:
rm -f $(doc).pdf
clean-all: cleanall
cleanall: clean
rm -f {siesta,siesta-screen,tbtrans,tbtrans-screen}.pdf
compress:
gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.5 \
-dNOPAUSE -dQUIET -dBATCH \
-sOutputFile=siesta-compressed.pdf siesta.pdf
help:
@echo "Help for creating the documentation for SIESTA"
@echo ""
@echo " Type:"
@echo " make"
@echo " to build the documentation once."
@echo " Type:"
@echo " make final"
@echo " to build the documentation with references and everything."
@echo ""
@echo " The text-size may be controlled by adding SIZE=10|11|12"
@echo " on the command line. I.e."
@echo " make final SIZE=10"
@echo " will build the SIESTA manual with textsize 10pt."
@echo ""
@echo " The manuals may also be build in screen-compatible sizes"
@echo " To compile for a 4:3 screen type:"
@echo " make final-screen"
@echo " And the resulting manual will be suffixed with '-screen.pdf'"
@echo ""
@echo " Lastly, one may build all by using:"
@echo " make all"
check: citations references badness undefined underfull overfull warning
......@@ -79,3 +168,4 @@ overfull:
@echo Finds overfull
$(grep) "overfull" $(doc).log
FORCE:
Docs/README
View file @ 63df7ad5
......@@ -2,14 +2,14 @@ To prepare a hard-copy version of the manual, use the (pdf)LaTeX program:
Formerly, one had to do manually:
(pdf)latex siesta
(pdf)latex siesta
pdflatex siesta
pdflatex siesta
splitidx siesta
makeindex siesta
(pdf)latex siesta
(pdf)latex siesta
[+ dvips siesta if you use plain latex]
pdflatex siesta
pdflatex siesta
Now it is enough to type 'make' in the Docs directory to create the manual (for
this you need a reasonably up-to-date TeX distribution).
Type 'make final' to fully create the manual.
Type 'make' if you do not have 'splitidx' and/or 'makeindex'.
Docs/branch-changes/NOTES.documentation 0 → 100644
View file @ 63df7ad5
Full restructure of the TeX documentation method.
This will accommodate a complete environment in TeX for more stringent
formatting of the documentation.
This will be a work-in-progress as not all flags are transferred but
will be eventually.
# Splitting of siesta and tbtrans documentation #
The documentation also splits the tbtrans and siesta manual in two.
This is to accommodate the tbtrans as a stand-alone program (which it
now is).
The siesta manual links to the tbtrans manual (if it is in the same folder).
## fdf-options ##
The fdf-options should be documented as these examples:
\begin{fdfentry}{FDF.Name!SubName}[real]<$0.1$>
\end{fdfentry}
\begin{fdflogicalT}{FDF.Name!Logical.Default.True}
\end{fdflogicalT}
\begin{fdflogicalF}{FDF.Name!Logical.Default.False}
\end{fdflogicalF}
For instance
\begin{fdfentry}{FDF.Name!SubName}[real]<$0.1$>
Description of the FDF flag.
\end{fdfentry}
To make examples of fdf flags, use this enviroment (which is a VERBATIM environment
in disguise):
\begin{fdfexample}
\end{fdfexample}
Similarly for shell examples:
\begin{shellexample}
\end{shellexample}
Note that the internals of the commands will automatically convert:
FDF.Name!SubName into FDF.Name.SubName but will use the ! when adding the
flag to the index files. One may reference fdf flags in the text via:
\fdf{FDF.Name!SubName} which will 1) add the place in the file to the index (for back-referencing),
and 2) transform the shown text as a link to the block where it is created.
This will make reading the manual much easier as one may press the flags
and automatically be moved to the location in the PDF (if the viewer supports it).
If one does not wish to create a link, one may use the starred variant of the
\fdf* command.
## Files ##
Files in the manual may be referenced using: \file{full-file-name} and/or
\sysfile{file-ending}, where the latter is a shorthand for \file{<SystemLabel>.file-ending}.
## Manual indices ##
The new siesta documentation now splits the index into 3, 1) contains generic
index entries, 2) all fdf-flags, and 3) the siesta files.
To add specific entries in the regular index, simply use the \index command. To add to the
fdf index, use \fdfindex. For adding to the file index, use \fileindex.
# release script #
This branch introduces the release.sh script which enables an
easy release tarball creation.
We encourage that it is called with these options:
./Docs/release.sh --prev-tag v3.2 --tag v4.0
To create the release of version 4.0.
The script will create a siesta-releases folder in your main shared
directory with sub-folders with the appropriate files.
By default will the release.sh script try and sign the files using your
default GPG key.
The previous tag is used to generate a CHANGES and CHANGES_DETAILED file
which contain the entire log of the commit messages.
## Tags ##
The release script of siesta requires certain strictness in the
\ No newline at end of file
Docs/compatibility.tex
View file @ 63df7ad5
......@@ -3,6 +3,8 @@
\usepackage[a4paper]{geometry}
\newcommand\siesta{\textsc{SIESTA}}
\newcommand\tsiesta{\textsc{TranSIESTA}}
\newcommand{\opt}[1]{{\bf #1}}
\newcommand{\code}[1]{{\tt #1}}
......@@ -21,6 +23,11 @@ This list describes the compatibility issues when using different versions of \s
\setlength\itemsep{1pt}
\setlength\topsep{1pt}
\item[4.1] Since 4.1 \tsiesta\ has been fully redeveloped. The entire algorithm has been
revised and substantial improvements on performance and numerical precision has been
achieved. One cannot compare, directly, the results although the transmissions should
be equivalent.
\item[0 --- 4.0-b2] The following compatibility issues should be remarked when
comparing with any later version of \siesta.
......
Docs/release.sh 0 → 100755
View file @ 63df7ad5
#!/bin/bash
# Script for preparing a release
# of SIESTA.
# Script-author:
# Nick R. Papior, 2016
#
# We encourage the use such as this:
# To create the 4.0 release, we would advocate performing
# this command:
# ./release.sh --prev-tag siesta-3.2 --tag 4.0-release \
# --out siesta-4.0
# which creates the file:
# siesta-releases/siesta-4.0.tar.gz
# We encourage that the prev-tag is ALWAYS the previous
# stable release tag.
# This ensures a consistent changes file shipped with
# the tar-file.
# I.e. for the 4.1 release, the command would be:
# ./release.sh --prev-tag 4.0-release --tag 4.1-release \
# --out siesta-4.1
# This may actually not be changed, but is useful
# throughout.
main_dir=`bzr root`
shared_dir=$(dirname $main_dir)
# Ensure we are at the root of this file
pushd $main_dir
# First we setup the default options
# _reldir is the main directory of the SIESTA shared
# repository (or at least it should be)
_reldir=$(dirname $main_dir)/siesta-releases
_sign=1
# Get the previous major release tag
_prev_tag=`bzr tags --sort=time | grep -e '^v' | grep -v '-' | tail -2 | head -1 | awk '{print $1}'`
# Get the latest tag
_tag=`bzr tags --sort=time | grep -e '^v' | tail -1 | awk '{print $1}'`
# Get default output file (siesta-<>.tar.gz)
_out=
function _has_tag {
local tag=$1
shift
local ret=1
for T in `bzr tags | awk '{print $1}'`
do
if [ "$tag" == "$T" ]; then
ret=0
fi
done
printf "%d" "$ret"
}
function _help {
local ret=$1
shift
echo "$0 creates a release of the SIESTA code at the tip-tag"
echo ""
echo "These options may be used to control the archive."
echo ""
echo " --prev-tag instead of selecting the second-latest tag, choose this tag as the"
echo " reference tag for creating a diff with regards to the --tag tag [bzr tags --sort=time]"
echo " --tag instead of selecting the latest tag, choose this tag as the"
echo " reference tag for creating a release archive [bzr tags --sort=time]"
echo " --out the default output file is siesta-<tag>.tar.gz."
echo " --help|-h show this help."
exit $ret
}
# Function for signing a specific file
function _sign {
local file=$1
if [ -e $file ]; then
if [ $_sign -eq 1 ]; then
gpg --armor --sign --detach-sig $file
fi
_store $file
if [ $_sign -eq 1 ]; then
_store $file.asc
rm -f $file.asc
fi
fi
}
# Save file in the $_tag-files folder
function _store {
local file=$1
if [ -e $file ]; then
cp $file $_reldir/$_tag-files/
fi
}
# First we check whether the release-manager has
# specified the tag that is going to be shipped.
while [ $# -gt 0 ]; do
opt=$1
shift
case $opt in
--tag)
_tag=$1
# Check that the tag exists
if [ $(_has_tag $_tag) -eq 1 ]; then
echo "$0 could not find tag: '$_tag' in the tags list."
echo "The available tags are:"
bzr tags | awk '{print " ",$1}'
exit 1
fi
shift
;;
--prev-tag)
_prev_tag=$1
# Check that the tag exists
if [ $(_has_tag $_prev_tag) -eq 1 ]; then
echo "$0 could not find tag: '$_prev_tag' in the tags list."
echo "The available tags are:"
bzr tags | awk '{print " ",$1}'
exit 1
fi
shift
;;
--no-sign)
_sign=0
;;
--out)
_out=$1
shift
;;
--help|-h)
_help 0
;;
esac
done
# Get default output file (siesta-<>.tar.gz)
if [ -z "$_out" ]; then
_out=siesta-${_tag//v/}
_out=${_out//-release/}
_out=${_out//-rel/}
_out=${_out//release-/}
_out=${_out//rel-/}
fi
echo "Chosen tags are:"
echo " previous tag: $_prev_tag"
echo " current tag : $_tag"
echo "Creating out file:"
echo " $_out.tar.gz"
sleep 1
# The current procedure of releasing a SIESTA
# version is the following:
# 0. Create the necessary directories
# 1. Create CHANGES and sign-store them.
# 2. Make the proper documentation
# 3. Go out of the top-directory to create the repository.
# Top release directories, in case it is not already
# created.
mkdir -p $_reldir
# The final directory with ALL release files, possibly
# signed.
mkdir -p $_reldir/$_tag-files
# If the release already exists... Tell the user and quit
if [ -d $_reldir/$_out ]; then
echo "The release has already been processed."
echo "Delete this folder:"
echo " rm -rf $(dirname $main_dir)/$_reldir/$_tag"
exit 1
fi
# Create a temporary work-directory
bzr export -r $_tag $_reldir/$_out $main_dir
# Create the changes files
# This is necessary to do here as the previous
# siesta versions may not have the tags related.
{
echo "##############################################"
echo " Changes between $_prev_tag and $_tag"
echo "##############################################"
echo ""
bzr log -r$_prev_tag..$_tag
} > $_reldir/$_out/CHANGES
{
echo "##############################################"
echo " Detailed Changes between $_prev_tag and $_tag"
echo "##############################################"
echo ""
bzr log -n 0 -r$_prev_tag..$_tag
} > $_reldir/$_out/CHANGES_DETAILED
# Go into the release directory where all work will be done
pushd $_reldir
pushd $_out
# Create documentation
pushd Docs
# First create the screen variants...
make final-screen
# Then the regular documentation (for print)
make final
# Clean-up the non-pdf files (currently
# this is not available through the make clean)
rm -f siesta*.[^pt]* siesta*.toc
rm -f tbtrans*.[^pt]* tbtrans*.toc
# Create signatures and move files
for f in *.pdf ; do
_sign $f
done
# Go out of the documentation directory...
popd
# Return from the branch release
popd
# Tar the file
# In some future cases will the tag and out name
# be equivalent and we shouldn't delete what we should process!
# Create the archive... (without any .bzr files)
tar -czf $_out.tar.gz $_out
_sign $_out.tar.gz
rm $_out.tar.gz
popd
Docs/siesta.bib 0 → 100644
View file @ 63df7ad5
@article{Kresse1996,
author = {Kresse, G. and Furthm{\"{u}}ller, J.},
doi = {10.1016/0927-0256(96)00008-0},
issn = {09270256},
journal = {Computational Materials Science},
month = {jul},
number = {1},
pages = {15--50},
title = {{Efficiency of ab-initio total energy calculations for metals and semiconductors using a plane-wave basis set}},
url = {http://linkinghub.elsevier.com/retrieve/pii/0927025696000080},
volume = {6},
year = {1996}
}
@article{Bowler2000,
author = {Bowler, D.R and Gillan, M.J},
doi = {10.1016/S0009-2614(00)00750-8},
issn = {00092614},
journal = {Chemical Physics Letters},
month = {jul},
number = {4},
pages = {473--476},
title = {{An efficient and robust technique for achieving self consistency in electronic structure calculations}},
url = {http://linkinghub.elsevier.com/retrieve/pii/S0009261400007508},
volume = {325},
year = {2000}
}
@article{Banerjee2016,
author = {Banerjee, Amartya S. and Suryanarayana, Phanish and Pask, John E.},
doi = {10.1016/j.cplett.2016.01.033},
issn = {00092614},
journal = {Chemical Physics Letters},
month = {mar},
pages = {31--35},
title = {{Periodic Pulay method for robust and efficient convergence acceleration of self-consistent field iterations}},
url = {http://linkinghub.elsevier.com/retrieve/pii/S0009261416000464},
volume = {647},
year = {2016}
}
@article{Brandbyge2002,
author = {Brandbyge, Mads and Mozos, Jos{\'{e}}-Luis and Ordej{\'{o}}n, Pablo and Taylor, Jeremy and Stokbro, Kurt},
doi = {10.1103/PhysRevB.65.165401},
issn = {0163-1829},
journal = {Physical Review B},
month = {mar},
number = {16},
pages = {165401},
title = {{Density-functional method for nonequilibrium electron transport}},
url = {http://link.aps.org/doi/10.1103/PhysRevB.65.165401},
volume = {65},