Skip to content
Snippets Groups Projects
Commit 9dd3c131 authored by Wuttke, Joachim's avatar Wuttke, Joachim
Browse files

rm fragmentary API documentation from Physics Manual 

... which now fully concentrates on theory
parent d47d1c08
Branches
Tags
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Doc/PhysicsManual/BasicRef.tex deleted 100644 → 0
+ 0
− 317
View file @ d47d1c08
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% BornAgain Physics 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
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \part{Reference}\label{PREF}
\chapter{Simulation, Instrument, Histograms}\label{SRefBas}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Simulation classes}\label{SRefSim}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Each BornAgain simulation is run from one of the three
foundational simulation classes:\footnote
{Developer note: They all inherit from a common non-public (pure virtual)
interface class \ttIdx{Simulation}.}
\ttIdx{GISAS\-Simulation},
\ttIdx{OffSpecularSimulation},
\ttIdx{SpecularSimulation}.
%===============================================================================
\subsection{GISAS\-Simulation}
%===============================================================================
Class \ttIdx{GISAS\-Simulation} controls one
grazing-incidence small-angle scattering simulation.
The following six functions from the C$++$ API are sufficient to set up and run a basic
simulation:
\setCpp
\begin{lstlisting}
class GISASSimulation {
GISASSimulation(); // constructor
void setDetectorParameters(...);
void setBeamParameters(...);
void setSample(...);
void runSimulation();
Histogram2D* getIntensityData(...);
};
\end{lstlisting}
\constrHide{GISAS\-Simulation}%
They shall now be explained with full signatures.
Some alternatives will also be shown.
%--------------------------------------------------------------------------------
\begin{figure}[tb]
\begin{center}
\includegraphics[width=0.7\textwidth]{fig/drawing/gisas_spherical_detector.png}
\end{center}
\caption{A spherical detector, with geometric conventions for polar angles~$\alpha$
and azimuthal angles~$\varphi$}
\label{FDetSpher}
\end{figure}
%--------------------------------------------------------------------------------
A two-dimensional detector must be defined through on of the following calls:
\subsubsection{Detector setup}\label{SRefDet}
\begin{lstlisting}
class GISASSimulation {
void setDetectorParameters(
size_t n_phi, double phi_min, double phi_max,
size_t n_alpha, double alpha_min, double alpha_max);
void setDetector(const IDetector2D& detector);
};
\end{lstlisting}
The function \clFct{GISAS\-Simulation}{setDetectorParameters}
defines a \ttIdx{SphericalDetector}
\index{Detector!spherical}%
with \texttt{n\_phi} equidistant azimuthal ($xy$, horizontal, off-specular) bins
\index{Azimuthal angle}%
\index{Horizontal angle}%
\index{Off-specular angle}%
\index{Angle!azimuthal ($=$ horizontal)}%
and \texttt{n\_alpha} equidistant polar ($xz$, vertical, specular) bins (\cref{FDetSpher}).
\index{Polar angle}%
\index{Vertical angle}%
\index{Specular angle}%
\index{Angle!polar ($=$ vertical)}%
The alternate function~\clFct{GISAS\-Simulation}{setDetector}
allows to supply any detector that realizes the interface \ttIdx{IDetector2D}.
Besides \texttt{SphericalDetector}, this can be a \ttIdx{Rectangular\-Detector}.
For details, see the \tuto{141}{rectangular detector tutorial}.
\subsubsection{Beam setup}\label{SRefBeam}
\begin{lstlisting}
class GISASSimulation {
void setBeamParameters(
double wavelength, double alpha_i, double phi_i);
};
\end{lstlisting}
This function\clFctHide{GISAS\-Simulation}{setBeamParameters}
is rather self-explanatory.
The incident radiation wavelength must be given in the same length unit
that is also used in the sample description.
\subsubsection{Sample setup}
\begin{lstlisting}
class GISASSimulation {
GISASSimulation(const MultiLayer& p_sample);
GISASSimulation(const std::shared_ptr<IMultiLayerBuilder> p_sample_builder);
void setSample(const MultiLayer& sample);
void setSampleBuilder(const std::shared_ptr<IMultiLayerBuilder> p_sample_builder);
};
\end{lstlisting}
Besides function \clFct{GISAS\-Simulation}{setSample}, there is an alternate
function \clFct{GISAS\-Simulation}{setSampleBuilder}.
Either function call can be replaced by an extend forms of the constructor
\constr{GISAS\-Simulation}.
Since BornAgain is only concerned with multilayer samples,
the \E{sample} class
\index{Sample (class)|see{\Code{MultiLayer}}}%
is called \ttIdx{MultiLayer},
and each \E{sample builder} must realize the interface \ttIdx{IMulti\-Layer\-Builder}.
\index{Sample builder (interface)|see{\Code{IMultiLayerBuilder}}}%
A sample builder provides a more versatile way to define a sample.
Usage examples can be found in the test cases in \ttIdx{Core/StandardSamples}
and in the Python example \ttIdx{FitSpheresInHexLattice\_builder.py}.
\subsubsection{Execution}
\begin{lstlisting}
class GISASSimulation {
void runSimulation();
};
\end{lstlisting}
\clFctHide{GISAS\-Simulation}{runSimulation}%
Once the simulation is fully set up, it is run once through this command.
Results are stored in a protected class variable.
\subsubsection{Retrieval of result}
\begin{lstlisting}
class GISASSimulation {
Histogram2D* getIntensityData(AxesUnits units_type = AxesUnits::DEFAULT) const;
};
\end{lstlisting}
\clFctHide{GISAS\-Simulation}{getIntensityData}%
This function returns a pointer to a \ttIdx{Histogram2D}
that contains the outcome of the simulation.
% TODO link -> as further discussed in~\Cref{SRefHis2D}.
%===============================================================================
\subsection{Off\-Specular\-Simulation}
%===============================================================================
\MissingSection
%===============================================================================
\subsection{Specular\-Simulation}
%===============================================================================
\MissingSection
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Intensity data}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\MissingSection
\iffalse
%===============================================================================
\subsection{Histogram2D}\label{SRefHis2D}
%===============================================================================
\Work{The following material has been moved here from a Tutorial.
It still needs to be recast in Reference style.}
The \Code{IntensityData} object stores the
simulated or real intensity data together with the axes definition of the detector in BornAgain's internal format.
During the simulation setup
it is created automatically when the user specifies the detector characteristics and is filled with the simulated intensities after the simulation is completed.
\setPy
\begin{lstlisting}
simulation = Simulation()
simulation.setDetectorParameters(10, -5.0*degree, 5.0*degree, 5, 0.0*degree, 1.0*degree)
...
simulation.runSimulation()
intensity = simulation.getIntensityData() @\label{py:UserApi:intensity}@
\end{lstlisting}
The \Code{IntensityData} object retrieved in line~\ref{py:UserApi:intensity} corresponds to
the two dimensional detector pixel array as shown in \cref{fig:UserApi:IntensityData}.
\begin{figure}[ht]
\centering
\includegraphics[clip=, width=120mm]{fig/drawing/UserAPI_IntensityDataLayout.eps}
\caption{The axes layout of IntensityData object.}
\label{fig:UserApi:IntensityData}
\end{figure}
The x-axis and y-axis of the figure correspond to the $\phi_f$ and $\alpha_f$ axes of the detector.
The x-axis is divided into 10 bins,
with low edge of the first bin set to $-5.0\,{\rm deg}$ and upper edge of the last bin set to $+5.0\,{\rm deg}$.
The y-axis is divided into 5 bins,
with low edge of the first bin set to $0.0\,{\rm deg}$ and upper edge of the last bin set to $1.0\,{\rm deg}$.
There are 50 bins in total (they are marked on the plot with indexes from 0 to 49), each bin will contain one intensity value.
During a standard simulation (i.e. no Monte-Carlo integration involved) intensities are calculated for $\phi_f, \alpha_f$ values corresponding to the bin centers, e.g. the intensity stored in bin\#42 will correspond to $\phi_f=3.5\,{\rm deg}, \alpha_f=0.5\,{\rm deg}$.
\vspace*{2mm}
\Note{
The \Code{IntensityData} object is not intended for direct usage from Python API. The idea is
that the API provides the user with the possibility to export the data from BornAgain internal format to the format of his choice as well as import user's data into BornAgain.
For the moment this functionality is limited to a few options explained below.
We encourage users feedback to implement the support of most requested formats.}
\subsubsection{Import/export of intensity data}
For the moment we provide following options:
\begin{itemize}
\item Import/export of \Code{IntensityData} object from/to \Code{numpy} array.
\item Import/export of \Code{IntensityData} object from/to text file.
\end{itemize}
\paragraph{Export to numpy array}
To export intensity data into \Code{numpy} array the method \Code{getArray()} should be used
on \Code{IntensityData} object as shown in line \ref{py:UserApi:getArray} of
following code snippet.
\begin{lstlisting}
intensity = simulation.getIntensityData()
array = intensity.getArray() @\label{py:UserApi:getArray}@
...
pylab.imshow(numpy.rot90(array, 1)) @\label{py:UserApi:imshow}@
pylab.show()
\end{lstlisting}
For the detector settings defined in the previous paragraph the dimensions of the resulting array will be (10,5). By using \Code{numpy} indexes the user can get access to the intensity values, e.g.
\Code{array[0][0]} corresponds to the intensity in bin\#0 of \cref{fig:UserApi:IntensityData},
\Code{array[0][4]} to bin\#4,
\Code{array[1][0]} to bin\#5,
\Code{array[8][2]} to bin\#42,
\Code{array[9][4]} to bin\#49.
To plot this resulting numpy array with \Code{matplotlib} it has to be rotated counter-clockwise
to match \Code{matplotlib} conventions as shown in line~\ref{py:UserApi:imshow}.
%\subsubsection{Direct access to the data}
%User can access to the
%\begin{lstlisting}[language=python, style=eclipseboxed]
%for i in range(0, intensity.getAllocatedSize()):
% print intensity[i]
%\end{lstlisting}
\subsubsection{Importing from numpy array}
To use fitting the user has to load experimental data into BornAgain fitting kernel.
To read experimental data the user has to create
IntensityData object, fill it with the experimental intensity values and pass
this object to the fitting kernel.
First, the user creates empty \Code{IntensityData} as shown
in line~\ref{py:UserApi:IntensityData} of the following code snippet.
\begin{lstlisting}
data = IntensityData() @\label{py:UserApi:IntensityData}@
data.addAxis(FixedBinAxis("phi_f", 10, -5.0*degree, 5.0*degree)) @\label{py:UserApi:phi_f}@
data.addAxis(FixedBinAxis("alpha_f", 5, 0.0*degree, 1.0*degree)) @\label{py:UserApi:alpha_f}@
...
array = numpy.zeros((10, 5)) # fill array with experimental intensities @\label{py:UserApi:create_array}@
...
data.setRawDataVector(array.flatten().tolist()) @\label{py:UserApi:set_raw}@
fitSuite = FitSuite() @\label{py:UserApi:fit_suite}@
fitSuite.addSimulationAndRealData(simulation, data) @\label{py:UserApi:add_real_data}@
\end{lstlisting}
In lines~\ref{py:UserApi:phi_f}, \ref{py:UserApi:alpha_f} two axes with fixed bin sizes
are defined to represent the detector layout as shown in \cref{fig:UserApi:IntensityData}.
The constructor of \Code{FixedBinAxis} object has the following signature
\begin{lstlisting}
FixedBinAxis(title, nbins, min_angle, max_angle)
\end{lstlisting}
The created \Code{IntensityData} object has to be filled with experimental intensities
using \Code{numpy} array prepared by the user (lines ~\ref{py:UserApi:create_array}-~\ref{py:UserApi:set_raw}). In lines \ref{py:UserApi:fit_suite},\ref{py:UserApi:add_real_data} the fitting kernel is created and initialized with \Code{Simulation} object and
\Code{IntensityData} object representing the experimental data.
\subsubsection{Saving intensity data to text file.}
The special class \Code{IntensityDataIOFactory} is intended for saving the intensity data
in different datafile formats. For the moment, it only supports saving the data in specific BornAgain's text files (the file extention \Code{*.int}).
\begin{lstlisting}
intensity = simulation.getIntensityData()
IntensityDataIOFactory.writeIntensityData(intensity, 'file_name.int')
\end{lstlisting}
\subsubsection{Reading intensity data from a text file.}
The same class is also intended for reading intensity data
from files with different formats. For the moment, it only supports reading the data from text files of special BornAgain's format (the file extention \Code{*.int}).
\begin{lstlisting}
intensity = IntensityDataIOFactory.readIntensityData('file_name.int')
\end{lstlisting}
\fi
Doc/PhysicsManual/Particles.tex deleted 100644 → 0
+ 0
− 71
View file @ d47d1c08
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% BornAgain Physics 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
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Embedded particles}\label{SRefParticles}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Particle layout}\label{SRefPLay}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
A \ttIdx{ParticleLayout} is constructed through the following API:
\setCpp
\begin{lstlisting}
class ParticleLayout {
ParticleLayout();
ParticleLayout(const IAbstractParticle& particle);
ParticleLayout(const IAbstractParticle& particle, double abundance);
void addParticle(const IAbstractParticle& particle);
void addParticle(const IAbstractParticle& particle, double abundance);
void addParticle(const IParticle& particle, double abundance, const kvector_t position);
void addParticle(const IParticle& particle, double abundance, const kvector_t position, const IRotation& rotation);
void setInterferenceFunction(const IInterferenceFunction& interference_function);
void setTotalParticleSurfaceDensity(double particle_density);
};
\end{lstlisting}
An \ttIdx{IAbstractParticle} is either an \ttIdx{IParticle} (\cref{SRefIPart})
or a \ttIdx{Particle\-Distri\-bution} (\cref{SRefPDis}).
\index{Particle!IAbstractParticle@\Code{IAbstractParticle}}%
\index{Particle!IParticle@\Code{IParticle}}%
\index{Particle!ParticleDistribution@\Code{ParticleDistribution}}%
In any case, it does not stand for \E{one} particle,
but for one kind of particles.
A \texttt{ParticleLayout} can be loaded with any number of \texttt{IAbstractParticle}s,
using the function \clFct{IAbstractParticle}{addParticle}.
Most often, a \texttt{ParticleLayout} is to be loaded with just one \texttt{IAbstractParticle}.
In this case, \texttt{IAbstractParticle} can be passed as an argument of the
\texttt{ParticleLayout} constructor,
and no call of \texttt{addParticle} is needed;
by default, the \texttt{abundance} is set to~1.
\index{Abundance}%
If there are several \texttt{IAbstractParticle}s,
then the parameter \texttt{abundance} of the function \texttt{addParticle} must be used for
a number that expresses the relative number density of the particle kind.
\Work{Explain \texttt{position} and \ttIdx{IRotation} \ldots}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{IParticle}\label{SRefIPart}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\MissingSection
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Particle distribution}\label{SRefPDis}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\MissingSection
Doc/PhysicsManual/PhysicsManual.tex
+ 2
− 14
View file @ 9dd3c131
...@@ -22,11 +22,6 @@ ...@@ -22,11 +22,6 @@
% makeindex -s nomencl.ist $T.nlo -o $T.nls % makeindex -s nomencl.ist $T.nlo -o $T.nls
% xelatex $T % xelatex $T
%\includeonly{Assemblies}
%\includeonly{ScatteringTheory}
%\includeonly{Introduction,Conventions,OnlineDocs,ScatteringTheory,PolarizedScattering,Multilayers,Assemblies,Domains,Roughness,Experiment}
%\includeonly{FormFactors}
\documentclass[a4paper,11pt,fleqn]{report}\usepackage[final]{graphicx} \documentclass[a4paper,11pt,fleqn]{report}\usepackage[final]{graphicx}
%\documentclass[a4paper,11pt,fleqn,draft]{report}\usepackage[final]{graphicx} %\documentclass[a4paper,11pt,fleqn,draft]{report}\usepackage[final]{graphicx}
%\documentclass[a4paper,11pt,fleqn,draft]{report}\usepackage[draft]{graphicx} %\documentclass[a4paper,11pt,fleqn,draft]{report}\usepackage[draft]{graphicx}
...@@ -48,20 +43,13 @@ ...@@ -48,20 +43,13 @@
\include{Preface} \include{Preface}
\pagemode{\thechapter} \pagemode{\thechapter}
%%%% Part I: Physics
\include{Scattering} \include{Scattering}
\include{Multilayers} \include{Multilayers}
\include{Assemblies} \include{Assemblies}
\include{Roughness} %\include{Roughness}
\include{PolarizedScattering} %\include{PolarizedScattering}
\include{Instrument} \include{Instrument}
%%%% Part II: Reference
\include{ThreeAPIs}
\include{BasicRef}
\include{Sample}
\include{Particles}
%\appendix %\addtocontents{toc}{\protect\setcounter{tocdepth}{1}} %\appendix %\addtocontents{toc}{\protect\setcounter{tocdepth}{1}}
%\include{..} %\include{..}
......
Doc/PhysicsManual/Preface.tex
+ 1
− 11
View file @ 9dd3c131
...@@ -150,16 +150,6 @@ with the software or the documentation.}} ...@@ -150,16 +150,6 @@ with the software or the documentation.}}
\medskip \medskip
\noindent\strut\hspace{.2\TW}This is a \tuto{1}{link to the online docs}. \noindent\strut\hspace{.2\TW}This is a \tuto{1}{link to the online docs}.
\medskip
\setCpp
\begin{lstlisting}[linewidth=.95\TW,xleftmargin=.2\TW]
C++ code, mainly used for API documentation.
\end{lstlisting}
\setPy
\begin{lstlisting}[linewidth=.95\TW,xleftmargin=.2\TW]
Python code.
\end{lstlisting}
\bigskip \bigskip
\noindent
Mathematical notations are explained in the symbol index, page~\pageref{Snomencl}. Mathematical notations are explained in the symbol index, page~\pageref{Snomencl}.
Doc/PhysicsManual/Sample.tex deleted 100644 → 0
+ 0
− 141
View file @ d47d1c08
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% BornAgain Physics 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
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Sample}\label{SRefSam}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Multilayer}\label{SRefMuLay}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Samples in BornAgain are always of type \ttIdx{MultiLayer}.
\setCpp
\begin{lstlisting}
class MultiLayer {
MultiLayer();
void addLayer(const Layer& p_child);
void addLayerWithTopRoughness(const Layer& layer, const LayerRoughness& roughness);
};
\end{lstlisting}
A \texttt{MultiLayer} consists of one or more layers,
numbered from top to bottom as shown in~\cref{Fdefz}.
The function \clFct{MultiLayer}{addLayer} or \clFct{MultiLayer}{addLayerWithTopRoughness}
inserts one \ttIdx{Layer} at the high-index, low-$z$ end.
The \texttt{Layer} API is documented in~\cref{SRefLayer},
the \ttIdx{LayerRoughness} in~\cref{SRefRough}.
The following Python code fragment constructs an absolutely minimal sample:
\setPy
\begin{lstlisting}
sample = MultiLayer()
sample.addLayer(air_layer)
\end{lstlisting}
This sample just consists of an infinite volume of air.
As such, it is completely inert; it causes neither refraction, nor scattering.
However, the air layer can be \E{decorated} with a \ttIdx{ParticleLayout},
which then causes small-angle scattering,
as demostrated in the tutorial \tuto{51}{Cylinders in Born Approximation}.
The following sample consists of two half-infinite layers,
substrate under air:
\setPy
\begin{lstlisting}
sample = MultiLayer()
sample.addLayer(air_layer)
sample.addLayer(substrate_layer)
\end{lstlisting}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Layer}\label{SRefLayer}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
A \ttIdx{Layer} is constructed through the following API:
\setCpp
\begin{lstlisting}
class Layer {
Layer();
Layer(const HomogeneousMaterial& material, double thickness=0);
void setThickness(double thickness);
void setMaterial(const HomogeneousMaterial& material);
void addLayout(const ParticleLayout& decoration);
};
\end{lstlisting}
It is obligatory to set a \E{material} (\cref{SRefMat}).
The \E{thickness} must be nonnegative.
The semi-infinite top and bottom layer must have a \E{pro forma} thickness of~0.
All other layers should have a thickness larger than~0.
The \texttt{Layer} can be \E{decorated} with any number of \ttIdx{ParticleLayout}s.\footnote
{The source code only requires the particle decoration to be of type \ttIdx{ILayout}.
However, since this interface is realized by no other class besides \ttIdx{ParticleLayout},
we here spell out \texttt{ILayout} as \texttt{ParticleLayout}.}
Scattering from different layouts adds incoherently.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Material}\label{SRefMat}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Material classes all inherit from the pure virtual interface class \ttIdx{HomogeneousMaterial}.
Currently, BornAgain only supports homogeneous materials.
They can be either nonmagnetic or magnetic.
A nonmagnetic \ttIdx{HomogeneousMaterial} is created through the API
\setCpp
\begin{lstlisting}
class HomogeneousMaterial {
HomogeneousMaterial(const std::string &name, const complex_t refractive_index);
HomogeneousMaterial(const std::string &name, double refractive_index_delta, double refractive_index_beta);
};
\end{lstlisting}
The second form of the constructor computes the complex refractive index
\index{Refractive index!HomogeneousMaterial@\Code{HomogeneousMaterial}}%
from the two real parameters $\delta$ and~$\beta$ according to~\cref{Endb1}.
Typical usage is:
\setPy
\begin{lstlisting}
m_air = HomogeneousMaterial("Air", 0.0, 0.0)
m_substrate = HomogeneousMaterial("Substrate", 6e-6, 2e-8)
m_particle = HomogeneousMaterial("Particle", 6e-4, 2e-8)
\end{lstlisting}
A \ttIdx{HomogeneousMagneticMaterial} has the \E{magnetic field} (in units of Tesla)
\index{Magnetic field}%
as additional parameter:
\setCpp
\begin{lstlisting}
class HomogeneousMagneticMaterial {
HomogeneousMagneticMaterial(const std::string &name, const complex_t refractive_index, const kvector_t magnetic_field);
HomogeneousMagneticMaterial(const std::string &name, double refractive_index_delta, double refractive_index_beta, const kvector_t magnetic_field);
void setMagneticField(const kvector_t magnetic_field);
}
\end{lstlisting}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Roughness}\label{SRefRough}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\MissingSection
Doc/PhysicsManual/Setup.tex
+ 1
− 2
View file @ 9dd3c131
...@@ -408,8 +408,7 @@ ...@@ -408,8 +408,7 @@
urlcolor={blue!80!black}, urlcolor={blue!80!black},
pdftitle={BornAgain Physics Manual} % seems to be ignored pdftitle={BornAgain Physics Manual} % seems to be ignored
} }
\def\tutoNomar#1#2{\href{http://bornagainproject.org/node/#1}{#2}} \def\tuto#1#2{\href{http://bornagainproject.org/node/#1}{#2}}
\def\tuto#1#2{\tutoNomar{#1}{#2}\marginpar{\marginSymbolMedium{fig/icons/Weblink.png}{LINK}}}
\ifdraft{\usepackage[right]{showlabels}}{} \ifdraft{\usepackage[right]{showlabels}}{}
\usepackage{cleveref} \usepackage{cleveref}
......
Doc/PhysicsManual/ThreeAPIs.tex deleted 100644 → 0
+ 0
− 252
View file @ d47d1c08
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% BornAgain Physics Manual
%%
%% homepage: http://www.bornagainproject.org
%%
%% copyright: Forschungszentrum Jülich GmbH 2016
%%
%% license: Creative Commons CC-BY-SA
%%
%% authors: Scientific Computing Group at MLZ Garching
%% M. Ganeva, G. Pospelov, W. Van Herck, J. Wuttke
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\part{Reference}\label{PREF}
\chapter{Introduction: The three interfaces of \BornAgain} \label{sec:API3}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Architectural overview}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The overall architecture of \BornAgain\ is outlined in \cref{Farch1}.
The core of \BornAgain\
\index{Core|see {\Code{libBornAgainCore}}}
comprises functionality to construct arbitrary hierarchical sample models,
to setup instrument models,
and to compute the expected detector image for any given sample and instrument model.
Furthermore \BornAgain\ comes with various minimizers that optimize model parameters
to fit the simulated detector image to a given experimental image.
All this functionality is implemented in a library, \Code{libBornAgainCore}.
\begin{figure}[tbh]
\begin{center}
\includegraphics[width=0.7\textwidth]{fig/drawing/architecture1.ps}
\end{center}
\caption{Overall architecture of \BornAgain.
\index{Architecture!applications and libraries}%
Applications are shown as oval fields, libraries as rectangles.
Black arrows indicate ``depends on''.
Green fields designate software that is part of \BornAgain.
Gray fields are external dependences
(only two external libraries are explicitly shown;
several more are listed in the online compilation instructions).
Blue fields indicate stand-alone applications that use \BornAgain's
two Application Programming Interfaces (the C$++$ API and the Python API).
\index{C++!using BornAgain from}
\index{Python!using BornAgain from}
\index{Application Programming Interface}
While such applications are to be written by users,
some examples come with the \BornAgain\ source distribution,
and are explained in the following Manual chapters.
It is also possible to export a simulation setup from GUI as Python code.
The binding of C++ to Python is highly simplified here.
For a more accurate picture, see \Cref{FarchPy}.}
\label{Farch1}
\end{figure}
\index{libBornAgainCore@\Code{libBornAgainCore}}
This library, in turn, depends on a number of other libraries.
One of these, the minimizer wrapper \Code{libBornAgainFit}
\index{libBornAgainFit@\Code{libBornAgainFit}}
\index{Minimizers|see \Code{libBornAgainFit}}
has been written specifically for use in \BornAgain,
and for the time being is only distributed as part of \BornAgain,
though in the future it may find applications in other contexts.
The other library dependences of \Code{libBornAgainCore}
are multi-purpose libraries that are easily available as open-source packages.
\index{Dependences!libraries}
The library \Code{libBornAgainCore} can be used in three different ways:
From its graphical user interface (GUI), or
from user-written stand-alone applications in the programming languages C$++$ or Python.
These different approaches are briefly outlined below.
The Python interface is then described at length in the next chapters.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Using \BornAgain\ from its Graphical User Interface}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{Graphical User Interface|(}
\index{bornagain@\Code{bornagain}|see {Graphical User Interface}}
\index{Executable!bornagain@\Code{bornagain}|see {Graphical User Interface}}
\index{Binary|see {Executable}}
%\index{Project name!BornAgain@\BornAgain}
The project \BornAgain\ comes with a stand-alone application called \Code{bornagain}
that provides a Graphical User Interface (GUI).
Note that we distinguish between the GUI executable \Code{bornagain},
the underlying library \Code{libBornAgainCore}, and the project \BornAgain\ at large.
The GUI allows users to quickly setup a simulation, to visualize simulated
detector images, to compare with experimental images, and to run fits.
It provides comfortable access to much, but not all the functionality
of \Code{libBornAgainCore}.
Depending on application fields,
users may sooner or later reach the limits of current GUI support.
Other users may have repetitive tasks that are cumbersome under a GUI.
In such cases, users can export their sample and instrument models from
the GUI as a Python script,
and continue work by directly editing the Python code.
\index{Export!Python from GUI}
See the online documentation for
\tuto{18}{detailed instructions} how to use the GUI.
\index{Graphical User Interface|)}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Using \BornAgain\ from Python}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{Python!using BornAgain from|(}
\index{Application Programming Interface!Python|(}
\BornAgain\ simulations and fits can be set up and run from Python programs
or from a Python command-line interpreter like \Code{IPython}.
\index{IPython}
\index{Command line!Python}
A short program in an interpreted language like Python is customarily called
\index{Script!Python}
\index{Python!script}
a \E{script},
and therefore in the following we will talk about \E{Python scripts}.
Of course this does not preclude the possibility that such scripts evolve into
complex programs, modules, or packages.
And anything we say about scripts also applies to usage of \BornAgain\ in an
interactive Python session.%
\index{Interactive Python session}%
\index{Python!interactive use}%
Usage of \BornAgain\ in a Python script should start with the command
\setPy
\begin{lstlisting}
import bornagain as ba @\label{import_as}\index{Import!\BornAgain\ to Python|(}@
\end{lstlisting}
This then allows calls to \BornAgain\ in commands like
\pagebreak[2]
\setPyNum
\begin{lstlisting}
air = ba.HomogeneousMaterial("Air", 0.0, 0.0) @\label{constructor_beg}@
air_layer = ba.Layer(air)
sample = ba.MultiLayer() @\label{constructor_end}@
sample.addLayer(air_layer) @\label{class_func_call}@
\end{lstlisting}
The function calls in lines \ref{constructor_beg}--\ref{constructor_end}
return new \E{objects}.
\index{Object!constructor}
These objects are instances of \E{classes} defined in \BornAgain.
\index{Class!Instantiation}
In the language of object-oriented programming,
a Function that returns a new instance of a class is called a \E{constructor}.
\index{Constructor}
In Python, as in C++, constructor names coincide with class names;
so the constructor function \Code{Layer(material)} will return an
object of class type \Code{Layer}.
\begin{figure}[tb]
\begin{center}
\includegraphics[width=0.72\textwidth]{fig/drawing/architecturePy.ps}
\end{center}
\caption{Relation between the BornAgain C++ libraries and the Python layer.
\index{Architecture!Python binding}%
Python code is indicated by \textsl{slanted font}.
Colors as in \Cref{Farch1}.
Bold arrows indicate ``depends on'' for code that is automatically generated
by the software tool Swig.%
\index{Swig}%
\index{Python!Swig}%
}
\label{FarchPy}
\end{figure}
To prevent accidental use of class or constructor names,
they are encapsulated in a \E{namespace}
\index{Namespace}
called \Code{bornagain}.
The \Code{import} command in the above code line~\ref{import_as}
makes this namespace available under the shortcut \Code{ba}.
\index{Import!\BornAgain\ to Python|)}
Note, however, that not all calls to \BornAgain\ require
(and can be recognized by) the prefix \Code{ba}.
The function call \Code{addLayer} in line~\ref{class_func_call}
is defined inside the \BornAgain\ class \Code{MultiLayer}.
The programmer is supposed to know that \Code{sample} is an instance of
class \Code{MultiLayer}, which is part of \BornAgain.
Therefore, there is no need (and no way) to adorn function calls like \Code{addLayer}
with the namespace label \Code{ba}.
The entirety of classes and functions provided by \BornAgain\
and exposed to Python forms the \E{BornAgain Python API}.
An API (Application Programming Interface)
\index{Application Programming Interface!Python}
is a kind of protocol that tells a programmer how to use a library.
In this perspective, the research scientist
who uses Python to set up simulations or fits
is seen as a \E{programmer} who writes an application program.
This notwithstanding, he is still a \E{user}
of the BornAgain Python library.
The relation of this library to the underlying C++ library is explained
in \Cref{FarchPy}.
The classes and functions in the BornAgain Python library have the same
names, argument lists, and return values
as their counterparts in the C++ library.
Therefore, we provide references only for the latter,
which has the advantage that it is more explicit about the data types
of function arguments and return values.
\index{Application Programming Interface!Python|)}
\index{Python!using BornAgain from|)}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Using \BornAgain\ from C++}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{C++!using BornAgain from|(}
\index{Application Programming Interface!C++|(}
Alternatively, BornAgain can also be used from the programs written
in the language~C++.
Since BornAgain itself is written in C++,
\index{C++!BornAgain written in}%
the BornAgain C++ API natively consists of
all classes and functions in \Code{libBornAgainCore} and \Code{libBornAgainFit},
\index{libBornAgainCore@\Code{libBornAgainCore}}%
\index{libBornAgainFit@\Code{libBornAgainFit}}%
including internal ones that are not exposed to Python.
It empowers application programmers to use BornAgain
in ways we cannot foresee.
Normal GISAS users, however, will find that their simulation and fit tasks
are well served by the Python API,
that edit-and-rerun cycles are faster with Python than with a compiled language,
and that there is no need to use BornAgain from C++.
Therefore, we provide only one code example:
\url{Examples/cpp/CylindersAndPrisms} in the source distribution.
The C++ API is fully documented
in the automatically generated Doxygen reference at
\url{http://apps.jcns.fz-juelich.de/doxy/BornAgain/index.html}.
\index{Doxygen!API reference}
\index{C++!Doxygen API reference}
The remaining chapters of this Manual
provide a selective, annotated reference,
especially of functions related to the physical modelling.
It is organized top-down: We start with top-level classes like
\texttt{GISAS\-Simulation};
then we explain the classes needed to set up a meaningful simulation.
For an alphabetic lookup of classes and functions,
see the general Index at the end of this Manual.
For classes and functions not explained here,
see the Doxygen documentation.
\index{Application Programming Interface!C++|)}
\index{C++!using BornAgain from|)}
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment