Merge pull request #1210 from fsoubelet/master

IBS Table Fix and Code Source Comments

Changes.md

@@ -1,3 +1,12 @@
+MAD-X release 5.09.02 (2024.??.??)
+
+* IBS:
+  * [PR 1210](https://github.com/MethodicalAcceleratorDesign/MAD-X/pull/1210) Fixes in IBS command behaviour (F. Soubelet)
+    * Fixed an issue where the IBS table would only be created if the `FILE="STRING"` part of the command was provided, instead of always as documented.
+    * Added an export of the `ibs.coulog` and `ibs.const` variables after calling the IBS command (see user guide).
+    * Documented the IBS code.
+
+
 MAD-X release 5.09.01 (2023.12.04)
 
 *  PTC:

doc/latexuguide/ibs.tex

@@ -20,21 +20,17 @@ \chapter{Intra-Beam Scattering}
 to the case of nonzero vertical dispersion.  
 
 The present implementation of the IBS module in \madx is described in a
-forthcoming note  \cite{antoniou-zimmermann2012}.
+forthcoming note \cite{antoniou-zimmermann2012}.
 
 
 The syntax of the \texttt{IBS} command is:
 \madbox{
-%IBS, TOLERANCE=real, STEPS=integer, FILE=string;
 IBS, FILE=string;
 }
 
 The \texttt{IBS} command has one attribute:
 \begin{madlist}
-%  \ttitem{TOLERANCE} ??? (Default:~1.e-7) % declared, never used
-%  \ttitem{STEPS} number of steps ??? (Default:~50) % declared, never used
-  \ttitem{FILE} outputs the resulting "ibs" table to
-  the named file. (Default:~"ibs")
+  \ttitem{FILE} outputs the resulting "ibs" table to the named file. (Default:~"ibs")
 \end{madlist}
 
 The Bjorken-Mtingwa formalism takes into account the variation of the
@@ -47,7 +43,7 @@ \chapter{Intra-Beam Scattering}
 \texttt{IBS} commands leads to \texttt{IBS} using wrong beam parameters,
 even if the \texttt{BEAM} command is reiterated.
 
-The \texttt{IBS} module does not include a consistent treatment of
+\textbf{Warning:} The \texttt{IBS} module does not include a consistent treatment of
 linear betatron coupling.   
 
 The intra-beam scattering growth times are given by:
@@ -65,7 +61,7 @@ \chapter{Intra-Beam Scattering}
 If the \texttt{CENTRE=true} option of \texttt{TWISS} was specified,
 the optical functions are calculated by \texttt{TWISS} at the center of 
 each element and \texttt{IBS} uses these values for the element. 
-If by default \texttt{TWISS} calculated the optical functions at the end
+If (by default) \texttt{TWISS} calculated the optical functions at the end
 of each element, \texttt{IBS} calculates the values at the center of
 each element by performing a linear interpolation between the end values
 for the previous element and the end values for the current element.
@@ -129,30 +125,33 @@ \chapter{Intra-Beam Scattering}
 
 \textbf{Resulting Table and File:} \\
 The \texttt{IBS} command produces a table "ibs" containing the following
-data for 
-each element of the machine: element name, position, optical functions
+data for each element of the machine: element name, position, optical functions
 (beta, alfa, dispersion and derivative) in both transverse planes, as
 well as the particular variables \texttt{DELS}, the length difference in
-meters between consecutive elements, and \texttt{TXI, TYI} and
-\texttt{TLI}, the IBS growth times in the two transverse and
-longitudinal planes.  
+meters between consecutive elements. The table also containts the \texttt{TXI, TYI}
+and \texttt{TLI} variables, values close to the IBS growth times at the element in
+the two transverse and longitudinal planes. Exactly, these variables correspond to
+the result of Eq (8) in~\cite{antoniou-zimmermann2012} without including the common
+constant term (the first fraction).
 
 This table can be accessed through the usual mechanisms. If the
 attribute \texttt{FILE="file\_name"} is also given, \madx writes the
 table to the named file.  
 
 
-
 \textbf{Features:} \\
 The average growth rates in [sec] are defined as variables called
 \texttt{ibs.tx}, \texttt{ibs.ty}, \texttt{ibs.tl} for the horizontal,
 vertical and longitudinal growth times respectively. They are directly
 accessible as variables after the \texttt{IBS} command, e.g.
 \madxmp{
 IBS; \\ 
-Tx = ibs.tx;}   
-defines a variable Tx which is the average horizontal growth rate in seconds. 
+Tx = ibs.tx;}
+defines a variable Tx which is the average horizontal growth rate in seconds.
 
+Additionally, the Coulomb logarithm as well as the aforementioned common
+constant of Eq (8) in~\cite{antoniou-zimmermann2012} are also exported as
+the \texttt{ibs.coulog} and \texttt{ibs.const} variables.
 
 
 \textbf{Examples:} \\