Gemini AI run to attempt sync of comp->tex doc snippets, McXtrace

willend · willend · commit 7a10fc3da46e · 2025-06-25T22:45:34.000+02:00
diff --git a/doc/manuals/mcxtrace/misc/Air.tex b/doc/manuals/mcxtrace/misc/Air.tex
@@ -0,0 +1,10 @@
+\section{Air: A component simulating atmospheric air}
+\label{s:air}
+\index{Misc!Air}
+\mcdoccomp{misc/Air.parms}
+
+The component \textbf{Air} simulates the scattering of X-rays from atmospheric air. The air is assumed to be a dry mixture of nitrogen, oxygen, and argon. The component can be used to estimate the background signal from air scattering in an experiment.
+
+The air volume can be defined as a box, a cylinder, or a sphere. The dimensions of the air volume are specified by the \textit{xwidth}, \textit{yheight}, \textit{zdepth}, and \textit{radius} parameters. The pressure and temperature of the air can be specified by the \textit{pressure} and \textit{temperature} parameters, respectively.
+
+The component also allows for the use of a target window, which is defined by the \textit{target_x}, \textit{target_y}, \textit{target_z}, \textit{focus_xw}, \textit{focus_yh}, \textit{focus_aw}, \textit{focus_ah}, and \textit{focus_r} parameters. The \textit{frac} parameter controls the fraction of rays to be scattered from the air.
diff --git a/doc/manuals/mcxtrace/misc/File.tex b/doc/manuals/mcxtrace/misc/File.tex
@@ -0,0 +1,11 @@
+
+
+\section{File: A component for generating input files}
+\label{s:file}
+\index{Misc!File}
+\mcdoccomp{misc/File.parms}
+
+The component \textbf{File} allows for the generation of input files from METADATA blocks. The component reads the content of a METADATA block and writes it to a file.
+
+The component is defined by the \textit{filename} and \textit{metadatakey} parameters. The \textit{filename} parameter specifies the name of the output file, and the \textit{metadatakey} parameter specifies the key of the METADATA block to be read. The \textit{keep} parameter can be used to keep the generated file after the simulation is finished.
+
diff --git a/doc/manuals/mcxtrace/misc/Focus.tex b/doc/manuals/mcxtrace/misc/Focus.tex
@@ -0,0 +1,10 @@
+
+\section{Focus: A component for focusing X-rays}
+\label{s:focus}
+\index{Misc!Focus}
+\mcdoccomp{misc/Focus.parms}
+
+The component \textbf{Focus} turns a photon into a Huygens wavelet. The component changes the direction of the photon to a random direction towards a specified target area. This component is intended to be used in coherent simulations, preferably with the SPLIT keyword.
+
+The target area is defined by the \textit{dist}, \textit{focus_xw}, \textit{focus_yh}, \textit{focus_x0}, and \textit{focus_y0} parameters. The \textit{focus_absolute} parameter can be used to specify whether the target coordinates are absolute or relative to the component's position.
+
diff --git a/doc/manuals/mcxtrace/misc/MCPL_input.tex b/doc/manuals/mcxtrace/misc/MCPL_input.tex
@@ -0,0 +1,10 @@
+
+\section{MCPL_input: An interface for MCPL}
+\label{s:mcpl_input}
+\index{Misc!MCPL_input}
+\mcdoccomp{misc/MCPL_input.parms}
+
+The component \textbf{MCPL_input} is a source-like component that reads photon state parameters from a binary mcpl-file. MCPL is a format for sharing events between different Monte Carlo simulation codes.
+
+The component is defined by the \textit{filename} parameter, which specifies the name of the mcpl-file to be read. The component can also be used to smear the energy, position, and direction of the photons by using the \textit{E_smear}, \textit{pos_smear}, and \textit{dir_smear} parameters, respectively. The \textit{repeat_count} parameter can be used to repeat the events in the mcpl-file multiple times.
+
diff --git a/doc/manuals/mcxtrace/misc/MCPL_output.tex b/doc/manuals/mcxtrace/misc/MCPL_output.tex
@@ -0,0 +1,10 @@
+
+\section{MCPL_output: An interface for MCPL}
+\label{s:mcpl_output}
+\index{Misc!MCPL_output}
+\mcdoccomp{misc/MCPL_output.parms}
+
+The component \textbf{MCPL_output} is a detector-like component that writes photon state parameters into an mcpl-format binary file. MCPL is a format for sharing events between different Monte Carlo simulation codes.
+
+The component is defined by the \textit{filename} parameter, which specifies the name of the output file. The component allows for several flags to tweak the output file. The \textit{polarisationuse} parameter can be used to store the polarisation vector of the photons. The \textit{doubleprec} parameter can be used to store the data as 32-bit floating points. The \textit{userflag} and \textit{userflagcomment} parameters can be used to attach extra information to each photon.
+
diff --git a/doc/manuals/mcxtrace/misc/Shadow_input.tex b/doc/manuals/mcxtrace/misc/Shadow_input.tex
@@ -3,4 +3,6 @@ \section{Shadow\_input: Reading input from Shadow}
 \label{s:shadow-input}
 \mcdoccomp{misc/Shadow_input.parms}
 
