Merge pull request #2403 from willend/main

Minor manual patches

Author: willend

docs/manuals/mcstas/abstractpage.tex

@@ -18,26 +18,24 @@
 Emmanuel Farhi \verb+<emmanuel.farhi@synchrotron-soleil.fr>+ \\
 Synchrotron SOLEIL, Saint-Aubin, France
 
+Kim Lefmann \verb+<lefmann@nbi.dk>+ \\
+Niels Bohr Institute, University of Copenhagen, Denmark
+
+\end{quote}
+as well as authors who left the project:
+\begin{quote}
 Erik Knudsen \verb+<erkn@fysik.dtu.dk>+ \\
 Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark 
-
 Jakob Garde \verb+<jaga@fysik.dtu.dk>+\\
 Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark
-
-Kim Lefmann \verb+<lefmann@fys.ku.dk>+ \\
-Niels Bohr Institute, University of Copenhagen, Denmark
-
 Jonas Stein \verb+<Jonas.Stein@uni-koeln.de>+ \\
 Institute of Physics II, University of Cologne, Germany
-\end{quote}
-as well as authors who left the project:
-\begin{quote}
 Peter Christiansen \verb+<pchristi@hep.lu.se>+\\
 Materials Research Department, Ris{\o} National Laboratory, Roskilde, Denmark\\
 Present address: University of Lund, Lund, Sweden\\
-Klaus Lieutenant \verb+<klaus.lieutenant@helmholtz-berlin.de>+ \\
+Klaus Lieutenant \verb+<k.lieutenant@fz-juelich.de>+ \\
 Institut Laue-Langevin, Grenoble, France \\
-Present address: Helmotlz Zentrum Berlin, Germany \\
+Present address: Forschungs-Zentrum J\"ulich, Germany \\
 Kristian Nielsen \verb+<kristian-nielsen@mail.tele.dk>+ \\
 Materials Research Department, Ris{\o} National Laboratory, Roskilde, Denmark\\
 Presently associated with: MySQL AB, Sweden

docs/manuals/mcstas/abstractpage_comp.tex

@@ -16,24 +16,22 @@
 Emmanuel Farhi \verb+<emmanuel.farhi@synchrotron-soleil.fr>+ \\
 Synchrotron SOLEIL, Saint-Aubin, France
 
-Erik Knudsen \verb+<erkn@fysik.dtu.dk>+ \\
-Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark 
-
-Jakob Garde \verb+<jaga@fysik.dtu.dk>+\\
-Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark
-
 Kim Lefmann \verb+<lefmann@nbi.dk>+ \\
 Niels Bohr Institute, University of Copenhagen, Denmark
 
 \end{quote}
 as well as authors who left the project:
 \begin{quote}
+Erik Knudsen \verb+<erkn@fysik.dtu.dk>+ \\
+Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark 
+Jakob Garde \verb+<jaga@fysik.dtu.dk>+\\
+Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark
 Peter Christiansen \verb+<pchristi@hep.lu.se>+\\
 Materials Research Department, Ris{\o} National Laboratory, Roskilde, Denmark\\
 Present address: University of Lund, Lund, Sweden\\
-Klaus Lieutenant \verb+<klaus.lieutenant@helmholtz-berlin.de>+ \\
+Klaus Lieutenant \verb+<k.lieutenant@fz-juelich.dee>+ \\
 Institut Laue-Langevin, Grenoble, France \\
-Present address: Helmotlz Zentrum Berlin, Germany \\
+Present address: Forschungs-Zentrum J\"ulich, Germany \\
 Kristian Nielsen \verb+<kristian-nielsen@mail.tele.dk>+ \\
 Materials Research Department, Ris{\o} National Laboratory, Roskilde, Denmark\\
 Presently associated with: MySQL AB, Sweden

docs/manuals/mcstas/intro.tex

@@ -297,6 +297,13 @@ \section{Overview}
 present here an extensive list of corrections, and we let the reader
 refer to this bug reporting service for details. Only important
 changes are indicated in the CHANGES document.
+In addition to this manual, extensive and up-to-date documentation is
+maintained on the \McStas/McCode GitHub wiki~\cite{Wiki}:
+\begin{center}
+  \url{https://github.com/mccode-dev/McCode/wiki}
+\end{center}
+The wiki covers end-user tutorials, component development guides, GPU
+acceleration, and migration from \McStas~2.x to 3.x.
 \item Chapter~\ref{s:MCtechniques} concerns Monte Carlo techniques
   and simulation strategies in general
 \item Chapter~\ref{c:running} includes a brief introduction to the

docs/manuals/mcstas/mcstas.bib

@@ -512,7 +512,7 @@ @MISC{mcnsi_webpage
 }
 
 @MISC{mcstas_webpage,
-  note = {See \url{http://www.mcstas.org}}
+  note = {See \url{https://www.mcstas.org}}
 }
 
 @MISC{github_issue_webpage,

docs/manuals/mcstas/preamble_manual.tex

@@ -24,7 +24,7 @@
   colorlinks=false,   % 
   pdfpagemode=UseNone,  % PDF-Viewer TOC settings
   pdfstartview=FitH, % PDF-Viewer 
-  pdfauthor={P. Willendrup, E. Farhi, E. Knudsen, U. Filges, K. Lefmann, J. Stein},%
+  pdfauthor={P. Willendrup, E. Farhi, K. Lefmann},%
   pdftitle=User and programmers guide to the neutron ray-tracing package McStas%
 }
 

docs/manuals/mcstas/preface.tex

@@ -22,7 +22,7 @@ \chapter*{Preface and acknowledgments}
 community, too numerous to mention here.
 
 In case of errors, questions, or suggestions, do not hesitate to
-contact the authors at \verb+mcstas-support@mcstas.org+
+contact the authors at \verb+mcstas-users@mcstas.org+
 or consult the \MCS home page~\cite{mcstas_webpage}.
 A special bug/request reporting service is available \cite{github_issue_webpage}.
 

docs/manuals/mcstas/running.tex

@@ -56,7 +56,32 @@ \section{Installation and updates}
 In case of problems, write the support mailing list,
 or contact the authors.
 
-%-------------------------------------------------------------------------------
+% -------------------------------------------------------------------------------
+\subsubsection{Installation via conda-forge (recommended)}
+\label{s:install-conda}
+
+The recommended installation method for all supported platforms---Linux,
+macOS, and Windows---is via the \texttt{conda-forge} channel.  Once a
+conda-compatible environment manager such as Miniforge or Mambaforge is
+available, \McStas can be installed into a fresh conda environment:
+
+\begin{verbatim}
+  conda create -n mcstas -c conda-forge mcstas
+  conda activate mcstas
+  mcgui
+\end{verbatim}
+
+On Windows a dedicated \texttt{mcstas-conda} batch script is provided by
+the installer.  After it completes, use the \emph{mcstas-shell} desktop
+shortcut and issue \texttt{mcgui} to start the graphical interface.
+Arm64 Windows is also supported via this route.
+
+For full platform-specific installation instructions, including Linux
+package management and macOS options, see:
+\begin{center}
+  \url{https://github.com/mccode-dev/McCode/tree/main/INSTALL-McStas}
+\end{center}
+
 \subsection{Important note for Windows users} 
 \index{Windows!file and directory names with spaces}
 \index{Windows!Perl distribution}
@@ -245,6 +270,33 @@ \subsection{Code generation options}
 Finally, the \verb+--verbose+ option will list the components and libraries being
 included in the instrument.
 
+\subsubsection{Alternative code generator: \texttt{mccode-antlr}}
+\label{s:antlr}
+
+From \McStas~3.5 onwards an alternative code generator,
+\texttt{mcstas-antlr}, is available alongside the classic generator.
+It is built on the ANTLR parser framework rather than the traditional
+\texttt{lex}/\texttt{yacc} toolchain, is implemented primarily in Python,
+and is a candidate replacement for the default generator in future releases.
+
+Select it on a per-run basis with the \texttt{--cogen} flag:
+\begin{verbatim}
+  mcrun --cogen=mcstas-antlr MyInstrument.instr -n 1e8
+\end{verbatim}
+
+The active code generator can also be set permanently by editing the
+\texttt{MCCOGEN} field in \texttt{mccode\_config.json}.  This file is
+accessible from the command line with:
+\begin{verbatim}
+  mcrun --edit-user-config
+\end{verbatim}
+or via the \emph{Save/Edit configuration} dialogue inside \texttt{mcgui}.
+
+At the time of the \McStas~3.6 release, \texttt{mcstas-antlr} is close to
+feature-complete for CPU simulations with a few more issues for GPU/OpenACC
+simulations.
+
+
 %-------------------------------------------------------------------------------
 \subsection{Specifying the location of files}
 \label{s:files}
@@ -883,7 +935,7 @@ \section{Using simulation front-ends}
        mcdaemon      Instrument results on-line plotting
     When used with the -h flag, all tools display a specific help.
     SEE ALSO: mcstas, mcdoc, mcplot, mcrun, mcgui, mcresplot, mcstas2vitess
-    DOC:      Please visit http://www.mcstas.org
+    DOC:      Please visit https://www.mcstas.org
 \end{lstlisting}
 
 %-------------------------------------------------------------------------------
@@ -1247,6 +1299,54 @@ \subsection{Running simulations on the commandline (mcrun)}
 The \verb+-h+ option will list valid options. The \verb+mcrun+ front-end
 requires a working installation of Perl to run.
 
+\subsection{GPU acceleration via OpenACC}
+\label{s:gpu}
+
+\McStas~3.x supports GPU-accelerated simulations through the OpenACC
+framework, enabling substantial speed-ups over CPU-only execution on
+compatible NVIDIA hardware.
+
+\subsubsection{Requirements}
+
+\begin{itemize}
+  \item \textbf{Compiler:} NVIDIA HPC SDK version~20.x or newer.  The
+        free Community Edition is sufficient.
+  \item \textbf{Hardware:} A CUDA-capable NVIDIA GPU with an up-to-date
+        driver.
+  \item \textbf{Platform:} GPU support is currently available on Linux
+        only.  Windows is not yet supported for OpenACC by NVIDIA; Windows
+        users wishing to use GPU acceleration should do so via
+        WSL~2 running a Linux distribution.
+\end{itemize}
+
+\subsubsection{Running a GPU-accelerated simulation}
+
+Pass the \texttt{--openacc} flag to \texttt{mcrun}:
+\begin{verbatim}
+  mcrun --openacc MyInstrument.instr -n 1e9
+\end{verbatim}
+
+\paragraph{Combined multi-core + GPU execution.}
+It is also possible to use both CPU cores and the GPU simultaneously.
+Enable this by adding the following to the \texttt{OACCFLAGS} field of
+your \texttt{mccode\_config.json}:
+\begin{verbatim}
+  "OACCFLAGS": "-fast -Minfo=accel -acc=gpu,multicore
+                -gpu=managed -DOPENACC -DMULTICORE"
+\end{verbatim}
+
+\subsubsection{Further information}
+
+GPU terminology specific to \McStas/McXtrace~3 and detailed debugging
+tips are documented on the McCode wiki:
+\begin{itemize}
+  \item GPU terminology table:\\
+    \url{https://github.com/mccode-dev/McCode/wiki/McStas-McXtrace-3-and-GPU-terminology-(table)}
+  \item GPU debugging tips:\\
+    \url{https://github.com/mccode-dev/McCode/wiki/GPU-Debugging-tips}
+\end{itemize}
+
+
 
 %-------------------------------------------------------------------------------
 \subsection{Graphical display of simulations (mcdisplay)}
@@ -1532,6 +1632,16 @@ \subsection{Creating and viewing the library, component/instrument help and
 format.  To use the \verb+mcdoc+ front-end, the program Perl should be
 available.
 
+\paragraph{Online wiki.}
+In addition to this manual, extensive and frequently updated documentation
+is maintained on the McCode GitHub wiki~\cite{Wiki}:
+\begin{center}
+  \url{https://github.com/mccode-dev/McCode/wiki}
+\end{center}
+The wiki includes end-user guides, component development howtos, GPU
+acceleration information, and migration guides from \McStas~2.x to 3.x.
+
+
 %-------------------------------------------------------------------------------
 \subsection{Translating \MCS components for Vitess (mcstas2vitess)}
 \label{s:mcstas2vitess}

docs/manuals/mcstas/title.tex

@@ -3,7 +3,7 @@
  \includegraphics[width=50mm]{figures/mcstas_logo_reflection.png}\\[4mm]
  \end{center}
  }
-\author{P. Willendrup, E. Farhi, E. Knudsen, U. Filges, K. Lefmann, J. Stein}
+\author{P. Willendrup, E. Farhi, K. Lefmann}
 \date{\reldate}
 
 \titlehead{