%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%   BornAgain User Manual
%%
%%   homepage:   http://www.bornagainproject.org
%%
%%   copyright:  Forschungszentrum Jülich GmbH 2015
%%
%%   license:    Creative Commons CC-BY-SA
%%
%%   authors:    Scientific Computing Group at MLZ Garching
%%               C. Durniak, M. Ganeva, G. Pospelov, W. Van Herck, J. Wuttke
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\cleardoublepage
\ichapter{Preface}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\isection{About BornAgain}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

BornAgain is a software package
to simulate and fit
reflectometry, off-specular scattering,
and grazing-incidence small-angle scattering (GISAS)
of X-rays and neutrons.
It provides a generic framework
for modeling multilayer samples with smooth or
rough interfaces and with various types of embedded nanoparticles.
The name, BornAgain,
alludes to the central role of the distorted-wave Born
approximation (DWBA) in the physical description of the
scattering process.
\index{Distorted-wave Born approximation}

BornAgain is maintained
by the Scientific Computing Group
of the J\"ulich Centre for Neutron Science (JCNS)
at Heinz Maier-Leibnitz Zentrum (MLZ) Garching, Germany.
It free and open source software.
The source code is released under the GNU General Public License (GPL, version 3 or higher),
the documentation under the Creative Commons license CC-BY-SA.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\isection{This manual vs other documentation}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This Physics Manual explains some of the theory behind BornAgain.
It is restricted to topics that are not covered by other components
of the BornAgain documentation.
These include:
\index{Publications}
\begin{itemize}
\item Our 2020 article in J.~Appl.\ Cryst. \cite{PoVB20}
that gives a broad overview over BornAgain.
The implemented physics is summarized in Sect.~5.
\item \index{Web site}
The web site \url{https://www.bornagainproject.org},
which includes instructions how to download and install BornAgain,
and extensive tutorials on setting up physical models.
\item \index{Application Programming Interface}
The complete documentation of the Application Programming Interface (API),
which can be generated by running \index{Doxygen}
the open-source tool \emph{Doxygen} over the source code.
\item Further technical documents,
available from the \emph{Documents} tab on the
\href{https://www.bornagainproject.org/download#Documents}{download page}.
So far, there exists one such document, namely the
\index{Form factor!catalog}
\href{http://apps.jcns.fz-juelich.de/src/BornAgain/FFCatalog.pdf}{Form factor catalog}.
\end{itemize}
This Physics Manual is work in progress.
In future editions, it may grow as we elaborate details or add new chapters,
but it may also shrink as we move contents to journal articles or other documents.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\isection{Citation}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\index{Citation}%
The canonical reference for BornAgain is the journal article \cite{PoVB20}
\begin{quote}
Gennady Pospelov, Walter Van Herck, Jan Burle, Juan M. Carmona Loaiza,
Céline Durniak, Jonathan M. Fisher, Marina Ganeva, Dmitry Yurov and
Joachim Wuttke:\\
BornAgain: software for simulating and fitting
grazing-incidence small-angle scattering\\
\href{https://doi.org/10.1107/S1600576719016789}{J. Appl. Cryst. 53, 262–276 (2020)}
\end{quote}
Use of the software should additionally be documented by citing a specific version thereof:
\begin{quote}
BornAgain --- Software for simulating and fitting
X-ray and neutron small-angle scattering at grazing incidence,
version $\langle$\texttt{version}$\rangle$ ($\langle$\texttt{release date}$\rangle$),\\
\url{http://www.bornagainproject.org}
\end{quote}
Citation of the present Physics Manual is only necessary
when referring to specific information.
As this document is subject to frequent and substantial change,
it is important to refer to a specific edition by indicating the release date
printed on the title page:
\begin{quote}
\authors:\\
BornAgain Physics Manual ($\langle$\texttt{release date}$\rangle$),\\
\url{http://www.bornagainproject.org}
\end{quote}
Old editions can be retrieved from the BornAgain source repository.

The initial design of BornAgain and much of the implemented physics owe much
to the widely used program IsGISAXS
\index{IsGISAXS@\IsGISAXS}%
\index{Lazzari, R\'emi}%
by R\'emi Lazzari \cite{Laz06}.
Depending on how BornAgain is used in scientific work,
it may be appropriate to also cite the pioneering papers
by Lazzari \etal\ \cite{Laz02,ReLL09}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\isection{Typographic Conventions}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

We use the following colored boxes to highlight
certain information:

\def\demobox#1{\noindent\strut\hspace{.2\TW}\begin{minipage}{.75\textwidth}#1
\end{minipage}\hfill\strut}

\medskip
\demobox{\Warn{\indent Such a box contains
a \textbf{warning} about potential problems
with the software or the documentation.}}

\medskip
\demobox{\Work{\indent This road sign in the margin indicates \textbf{work in progress}.}}

\medskip
\demobox{\Emph{\indent A green box highlights
  an \textbf{important fact}, for instance an equation
  that is central in
  the further development of the theory.}}

\medskip
\demobox{\Note{\indent
  An \textbf{implementation note} explains
  how the theory exposed in this manual is actually used in \BornAgain.}}

\medskip
\noindent\strut\hspace{.2\TW}This is a \tuto{1}{link to the online docs}.

\bigskip
\noindent
Mathematical notations are explained in the symbol index, page~\pageref{Snomencl}.