-Documentation pending
+The component \textbf{Shadow_input} is a source-like component that reads x-ray state parameters from a SHADOW x-ray event file. This component can be used to interface McXtrace components or simulations into SHADOW.
+
+The component is defined by the \textit{file} parameter, which specifies the name of the SHADOW file to be read. The \textit{bufsize} parameter can be used to specify the size of the input buffer, and the \textit{repeat_count} parameter can be used to repeat each x-ray read multiple times.
diff --git a/doc/manuals/mcxtrace/misc/Shadow_output.tex b/doc/manuals/mcxtrace/misc/Shadow_output.tex
@@ -3,4 +3,6 @@ \section{Shadow\_output: Saving the photon rays for use with SHADOW}
 \index{Sources!Virtual source}
 \mcdoccomp{misc/Shadow_output.parms}
 
-Documentation pending.
+The component \textbf{Shadow_output} is a detector-like component that writes x-ray state parameters to a SHADOW x-ray event file. This component can be used to interface McXtrace components or simulations into SHADOW.
+
+The component is defined by the \textit{file} parameter, which specifies the name of the output file. The \textit{bufsize} parameter can be used to specify the size of the output buffer, and the \textit{progress} parameter can be used to output dots as a progress indicator.
diff --git a/doc/manuals/mcxtrace/misc/Shape.tex b/doc/manuals/mcxtrace/misc/Shape.tex
@@ -0,0 +1,11 @@
+
+
+\section{Shape: A geometric shape for display purposes}
+\label{s:shape}
+\index{Misc!Shape}
+\mcdoccomp{misc/Shape.parms}
+
+The component \textbf{Shape} is an inactive geometrical shape for drawing purposes only. It does not propagate X-rays, nor interact with them.
+
+The shape can be a cylinder, a sphere, a box, or any other shape defined by an OFF file. The dimensions of the shape are specified by the \textit{radius}, \textit{xwidth}, \textit{yheight}, \textit{zdepth}, and \textit{thickness} parameters. The \textit{geometry} parameter can be used to specify the name of an OFF file for complex geometries.
+
diff --git a/doc/manuals/mcxtrace/optics/Beamstop.tex b/doc/manuals/mcxtrace/optics/Beamstop.tex
@@ -16,9 +16,7 @@ \section{Beamstop: A photon absorbing area}
 Further, the holder of the beamstop is not simulated.
 
 \textbf{Beamstop} can be either circular or rectangular.
-The input parameters of \textbf{Beamstop} are either height and width \textit{(xwidth, yheight)} or the four coordinates,\textit{(xmin, xmax, ymin, ymax)}
-defining the opening of a rectangle, or the \textit{radius} of
-a circle, depending on which parameters are specified.
+The input parameters of \textbf{Beamstop} can be either circular or rectangular. If the \textit{radius} is specified, the beamstop is circular. Otherwise, it is rectangular. The rectangular geometry can be defined by either the \textit{xwidth} and \textit{yheight} parameters, which define the width and height of the beamstop, or by the \textit{xmin}, \textit{xmax}, \textit{ymin}, and \textit{ymax} parameters, which define the absolute limits of the beamstop. If both sets of parameters are specified, \textit{xwidth} and \textit{yheight} take precedence.
 
 If the "direct beam" (e.g. after a monochromator or sample) should not be
 simulated, it is possible to emulate an ideal beamstop 
diff --git a/doc/manuals/mcxtrace/optics/Capillary.tex b/doc/manuals/mcxtrace/optics/Capillary.tex
@@ -0,0 +1,12 @@
+
+\section{Capillary: A capillary tube}
+\label{s:capillary}
+\index{Optics!Capillary}
+\mcdoccomp{optics/Capillary.parms}
+
+The component \textbf{Capillary} models a capillary tube that allows for multiple reflections along its inner surface. The capillary is a hollow cylinder with a given \textit{radius} and \textit{length}.
+
+The inner surface of the capillary can be coated with a material to enhance its reflectivity. The optical properties of the coating are defined by the \textit{coating} parameter, which should be the name of a file containing the material's complex refractive index data (f1 and f2). Alternatively, a pre-calculated reflectivity table can be provided by setting the \textit{rtable} parameter to a non-zero value. In this case, the \textit{coating} file should contain a 2D matrix of reflectivities as a function of energy and incident angle. If no coating is specified, a constant reflectivity can be set using the \textit{R0} parameter.
+
+The component also models surface waviness, which can be introduced using the \textit{waviness} parameter. This parameter defines the maximum angular deviation of the surface normal from its ideal orientation. The waviness can be either longitudinal (along the capillary axis) or isotropic, as determined by the \textit{longw} parameter.
+
diff --git a/doc/manuals/mcxtrace/optics/Chopper_simple.tex b/doc/manuals/mcxtrace/optics/Chopper_simple.tex
@@ -1,19 +1,17 @@
-\section{Chopper\_simple: An ideal chopper}
+\section{Chopper_simple: An ideal chopper}
 \index{Optics!lens}
 \mcdoccomp{optics/Chopper_simple.parms}
-\texttt{Chopper\_simple} is an idelized version of a chopper with a rectangular chopper opening which may open
+\texttt{Chopper_simple} is an idelized version of a chopper with a rectangular chopper opening which may open
 instantly and has no side-scattering etc.
 
+The timing of the chopper opening can be randomized by using the \textit{tjit} parameter, which introduces a timing jitter to the opening window.
+
 It models the chopper with a blocking infinitely thin aperture which becomes transparent
 in the time interval $t\in\left[\mathit{t0},\mathit{t0}+\tau\right]$.
 This is an idelized version of a chopper where the chopper opening is rectangular which may open
-instantly (if \textit{t\_rise}$=0$, the default). For nonzero rise time the aperture simply becomes gradually less opaque
-for $t\in\left[\mathit{t0}-\textit{t\_rise},\mathit{t0}\right]$.
+instantly (if \textit{t_rise}$=0$, the default). For nonzero rise time the aperture simply becomes gradually less opaque
+for $t\in\left[\mathit{t0}-\textit{t_rise},\mathit{t0}\right]$.
 
 For correct normalization of intesity a chopper period, \textit{T}, must also be set.
 
-\textit{is\_first} is useful when using \textbf{Chopper\_simple} with continous sources who inherently have no time-dependence. Thus the emission time of the photon
-ray is arbitrary, and the chopper defines the temporal signature of the beam,
-i.e. it simply sets the time-parameter of the photon ray randomly in the
-opening window of the chopper. Naturally this should only be used for the \emph{first} chopper
-element in a simulation.
+\textit{is_first} is useful when using \textbf{Chopper_simple} with continous sources who inherently have no time-dependence. When \textit{is_first} is set to 1, the chopper defines the temporal signature of the beam by setting the time-parameter of the photon ray randomly in the opening window of the chopper. This should only be used for the \emph{first} chopper element in a simulation.
diff --git a/doc/manuals/mcxtrace/optics/Collimator_linear.tex b/doc/manuals/mcxtrace/optics/Collimator_linear.tex
@@ -0,0 +1,12 @@
+
+\section{Collimator_linear: A simple analytical Soller collimator}
+\label{s:collimator_linear}
+\index{Optics!Collimator_linear}
+\mcdoccomp{optics/Collimator_linear.parms}
+
+The component \textbf{Collimator_linear} models a simple analytical Soller collimator with a rectangular opening. The collimator is defined by its \textit{length} and the dimensions of its input and output slits. The slits can be defined by either their \textit{xwidth} and \textit{yheight} or by their absolute limits in x and y (\textit{xmin}, \textit{xmax}, \textit{ymin}, \textit{ymax}).
+
+The collimator's divergence is specified by the \textit{divergence} and \textit{divergenceV} parameters, which define the horizontal and vertical angular acceptance of the collimator, respectively. The transmission of the collimator is controlled by the \textit{transmission} parameter, which is a value between 0 and 1.
+
+The transmission function of the collimator is an average and does not take into account the actual trajectory of the photon. If the divergence is set to zero, the collimator acts as a simple double slit.
+
diff --git a/doc/manuals/mcxtrace/optics/Grating_reflect.tex b/doc/manuals/mcxtrace/optics/Grating_reflect.tex
@@ -0,0 +1,12 @@
+
+\section{Grating_reflect: A reflective grating}
+\label{s:grating_reflect}
+\index{Optics!Grating_reflect}
+\mcdoccomp{optics/Grating_reflect.parms}
+
+The component \textbf{Grating_reflect} models a reflective grating that diffracts incident photons. The grating is located in the XZ-plane and is defined by its \textit{xwidth} and \textit{zdepth}.
+
+The grating has a specified number of lines per millimeter, which is controlled by the \textit{rho_l} parameter. The width of the spacing between the lines and the width of the slits can be specified by the \textit{b} and \textit{d} parameters, respectively. The total number of slits can be specified by the \textit{N} parameter.
+
+The component simulates diffraction by randomly selecting a diffraction angle from a uniform distribution of width \textit{d_phi}. The center of this distribution can be shifted to a specific diffraction order by using the \textit{order} parameter, or to a specific angle by using the \textit{phi0} parameter. The reflectivity of the grating is controlled by the \textit{R0} parameter.
+
diff --git a/doc/manuals/mcxtrace/optics/Grating_trans.tex b/doc/manuals/mcxtrace/optics/Grating_trans.tex
@@ -0,0 +1,12 @@
+
+\section{Grating_trans: A transmission grating}
+\label{s:grating_trans}
+\index{Optics!Grating_trans}
+\mcdoccomp{optics/Grating_trans.parms}
+
+The component \textbf{Grating_trans} models a 1D rectangular transmission grating. The grating is defined by its \textit{xwidth}, \textit{yheight}, and the \textit{period} of its grooves. The \textit{gamma} parameter controls the duty cycle of the grating, which is the ratio between the groove width and the period.
+
+The grating is made of a specific material, which is defined by the \textit{material} parameter. The thickness of the grating's substrate can be specified by the \textit{sdepth} parameter, and the material of the substrate can be specified by the \textit{substrate} parameter. The component simulates diffraction up to a specified \textit{max_order}.
+
+The component also allows for the use of a fixed delta for the refractive index, which can be useful for debugging purposes. This is controlled by the \textit{fixed_delta} parameter.
+
diff --git a/doc/manuals/mcxtrace/sources/Bending_magnet.tex b/doc/manuals/mcxtrace/sources/Bending_magnet.tex
@@ -0,0 +1,12 @@
+
+\section{Bending_magnet: A bending magnet source}
+\label{s:bending_magnet}
+\index{Optics!Bending_magnet}
+\mcdoccomp{sources/Bending_magnet.parms}
+
+The component \textbf{Bending_magnet} models a bending magnet source. The source is defined by the electron beam energy \textit{Ee}, the ring current \textit{Ie}, and the magnetic field strength \textit{B}. The size of the electron beam is defined by the \textit{sigex} and \textit{sigey} parameters, which are the horizontal and vertical rms beam sizes, respectively.
+
+The source emits photons with a given energy spectrum, which can be defined by either the \textit{E0} and \textit{dE} parameters (for a uniform or Gaussian distribution) or by the \textit{lambda0} and \textit{dlambda} parameters (for a uniform or Gaussian distribution). The coherence of the emitted radiation is controlled by the \textit{phase} and \textit{randomphase} parameters.
+
+The component also allows for the use of a target window, which is defined by the \textit{focus_xw}, \textit{focus_yh}, and \textit{dist} parameters. The \textit{gauss_t} parameter controls whether the target window is sampled uniformly or with a Gaussian distribution.
+
diff --git a/doc/manuals/mcxtrace/sources/Source_div.tex b/doc/manuals/mcxtrace/sources/Source_div.tex
@@ -17,6 +17,6 @@ \section{Source\_div: A continuous source with specified divergence}
 at that wavelength. This implies an oversampling of weak parts of the intensity spectrum.
 
 The beam intensity is uniform over
-the whole of the source and the source divergences are \textit{focus\_ah} and \textit{focus\_aw} in degrees.
-Unless \textit{gauss\_a}$\neq=0$ the individual photons are sampled from a uniform divergence distribution, otherwise a Gaussian is used.
-
+the whole of the source and the source divergences are \textit{focus_ah} and \textit{focus_aw} in radians.
+Unless \textit{gauss_a} is non-zero the individual photons are sampled from a uniform divergence distribution, otherwise a Gaussian is used.
+A radial divergence can also be specified using the \textit{focus_ar} parameter. The source can be either rectangular or circular, as specified by the \textit{xwidth}, \textit{yheight}, and \textit{radius} parameters. The \textit{verbose} parameter can be used to generate more output on the console.
diff --git a/doc/manuals/mcxtrace/sources/Source_div_quasi.tex b/doc/manuals/mcxtrace/sources/Source_div_quasi.tex
@@ -0,0 +1,13 @@
+
+
+\section{Source_div_quasi: A quasi-stochastic source with specified divergence}
+\label{s:source_div_quasi}
+\index{Optics!Source_div_quasi}
+\mcdoccomp{sources/Source_div_quasi.parms}
+
+The component \textbf{Source_div_quasi} is a flat rectangular surface source with a uniform or Gaussian divergence profile. The source is similar to the \textbf{Source_div} component, but it uses Halton sequences instead of pseudo-random numbers to sample the phase space. This ensures that the samples are evenly distributed within the region of interest.
+
+The source is defined by its \textit{xwidth} and \textit{yheight}, and the divergence of the beam is controlled by the \textit{focus_aw} and \textit{focus_ah} parameters. The energy spectrum of the source can be defined by either the \textit{E0} and \textit{dE} parameters or by the \textit{lambda0} and \textit{dlambda} parameters. The coherence of the emitted radiation is controlled by the \textit{phase} and \textit{randomphase} parameters.
+
+The component also allows for the use of a target window, which is defined by the \textit{focus_xw}, \textit{focus_yh}, and \textit{dist} parameters.
+
diff --git a/doc/manuals/mcxtrace/sources/Source_flat.tex b/doc/manuals/mcxtrace/sources/Source_flat.tex
@@ -5,7 +5,7 @@ \section{Source\_flat: A flat surface emitting photons with a spectrum either un
 
 A simple source model, with a flat surface emitting photons. The surface in the
 $xy$-plane is specified as a rectangle with dimensions
-$\mathit{xwidth}\times \mathit{yheight}$ \si{m \squared}, or as a circle with \textit{radius} \si{m}. 
+$\mathit{xwidth}\times \mathit{yheight}$ \si{m \squared}, or as a circle with \textit{radius} \si{m}. The \textit{xwidth} parameter overrides the \textit{xmin} and \textit{xmax} parameters. 
 The initial x-ray position is chosen randomly in the source surface --- its
 wavevector is chosen randomly (exactly as in the case of \textbf{Source\_pt})
 (section \ref{s:source-pt}) in the defining aperture with height \textit{focus\_yh} and
diff --git a/doc/manuals/mcxtrace/sources/Source_genesis13.tex b/doc/manuals/mcxtrace/sources/Source_genesis13.tex
@@ -0,0 +1,12 @@
+
+\section{Source_genesis13: An interface for GENESIS 1.3}
+\label{s:source_genesis13}
+\index{Optics!Source_genesis13}
+\mcdoccomp{sources/Source_genesis13.parms}
+
+The component \textbf{Source_genesis13} is an interface for importing X-ray pulses generated by GENESIS 1.3 into McXtrace. The component reads the dumped radiation field output from GENESIS 1.3 and samples it to be used in McXtrace.
+
+The component is defined by the name of the GENESIS 1.3 output file (\textit{fname}), the mesh size (\textit{meshsize}), the number of grid points (\textit{gridpoints}), and the number of slices (\textit{nslices}). The energy spectrum of the source can be defined by the \textit{E0} and \textit{dE} parameters.
+
+The component also allows for the use of a target window, which is defined by the \textit{focus_xw}, \textit{focus_yh}, and \textit{dist} parameters. The \textit{focus_a} parameter controls the mean divergence angle of the beam.
+
diff --git a/doc/manuals/mcxtrace/sources/Source_lab.tex b/doc/manuals/mcxtrace/sources/Source_lab.tex
@@ -24,7 +24,7 @@ \section{Source\_lab: X-ray tube laboratory source}
 elctron beam at the surface of the
 anode material and is oriented such that the z-axis points at the center of the
 exit window, and the x-axis is parallel to the \emph{width} of the electron
-beam. 
+beam. If the \textit{exit_window_refpt} parameter is set, the AT position and the exit window will coincide.
 
 Note that the exit aperture is merely an opening. If the
 material absorption of a window, e.g. Be, is to be taken into account a
@@ -85,4 +85,4 @@ \section{Source\_lab: X-ray tube laboratory source}
 in the \texttt{SHARE} section of the component source code.
 Here $[E_C]$ refers to a comma separated list of characteristic energies in \si{keV}, $[W]$ a
 list of characteristic widths in \si{keV}, and $[I]$ a list of relative line intensities.
-Lastly, $n$ denotes the number of x-ray lines.
+Lastly, $n$ denotes the number of x-ray lines.
diff --git a/doc/manuals/mcxtrace/sources/Source_pt.tex b/doc/manuals/mcxtrace/sources/Source_pt.tex
diff --git a/doc/manuals/mcxtrace/sources/Source_simplex.tex b/doc/manuals/mcxtrace/sources/Source_simplex.tex
diff --git a/doc/manuals/mcxtrace/sources/Source_spectra.tex b/doc/manuals/mcxtrace/sources/Source_spectra.tex
diff --git a/doc/manuals/mcxtrace/sources/Undulator.tex b/doc/manuals/mcxtrace/sources/Undulator.tex
diff --git a/doc/manuals/mcxtrace/sources/Wiggler.tex b/doc/manuals/mcxtrace/sources/Wiggler.tex
