CHANGES_McXtrace

/************************************************************************'
* 
* McXtrace X-ray tracing software
* Copyright, All Rights Reserved
* DTU-Physics, Kgs. Lyngby, Denmark
* ESRF, Grenoble, France
* Univeristy of Copenhagen, Copenhagen Denmark
* 
*
*
* McStas and McXtrace share code repository at
* https://github.com/McStasMcXtrace/McCode
*
* Both codes are released under GPL v3
*
* Documentation: CHANGES_McXtrace
*************************************************************************/
Changes in McXtrace 3.5.1, September 16th, 2024

 McXtrace 3.5.1 is the sixth official release in the 3.x series, with a modernised 
 code-generator and support for GPU acceleration on NVIDIA cards.

 Thanks:
 - Thanks to all members of the joint McStas-McXtrace team and input from our
   users via emails and GitHub issues alike! Further a special thanks to
   Theodor Peter Guttesen (former DTU diploma student) who has helped modernise
   our 3D visualisation!

 Important changes going forward:
 - From release 3.5.1 McStas and McXtrace are released simultaneously and with
   the same versioning (meaning that McXtrace takes a jump from 3.2 up to 3.5)
 - With release 3.5.1 we are officially dropping support for the "legacy"
   McStas 2.7.2 release and the "legacy" McXtrace 1.7.1 release.
 - To minimize work required for platform support and builds, we are now focusing
   on fewer platforms:
   * Debian packages at packages.mccode.org are provided for x86_64 and arm64 Linux
     (Thanks to the work of Emmanuel Farhi and his team at SOLEIL, official Debian
     packages are already available in Debian Testing and Unstable 
     (see https://tracker.debian.org/pkg/mccode) and should become
     widely available with next Debian Stable, after which we might drop our "own
     channel").
   * conda-forge is to become our distribution channel for "everything else", meaning
     that:
     1. Our macOS "bundles" are effectively now self-extracting conda-installers and
        REQUIRES an active internet connection during installation
     2. From a later release in the 3.5 series the same will be the case for Windows
     - We are dropping builds for ALL rpm-oriented platform. Please use conda-forge instead.
 - We want to release more "early and often" going forward, see below under conda-forge.

 Conda-forge:
 - We are now officially on conda-forge, with feedstocks available at:
   * https://github.com/conda-forge/mcstas-suite-feedstock
   * https://github.com/conda-forge/mcxtrace-suite-feedstock
 - Via conda-forge we  support the platforms linux-64, linux-aarch64, osx-arm64, osx-64 and win-64
 - The conda-forge win-64 packages have slight shortcomings for this first release, meaning that:
   * MCPL is not shipped with McXtrace
   * MCPL and NCrystal are not shipped with McStas
 - We still provide cross-compiled installers for Windows (mingw builds) for now
 - You will find that when installed via conda-forge, file locations are slightly different:
   most of the locations may be probed via:
   mxrun --showcfg=ITEM   Print selected cfg item and exit (paths are resolved
                          and absolute). Allowed values are "bindir", "libdir",
                          "resourcedir", and "tooldir".
   (Wrt. locations of examples and components, the "resourcdir" is the same as $MCSTAS)
 - Going forward, we will add incremental releases in the 3.5-series as work happens on the
   main McStas/McXtrace branch - and this work will automatically go on our official
   conda-forge and Debian channels. Other distribution channels ("bulky installers etc.)
   may come with longer intervals.


 Fixes of issues from last 3.x release:
 - A number of issues from 3.2 were addressed, see the relevant GitHub issues for details:
   - https://github.com/McStasMcXtrace/McCode/issues?q=is%3Aissue+is%3Aclosed+label%3Amcxtrace-3.2

 Installation:
 - Our install docs are available on the McCode GitHub page at
   https://github.com/McStasMcXtrace/McCode/tree/master/INSTALL-McXtrace
 - The meta-package for Debian/Ubuntu is named mcstas-suite-python
 - OpenACC GPU (and CPU multicore) acceleration is at the time of release still ONLY
   supported on Linux systems, as this is the only platform targeted by the NVIDIA
   HPC package. Versions 20.x -> 24.x should all work. On Windows 64bit systems,
   support is expected to arrive "later", but you may run on your GPU via the so-called
   "Windows Subsystem for Linux" (WSL). macOS is unfortunately not supported
   by NVIDIA HPC acceleration.
 - McXtrace 3.5.1 packages come with OpenMPI and NeXus as install-time dependencies for all supported 
   platforms.

 McXtrace 3.5.1 enables most components and instruments on GPU. A few components compute only on CPU:
 - Components using shared libraries from external software:
   * GNU Scientific library used in: 
     contrib/SAXSNanodiscsFast
     contrib/SAXSEllipticCylinders
     contrib/SAXSCylinders
     contrib/SAXSPDB
     contrib/SAXSNanodiscsWithTags
     contrib/SAXSNanodiscs
     contrib/SAXSPDBFast
     contrib/SAXSNanodiscsWithTagsFast
     sources/Undulator
   * Xraylib library used in: 
     samples/Fluorescence

 Tool enhancements:
 - The mxdisplay-webgl tool has received a MAJOR overhaul:
   * Support for visualisation of proper "solids" instead of "multilines". Key components 
     have been updated with this new style, but more will come in the following releases.
   * New react/js user-interface with options for choosing colour and transparency
     of the individual components.
   * Save and load of instrument visualisation and particle rays in JSON format
   * The new features require a server-process, facilitated by the 'vite' javascript/node.js
     oriented server. The server is by default shut down after 5 minutes - but mxdisplay-webgl
     has an input parameter to control this behavior.
   * On first launch the 'npm' package manager installs and builds packages to the McXtrace
     user directory, so expect this first launch to take a little time.
   * The tool further has a '2D' mode in the style of mxdisplay-pyqtgrahph, simply use your
     mouse wheel on the browser menu to scroll the 3D view 'up' and the 2D views will appear!

 - The mxgui user interface also has recieved a numner of usability changes:
   * The main interface includes a new 'Jupylab' button that will convert a loaded
     instrument file to McStasScript (python) format and launch Jupyterlab.
   * The mxgui font-size can be configured via the Preferences dialogue and saved to 
     the user-level mccode_config.json file
   * Monitor_nD "buffersize" of a given simulation (mostly used for the list/event mode)
     may be configured via the Preferences dialogue and saved to the user-level config
   * When copying an instrument from the Examples / Templates, the instrument-folder is
     copied, i.e. including both instrument and specific datafiles etc.
   * The "autoplot" mode that spawns plotting post simulation completion now also functions
     with NeXus output
   * "Inverted" canvas can be chosen when autoplotting with mxplot(-pyqtgraph)


 - Improved NeXus support in both mxgui and mxrun:
   * The JSON configuration file mccode_config.json now includes a HDFVIEW setting,
     defaulting to 'nexpy' on the conda-forge based systems and HDFCompass on Debian
     as nexpy is not yet available here. (A useful alternative is 'silx view'.)

 - The primary mxplot(-pyqtgraph) tool also received a number of updates:
   * The tool behaves correctly both in case of PyQt5 and PyQt6 based systems
   * Visibility of legends is highly improved both on (standard) black canvas and
     inverted white canvas (select from the mxgui prefs / run dialogue)
   * When selecting --format=NeXus and requesting '--autoplot' from mxgui/mxrun, both the
     mxplot(-pyqtgraph) and mxplot-matplotlib plotters request the HDFVIEW tool to 
     open the resulting mccode.h5 file.

 - The 'mxtest' tool is now available as a user-tool. The tool
   * Allows to test for compilation of all instruments
   * test-executes those including with %Example lines.
   * To test your McXtrace installation, simply execute 'mxtest' in your McXtrace environment
   * The tool creates an output folder with the tested instruments in subfolders and the
     test simulation results in subfolders under these. Compile-time, execution-time and 
     test numerical output is stored in JSON files.
   * The most important commandline switches are these:
     --ncount N selects the wanted statistic for the tests
     --mpi=number or --mpi=auto enables mpi mode for the tests
     --openacc enables OpenACC accelerations on Nvidia GPU on Linux
     --instr=PATTERN only test instruments matching PATTERN
     --testdir=DIR puts the test results under the DIR folder
     --suffix=SUFFIX adds SUFFIX as an identifier in the output foldername
     --nexus enables NeXus output for all tested instruments
   * Here is an example of a run:
     # mxtest --instr=JJ_SAXS --testdir=mcxtrace-test
     loading system configuration
     Output of test will be placed in: mcxtrace-test
     ncount is: 1e6
     Testing: 3.5.1

     Finding instruments in: /Users/peterwillendrup/miniforge3/share/mcxtrace/resources/examples
     Copying instruments to: mcxtrace-test/mcxtrace-3.5.1_JJ_SAXS_Darwin

     Compiling instruments [seconds]...
     JJ_SAXS :   2.10

     Running tests...
     JJ_SAXS  :   0.85


  - The 'mxviewtest' tool is now available as a user-tool. The tool may be used to render
    an html page with results from one or more 'mxtest' runs. If your results of a test run
    was placed in e.g. mcxtrace-test/mcxtrace-3.5.1_JJ_SAXS_Darwin:
    * cd to mcstas-test
    * run the command:    mxviewtest
    * You may then open the resulting html file for visualisation in your browser and see
      an output simmilar to that of our nightly test, see e.g.
      https://new-nightly.mcxtrace.org/2024-09-11_output.html (A single test run gives
      a single column of output - the example test demonstrated above would give only a
      single cell since only one test was executed for a single instrument.)
    * GRAY = instrument compiled OK, GREEN = instrument test agrees with %Example line,
      RED = numerical result disagrees, WHITE with red text = instrument did not compile.
    * The included numbers pr. cell includes C: compile time R: runtime and I=numerical value

 Components and Instruments:
 - The examples/ folder is no longer a flat directory, but has instead beceme a tree-structure,
   subdivided into instrument categories:
   * Facility / University / source type instruments:
     BARC DTU ESRF MAXII MAXIV NIST SAXSLAB SSRL NBI NSLS2 SOLEIL XFEL	
   * Templates, tools and various tests:
     Tests Tests_optics Tests_samples Templates	Tests_grammar Tests_other Tests_sources
   * AstroX - X-ray telescoe models etc.
     AstroX_ESA AstroX_NASA
 - Each instrument has its own folder within the hierarcy, where usage-specific input files
   etc. may also exist. In the future we may decide to distribute some McStasScript instruments
   within this folder structure.
 - Fearure-updates and fixes in components and instruments:
   * Single_crystal: experimental surface diffraction mode (CTR).
   * Fluorescence: fix line-shape, handle multiple scattering.
   * SOLEIL_SIXS beam-line model, using SX component with surface CTR.
   * Many bug fixes in instruments and components.
   
 Core simulation framework / code-generator:
 - The McStas and McXtrace code-generators are fully synchronised from v3.5.1 onwards.

 Libraries and other runtime code:
 - The NeXus output is richer from McXtrace 3.5.1, specifically:
   * All component global postions and orientations are placed as dataset within
     /entry1/instrument/components/<COMP>
   * Monitors store their detector outputs in
     /entry1/instrument/components/<COMP>/output/<filename>
 - MCPL library from T. Kittelmann (ESS) included at v. 1.6.2
  - On debian we are providing a packages for MCPL via the
   McCode repository, independent of the McXtrace release. (MCPL has further arrived
   in the Debian ecosystem, thanks to Synchrotron SOLEIL, Emmanuel Farhi and Roland Mas.)

 Migration to 3.5.1:
 - As mentioned above, we no longer support McXtrace 1.x.
 - The Wiki has a dedicated section on McXtrace 1.x -> McXtrace 3.x conversion that includes:
   * A nomenclature list containing short descriptions of new concepts and important keywords
     in McXtrace 3.x and OpenACC / CUDA code in general.
   * A document outlining the most importand differences between 1.x and 3.x.
   * A guide for 1.x -> 3.x instrument conversion.
   * A guide for 1.x -> 3.x component conversion.
 - If you are still in trouble, please write us a GitHub issue or an email to mcxtrace-users@mcxtrace.org

 Platforms:
  - We provide packages for the following platforms / systems:
    * conda-forge Platforms linux-64, linux-aarch64 osx-arm64, osx-64 and win-64
    * Debian-based distros on Intel and Arm
    * conda-forge based 'application bundles' for
      64bit macOS 12-14 both Intel and Silicon (should also be ready for macOS 15 Sequoia)
    * A cross-compiled 'bulky installer' for 64bit Windows 10/11 on Intel
  - For RPM based distros please use our conda-forge solution!
  - For e.g. FreeBSD you may roll your own using CMake.

We hope you will enjoy this new release!!!

CHANGES in 3.2

 McXtrace 3.2 is the third official release in the 3.x series, with a modernised 
 code-generator and support for GPU acceleration on NVIDIA cards.

 Thanks:
 - Thanks to all members of the joint McStas-McXtrace team, you guys ROCK!

 Fixes of issues from last 3.x release:
 - A large number of issues from 3.1 were addressed, see the relevant GitHub issues for details:
   - https://github.com/McStasMcXtrace/McCode/issues?q=is%3Aissue+is%3Aclosed+label%3Amcxtrace-3.1

 Documentation & guides:
 - Inline component documentation has been given an overhaul, most component doc pages should now
   render in a meaningful way

 Installation:
 - As usual, our install docs are available on the McCode GitHub page at
   https://github.com/McStasMcXtrace/McCode/tree/master/INSTALL-McXtrace
 - The meta-packages for Debian/Ubuntu and Fedora are named e.g.
   mcxtrace-suite-python-ng 'next generation' for 3.x and mcxtrace-suite-python
   for the 1.x series packages.
 - OpenACC GPU (and CPU multicore) acceleration is at the time of release still ONLY
   supported on Linux systems, as this is the only platform targeted by the NVIDIA
   HPC package. Versions 20.x-23.x should all work. On Windows 64bit systems,
   support is expected to arrive "later", but you may run on your GPU via the so-called
   "Windows Subsystem for Linux" (WSL). macOS is unfortunately not supported
   by NVIDIA HPC acceleration.

 McXtrace 3.2 enables further components and instruments GPU. Effectively all functionality has
 been ported to 3.x.

 Interoperability with other codes:
 - McXtrace now ships with a "python-aware" code generator for generating "McStasScript" code, example:
     mcxtrace-pygen Instrument.instr   -->   Instrument_generated.py
   Using 'jupytext' this file may easily be converted to a notebook:
     jupytext --to ipynb Instrument_generated.py   -->   Instrument_generated.ipynb
   See https://github.com/PaNOSC-ViNYL/McStasScript
   for more information on McStasScript, that also works for X-rays.
 - Thanks to the work of José Robledo (FZJ), we now have a better interface to the Small-Angle Scattering
   models from SASview, aka. SASmodels. Due to the big number of included models that each correspond
   to a McXtrace component, these are now found in the "sasmodels" folder of your McXtrace installation.

 Tools:
 - mxplot (-pyqtgraph) has received a couple of bugfixes relating to plotting in log-mode.
 - mxrun has now a number of --optimize options to Optimize beam-line parameters. Specify min,max or min,start,max for parameters to vary. the default optimizer is Powell from SciPy. You may choose the monitor to optimize, or all. Use mxrun -h for more help.
 - mxgui Run dialogue now allows to Optimize beam-line parameters. Specify min,max or min,start,max for parameters to vary. the default optimizer is Powell from SciPy. You may choose the monitor to optimize, or all.


 Components and Instruments:
 - As mentioned above, SASmodels now come in the form of 94 (!) components in the sasmodels folder.
 - The Isotropic_Sqw sample by Emmanuel Farhi has received a number of updates.
 - The Fluorescence sample by Emmanuel Farhi has received a number of updates.
 - PowderN and Single_crystal may now use material definition from a CIF file, calls the cif2hkl
   tool behind the scenes, work done by Emmanuel Farhi.
 - New instrument SOLEIL_CASSIOPEE.instr from Emmanuel Farhi.
 - Many updates to SOLEIL_ instruments.

 Core simulation framework / code-generator:
 - McXtrace will now issue a warning if you generate GROUPS of a single component, as this may
   lead to unphysical results. (GROUPS are intended for 2 or more components in an "exclusive-or"
   setup.

 Please start your migration to 3.x:
 - The last release of McXtrace 1.x was 1.7.1 that shares a subset of tool features with McXtrace 3.x.
   Hence you should now move to McXtrace 3.x.
 - The Wiki has a dedicated section on McXtrace 1.x -> McXtrace 3.x conversion that includes:
   * A nomenclature list containing short descriptions of new concepts and important keywords
     in McXtrace 3.x and OpenACC / CUDA code in general.
   * A document outlining the most importand differences between 1.x and 3.x.
   * A guide for 1.x -> 3.x instrument conversion.
   * A guide for 1.x -> 3.x component conversion.
 - If you are still in trouble, please write us a GitHub issue or an email to mcxtrace-users@mcxtrace.org
 - Known limitations in the GPU-implementation:
   * Some components work on CPU only, but can be used in the mixed GPU/CPU funnnel mode by raising the
     NOACC component keyword, e.g. Undulator.comp and the various SAXS samples.
   * Special NOACC versions of Monitor_nD and MCPL_output are included. These may be used in the case
     of large event datasets, allowing more than 2e9 events to be stored.

 Platforms:
  - We still support 64bit Windows 10/11 on Intel, all recent 64bit macOS including 13.0 Ventura and later
    on both Intel and Apple Silicon/M1 processors. Debian-based distros on Intel and Arm, Fedora on Intel.
  - On macOS and Windows we now bundle a Mambaforge Python with the installation.


We hope you will enjoy this new release!!!

CHANGES in 3.1

 McXtrace 3.1 is the second official release in the 3.x series, with a modernised 
 code-generator and support for GPU acceleration on NVIDIA cards.
 
 Thanks:
 - Thanks to all members of the joint McStas-McXtrace team, you guys ROCK!
 - Our joint hackathon in November brought lots of goodies to our user base!

 Fixes of issues from last 3.x release:
 - A large number of issues from 3.0 were addressed, see the relevant GitHub issues for details:
   - https://github.com/McStasMcXtrace/McCode/issues?q=is%3Aissue+is%3Aclosed+label%3Amcxtrace-3.0

 Documentation & guides:
 - The component pages now include an extra column in the parameter-table. When filling in
   this column with wanted values, plus filling the entry-boxes for AT, ROTATED and instance
   name, pressing "Generate" will put a code-snipet for your component instance directly on
   your computer clipboard, for easy transfer to the mcgui editor or any other editor of choice!
 - mxdoc has been made "less picky" wrt. component and instrument structure for a more robust
   experience.
 - mxgui has a new "Docs" button for easier access to the generated mcdoc pages (that give easy
   access to components, instruments, manuals, datafiles and more.
   
 Installation:
 - As usual, our install docs are available on the McCode GitHub page at
   https://github.com/McStasMcXtrace/McCode/tree/master/INSTALL-McXtrace
 - The meta-packages for Debian/Ubuntu and Fedora are named e.g.
   mcxtrace-suite-python-ng 'next generation' for 3.x and mcxtrace-suite-python
   for the 1.x series packages.
 - OpenACC GPU (and CPU multicore) acceleration is at the time of release still ONLY
   supported on Linux systems, as this is the only platform targeted by the NVIDIA
   HPC package. Versions 20.x, 21.x and 22.x should all work. On Windows 64bit systems,
   support is expected to arrive "later", but you may run on your GPU via the so-called
   "Windows Subsystem for Linux" (WSL). macOS is unfortunately not supported
   by NVIDIA HPC acceleration.

 McXtrace 3.1 enables further components and instruments GPU. A limited number of instruments using
 the special features of 1.x are still only available on 1.x.

 Interoperability with other codes:
 - We have worked on the interface with MCPL and a mechanism was developed to automatically detect the
   location using the mcpl-config util. In practice this happens prior/during to the code-generation step,
   see below under mxrun. Thanks to Thomas Kittelmann (ESS) for your help in this area.

 Tools:
 - mxrun has a new solution to support 3 new keywords CMD(), ENV() and GETPATH() through the
   DEPENDENCY line as collected by the code-generator.
   * CMD() is used to call mcpl-config to probe lib and include-paths and
     use them in compiler-directives.
     (Examples available in MCPL_input.comp and MCPL_output.comp)
   * ENV() may evaluate an evironment variable
     (No specific example available yet)
   * GETPATH() can be used to locate the absolute path to e.g. an input file in the $MCXTRACE
     folder hierachy. Component writers may use this mechanism for a low-barrier and platform-
     independent way to access inputfiles.
     (An example is available in Test_MCPL_input.instr)
 - mxrun has a new triplet of switches (D1/D2/D3) that can be used to easily set defines from
   the commandline. For instance --D1=SOMETHING will mean -DSOMETHING when compiling. Note that
   setting these --D flags implies recompilation (-c).
 - mxdoc has been made "less picky" wrt. component and instrument structure for a more robust
   experience. Also, rendered component pages now include an extra column in the parameter-table.
   When filling in this column with wanted parameter-values, plus filling the entry-boxes for
   AT, ROTATED and instance name, pressing "Generate" will put a code-snipet for your component
   instance directly on your computer clipboard, for easy transfer to the mxgui editor or any
   other editor of choice!
 - mxplot (-pyqtgraph) has received a nice update with an infobar at the bottom of the window.
   The infobar is updated with coordinates of the cursor on the active plot, meaning that you
   can easily determine the coordinates of e.g. a peak. The code has also received a number of
   bugfixes relating to colorbars, the order of monitor output in overviews etc.
   Thanks to Tobias Weber (ILL) for your work on mxplot.
 - The new mxdisplay-cad variant has come along, and is currently included in the form of a
   technology-preview. The code uses the Python module cadquery (https://github.com/CadQuery/cadquery)
   and is able to write e.g. STEP or STL output. For now, resolving the required dependencies is
   left to the user, but we foresee that this tool will mature over the coming releases.
   Thanks to Greg Tyler (ESS) for contributing this tool.

 Components and Instruments:
 - The Isotropic_Sqw sample which can be used to model structure and dynamics in isotropic
   materials, such as powders and liquids has been added. The component is developed by
   Emmanuel Farhi and also exists in the McStas code. The component is currently in
   "Experimental" state in McXtrace.
 - Multiple new SOLEIL instruments have been added, thanks to lots of work from Antoine Pado,
   Stephane Bac and Emmanuel Farhi:
   * SOLEIL_ANATOMIX.instr tomography beam-line
   * SOLEIL_DISCO.instr in the imaging mode
   * SOLEIL_MARS.instr in the XRD mode
   * SOLEIL_PX2a.instr protein crystallography beam-line
 - The AstroX toolbox for simulating X-ray telescopes has been included as a special component
   category. GPU support in the related components/instruments is newly developed and likely not
   perfect in all cases.
 - Most of the standard monitors will now fill in their own "instance name" as filename in case
   a filename was not defined. A small but very useful convenience.
 - Lens_elliptical.comp fixed
 - Grating_reflect.comp fixed, and created a test for it.
 - Udated/fixed Mirror_elliptic.comp and created a test for it.
 - Beamline ssrl 11-2 (in it's unfocused and uncollimated mode) added (related to work done on glitches). 
 - Czerny_Turner instrument created.
 - Single_crystal component, corrected absorption cross-section.
   
 Core simulation framework / code-generator:
 - Previously, any component present in a McXtrace instrument would trigger the transformation of
   every photon to its local coordinate system, even in the case of an Arm() (empty TRACE) without
   an EXTEND block. We now instead detect components with an empty TRACE that have no EXTEND block
   and are able to completely skip these in the calculation. This results in a speedup in case of
   instruments with many "empty" components. Thanks to Mads Bertelsen (ESS) for investigating the
   problem and finding a good solution.
 - A new syntax called SHELL has been added to the grammar, allowing users to run a system command
   prior to code-generation. This may for instance be used to generate an instrument-snippet that
   you may %include in the instrument (think for-loops of an assembly of identical components).
   One could also imagine compilation of a needed library, wget of a data file etc.
   The synax is SHELL "command-to-execute" and it should be placed directly after a DEPENDENCY line
   within an instrument or component. We expect that applications and examples will come in the
   next couple of releases.
 - Components may from McXtrace 3.1 request USERVARS that become part of the particle struct.
   (For the time being only in the form of basic C types like double, int etc. and corresponding
   arrays / pointers.) This will mean that e.g. the optimisations in Single_crystal and PowderN
   in SPLIT scenarios can be introduced also in GPU settings.

 Libraries and other runtime code:
 - A flaw was spotted in our NeXus implementation in the case of event lists: A small chunk-size
   of (1,6) was used, leading to slow I/O and lots of size-overhead. Our new NeXus files are
   generally a factor of (at least) 2-3 smaller and load much faster in e.g. Mantid.
 - MCPL library from T. Kittelmann (ESS) is now included at v. 1.6.1
   
 Please start your migration to 3.x:
 - Following the release of 3.1, we will also release a "last update" to the 1.x series in the form
   of McXtrace 1.7.1 that share a subset of tool features with McXtrace 3.1.
 - The Wiki has a dedicated section on McXtrace 1.x -> McXtrace 3.x conversion that includes:
   * A nomenclature list containing short descriptions of new concepts and important keywords
     in McXtrace 3.x and OpenACC / CUDA code in general.
   * A document outlining the most importand differences between 1.x and 3.x.
   * A guide for 1.x -> 3.x instrument conversion.
   * A guide for 1.x -> 3.x component conversion.
 - If you are still in trouble, please write us a GitHub issue or an email to mcxtrace-users@mcxtrace.org
 - Known limitations in the GPU-implementation:
   * Some components work on CPU only, but can be used in the mixed GPU/CPU funnnel mode by raising the
     NOACC component keyword, e.g. Undulator.comp and the various SAXS samples.
   * Special NOACC versions of Monitor_nD and MCPL_output are included. These may be used in the case
     of large event datasets, allowing more than 2e9 events to be stored.
   
 Platforms:
  - We still support 64bit Windows 10/11 on Intel, all recent 64bit macOS including 13.0 Ventura on
   both Intel and Apple Silicon/M1 processors. Debian-based distros on Intel and Arm, Fedora on Intel.
  - On macOS and Windows we now bundle a Mambaforge Python with the installation.

 Infrastructure:
  - During the last McStas-McXtrace hackathon we worked on "standardizing" our CMake code, which will
    mean smoother integration with other codes and easier configuration and build of our code for
    various platforms. Try it out if you like, directly from the McCode repo.
    (https://github.com/McStasMcXtrace/McCode/)

We hope you will enjoy this new release!!!


CHANGES in 1.7.1

 McXtrace 1.7.1 provides minor incremental improvements and fixes various minor issues with McXtrace 1.7.1.
 McXtrace 1.7.1 is meant to be the LAST version in the 1.x series.

 Please start your migration to 3.x:
 - McXtrace 1.7.1 is meant to be the "last update" to the 1.x series, sharing a subset of tool features
   with McXtrace 3.1.
 - The Wiki has a dedicated section on McXtrace 1.x -> McXtrace 3.x conversion that includes:
   * A nomenclature list containing short descriptions of new concepts and important keywords
     in McXtrace 3.x and OpenACC / CUDA code in general.
   * A document outlining the most importand differences between 1.x and 3.x.
   * A guide for 1.x -> 3.x instrument conversion.
   * A guide for 1.x -> 3.x component conversion.
 - If you are still in trouble, please write us a GitHub issue or an email to mcxtrace-users@mcxtrace.org

 Thanks:
 - Thanks to all members of the joint McStas-McXtrace team, you guys ROCK!
 - Our joint hackathon in November brought lots of goodies to our user base!

 Fixes of issues from last 1.x release:
 - A large number of issues from 1.7 were addressed, see the relevant GitHub issues for details:
   - https://github.com/McStasMcXtrace/McCode/issues?q=is%3Aissue+is%3Aclosed+label%3Amcxtrace-1.7

 Documentation & guides:
 - The component pages now include an extra column in the parameter-table. When filling in
   this column with wanted values, plus filling the entry-boxes for AT, ROTATED and instance
   name, pressing "Generate" will put a code-snipet for your component instance directly on
   your computer clipboard, for easy transfer to the mcgui editor or any other editor of choice!
 - mxdoc has been made "less picky" wrt. component and instrument structure for a more robust
   experience.
 - mxgui has a new "Docs" button for easier access to the generated mcdoc pages (that give easy
   access to components, instruments, manuals, datafiles and more.
   
 Installation:
 - As usual, our install docs are available on the McCode GitHub page at
   https://github.com/McStasMcXtrace/McCode/tree/master/INSTALL-McXtrace
 - The meta-packages for Debian/Ubuntu and Fedora are named
   mcxtrace-suite-python for 1.x and mcxtrace-suite-python-ng 'next generation' the 3.x
   series packages


 Interoperability with other codes:
 - We have worked on the interface with MCPL and a mechanism was developed to automatically detect the
   location using the mcpl-config util. In practice this happens prior/during to the code-generation step,
   see below under mxrun. Thanks to Thomas Kittelmann (ESS) for your help in this area.

 Tools:
 - mxrun has a new solution to support 3 new keywords CMD(), ENV() and GETPATH() through the
   DEPENDENCY line as collected by the code-generator.
   * CMD() is used to call mcpl-config to probe lib and include-paths and
     use them in compiler-directives.
     (Examples available in MCPL_input.comp and MCPL_output.comp)
   * ENV() may evaluate an evironment variable
     (No specific example available yet)
   * GETPATH() can be used to locate the absolute path to e.g. an input file in the $MCXTRACE
     folder hierachy. Component writers may use this mechanism for a low-barrier and platform-
     independent way to access inputfiles.
     (An example is available in Test_MCPL_input.instr)
 - mxrun has a new triplet of switches (D1/D2/D3) that can be used to easily set defines from
   the commandline. For instance --D1=SOMETHING will mean -DSOMETHING when compiling. Note that
   setting these --D flags implies recompilation (-c).
 - mxdoc has been made "less picky" wrt. component and instrument structure for a more robust
   experience. Also, rendered component pages now include an extra column in the parameter-table.
   When filling in this column with wanted parameter-values, plus filling the entry-boxes for
   AT, ROTATED and instance name, pressing "Generate" will put a code-snipet for your component
   instance directly on your computer clipboard, for easy transfer to the mxgui editor or any
   other editor of choice!
 - mxplot (-pyqtgraph) has received a nice update with an infobar at the bottom of the window.
   The infobar is updated with coordinates of the cursor on the active plot, meaning that you
   can easily determine the coordinates of e.g. a peak. The code has also received a number of
   bugfixes relating to colorbars, the order of monitor output in overviews etc.
   Thanks to Tobias Weber (ILL) for your work on mxplot.
 - The new mxdisplay-cad variant has come along, and is currently included in the form of a
   technology-preview. The code uses the Python module cadquery (https://github.com/CadQuery/cadquery)
   and is able to write e.g. STEP or STL output. For now, resolving the required dependencies is
   left to the user, but we foresee that this tool will mature over the coming releases.
   Thanks to Greg Tyler (ESS) for contributing this tool.

 Components and Instruments:
 - The Isotropic_Sqw sample which can be used to model structure and dynamics in isotropic
   materials, such as powders and liquids has been added. The component is developed by
   Emmanuel Farhi and also exists in the McStas code. The component is currently in
   "Experimental" state in McXtrace.
 - Multiple new SOLEIL instruments have been added, thanks to lots of work from Antoine Pado,
   Stephane Bac and Emmanuel Farhi:
   * SOLEIL_ANATOMIX.instr tomography beam-line
   * SOLEIL_DISCO.instr in the imaging mode
   * SOLEIL_MARS.instr in the XRD mode
   * SOLEIL_PX2a.instr protein crystallography beam-line
 - The AstroX toolbox for simulating X-ray telescopes has been included as a special component
   category. 
 - Lens_elliptical.comp fixed
 - Grating_reflect.comp fixed, and created a test for it.
 - Udated/fixed Mirror_elliptic.comp and created a test for it.
 - Beamline ssrl 11-2 (in it's unfocused and uncollimated mode) added (related to work done on glitches). 
 - Czerny_Turner instrument created.
 - Single_crystal component, corrected absorption cross-section. 

 Libraries and other runtime code:
 - A flaw was spotted in our NeXus implementation in the case of event lists: A small chunk-size
   of (1,6) was used, leading to slow I/O and lots of size-overhead. Our new NeXus files are
   generally a factor of (at least) 2-3 smaller and load much faster in e.g. Mantid.
 - MCPL library from T. Kittelmann (ESS) is now included at v. 1.6.1
   
 Platforms:
  - We still support 64bit Windows 10/11 on Intel, all recent 64bit macOS including 13.0 Ventura on
   both Intel and Apple Silicon/M1 processors. Debian-based distros on Intel and Arm, Fedora on Intel.
  - On macOS and Windows we now bundle a Mambaforge Python with the installation.

 Infrastructure:
  - During the last McStas-McXtrace hackathon we worked on "standardizing" our CMake code, which will
    mean smoother integration with other codes and easier configuration and build of our code for
    various platforms. Try it out if you like, directly from the McCode repo.
    (https://github.com/McStasMcXtrace/McCode/)

We hope you will enjoy this new release!!!


CHANGES in 3.0

McXtrace 3.0 is the first release in the 3.0 series with a completely rewritten code-generator and thereby
support for GPU-acceleration through the OpenACC programming model.

THANKS:
- Thanks to: all members of the team (and also to the McStas team), for pulling together to make this possible.
- Thanks to the mentors at the GPU Hackathons that really made this happen
- Thanks to NVIDIA for making the hackathons happen

INSTALLATION:
- Installation instructions for McXtrace-3.0 and support libraries may be found on our the McCode github-site:
https://github.com/McStasMcXtrace/McCode/tree/master/Install_McXtrace-3.x
- OpenACC acceleration is at present available out of the box on Linux. On windows it is possible to target GPU-acceleration
through Windows Subsystem For Linux v2: WSL2. The present McXtrace-3.0 implementation relies the concept managed memory, which
is at the time of writing only supported by the NVHPC-kit, downloadable from https://developer.nvidia.com/hpc-sdk

Main new features and changes:
1. New code-generation scheme based on functions instead of #defines, which brings
  - Highly improved interfacing to regular debugging tools. 
  - Much improved compilation-times, the code is better suited for modern compilers
  - In most cases a speed-up of order 20%
  - The xray _particle is now represented by a struct
  - The component types and instances are also represented by structs
  - In the generic TRACE function of a given component type, the _comp var is
    short-hand for "whatever the component instance is"
  - New instrument section of USERVARS %{ double example_flag; %} which enriches
    the _particle struct to allow per particle extra information to be tracked.
  - In component DECLARE blocks, assignments can no longer be done and all declarations
    must be listed independently, i.e double a; is OK, double a,b; is not. Variables in
    this scope are automatically so-called "OUTPUT PARAMETERS" (we may deprecate that
    keyword completely for the official McXtrace 3.0 release)
  - Components no longer support DEFINITION PARAMETERS, instead the SETTING PARAMETERS
    must be used, which now includes a vector and string type supplementing the (default)
    double/MCNUM and int types.
  - New macros have been added for
        - INSTRUMENT_GETPAR(parameter_name)
        - COMP_GETPAR(component, parameter_name) which is similar to the legacy MC_GETPAR
        - MC_GETPAR3(component_class, component_name,parameter_name)
        - The function particle_getvar(_particle,"variable",success) provides component-access
        to the instrument USERVARS, e.g. in Monitor_nD.
        - Further, the new cogen implements support for Nvidia GPU's, for details see point 2 below.
2. Support for OpenACC acceleration on NVIDIA GPU's on Linux systems
  - #pragma driven, inserted by the code-generation, but also implemented in libs and comps
  - Speedups measured using top-notch NVIDIA V100 datacenter cards are in the range of 10-600 with
    respect to a single-core of a modern CPU. See ( 
  - Platform support / compiler configuration:
    - Required compiler for GPU/OpenACC: NVIDIA HPC SDK 20.x or newer. Community edition works fine. Older compiler
    may work in most cases.
    - Required GPU hardware: NVIDIA Tesla card + configured driver
    - Windows: Possible with WSL 2.0.
    - macOS: At this point UNSUPPORTED for OpenACC since NVIDIA does not ship a package for
      this platform.
    - Linux: Full acceleration support with GPU, and with CPU/multicore.
  - Install the compiler and put it on your system PATH. Install and configure Nvidia drivers for your card.
  - We hope that GCC will offer better support for OpenACC in the near future.
  - Tool support
    - On Linux and macOS mxrun is preconfigured so that mxrun -c --openacc compiles with:
    - Linux: nvc -ta:tesla,managed,deepcopy -DOPENACC
    - Linux: You may configure for use on CPU/multicore via: nvc -ta:multicore -DOPENACC
    - The --funnel option can be used to launch the FUNNEL simulation flow, see description below.
  - For both of the above, adding -Minfo:accel will output verbose information on parallelisation
  - In mxgui, the mxrun --openacc configuration can be selected via the preferences
  - Both mxgui and mxrun allow combining --openacc and --mpi if you have multiple GPU's available.
    The n'th mpi process will attempt to use the k'th GPU, where k = #available GPU's % #MPI nodes.
3. Special McStas 3.0 grammar for mixed CPU/GPU mode:
  - A "FUNNEL" mode has been added, which allows
    - Mixed GPU/CPU mode, were sections of the instrument are executed on each device type, with
      copying of photon-bunches back and forth.
    - When this instrument grammar is specified, it signifies that the component should be executed
      on CPU rather than GPU.
       CPU SPLIT 10 COMPONENT Sample = Something()
    - Sections before and after that are not marked CPU will be executed on GPU.
    - If a component includes the NOACC token in the component header, the CPU-mode is forced
      through the compilation, as it signifies that the component does NOT support GPU. This is
      for the time being the case for Undulator & Union_master
4. Interopreability between McXtrace 1.7 and 3.0
   Simulations of the two version are able to interchange particles through the MCPL_output/input
   components, i.e. through event data files.
5. Limitations:
   - Some components: those that rely on external libraries such as GSL and the Union subsystem, cannot run GPU.
   These may however be run CPU-side in FUNNEL-mode. In terms of the undulator component which tends to be one
   of the first components (if not the first), the program flow is mostly indentical to normal.
   - We do not ship an updated manual for McXtrace 3.0. Instead you may rely on online docs from the 
   McCode github wiki: https://github.com/McStasMcXtrace/McCode/wiki

Tools:
   - The perl-suite of tools are no longer actively supported. They may still work.

Platforms:
   - We support the platforms Debian/Ubuntu and Fedora for Linux, 64 bit Windows 10, and recent 64 bit macOS (big Sur and
   newer). For FreeBSD you may build from source, an entry into the ports system is pending.

Components and Instruments:
   - Most components and instruments work out of the box. See https://new-nightly.mcxtrace.org for details.
   - Monitor_nD.comp: the uservar utility should now be given a string insted of a token name to measure a USERVAR entity
   tagged onto the photon. The string is used to look-up the name of the variable which should be declared in the USERVARS-section
   of the instrument file.

 
CHANGES in 1.7

This is mainly an bugfix/update release. 

1. Improved installation scripts
        1. Installs cleanly on Mac silicon 
2. Updated examples:
        1. MAXIV_DanMAX_pxrd2d.instr
3. New examples:
        1. SOLEIL ROCKS beamline.
        2. ESRF BM29 skeleton beamline.
        3. Example of Air-scattering block.
        4. Test example for the GROUP langnuage feature
        5. Union demo test example
        6. New Example of Compton scattering union process.
3. Updated Components
	1. Lens_parab_Cyl_rough.comp, Lens_parab_rough.comp, Lens_Kinoform.comp: documentation issues
	2. Mirror.comp: documentation update
	3. Mirror_curved.comp, Mirror_elliptic.comp: Use reflectivity library
	4. Mirror_toroid.comp: Fix for stable handling of reflectivity file
	12. Absorption_sample.comp: Fix inner/outer volume logic 
	13. Source_genesis13.comp, Source_simplex.comp: Documentation issues.
5. Updated libraries:
        1. Reflectivity-lib has a series of bugfixes. 
4. New tools:
        1. Test tool for component writers' convenience.
        2. Script for generating reflectivity files.
5. License change:
        The release includes a switch to the GPLv3-license for McXtrace. The underlying reason for this 
        is to help collaboration wih the Debian project.

CHANGES in 1.6

1. Union concept for X-ray
        A subsystem under McXtrace that separate physics from geometry, 
        thereby allowing multiscattering processes from object to object.
2. Scatter logger subsystem
        A concept to allow quantification of parasitic scattering from e.g. mirror substrate.
3. New Components
        Sources, Source_div_quasi.comp - quasi-stochastic sampled set divergence source.
        Samples, Abs_objects.comp - A set of absorbing objects

        Misc, Scatter_logger.comp - The set of components defining the scatter logger interface.  
        Misc, Scatter_logger_stop.comp 
        Misc, Scatter_log_iterator.comp
        Misc, Scatter_log_iterator_stop.comp
        Misc, Shape.comp - Inactive shape, to embellish instrument display, e.g. a flight tube. 
        
        Optics, Grating_trans.comp - Linear transmission grating 
        Optics, Lens_CRL_RTM.comp - 1D-compound refractive lens based of the ray transfer matrix method

        Union, Union_master.comp - Set of components defining the Union subsystem.
        Union, Union_cylinder.comp 
        Union, Union_sphere.comp
        Union, Union_make_material.comp
        Union, Union_box.comp
        Union, Compton_xrl_process.comp
        Union, Incoherent_process.comp
        Union, Union_logger_2D_space.comp
        Union, Union_logger_1D.comp
        ...and more...

        Contrib, Bragg_crystal_simple.comp - Simple, easy-to-use reflective crystal.
4. Many new test-examples and bug fixes.
        Refer to new-nightly.mcxtrace.org for daily tests
5. New example instruments
        Test_mirror_parabolic.instr - Template instrument for the parabolic reflector. 
        Test_Detector_pn.instr - Templat/test instrument for a detector with quantum efficiency.
        Test_grating_trans.instr - Template transmission grating instrument
        Focal_pt_monitor.instr - Template for setting up direct measurement of focal point.
        NBI_Lab_TOMO.instr - Laboratory tomography setup.
        Airport_scannerII.instr - Lab-based large scale tomograhy setup with multiple off-objects
        Union_incoherent.instr - Examples that shows how to use Union.
        Union_geom_demo.instr 
        Template_DCM.instr - a template for how to set up a double crystal monochromator.
        Template_Johann_spec.instr - template for a Johann spectrometer (such as FXE@E-XFEL) 
        Template_Scatter_log_losses.instr - template for logging losses in a mirror
        Test_source_spectra.instr

6. A GUI feature to connect the McXtrace GUI with your editor of choice.
7. Many updates to existing beamline models.

CHANGES in 1.5

1. Standardized reflectivity library, making it much simpler to deal with reflectivity files
2. The shipped MCPL-library has been updated
3. Updated and streamlines the installation procedure - such that windows and Mac installs are now (almost completely sandboxed).
4. New components:
        1. Bragg_crystal (replacing Perfect_crystal)
        2. Bragg_crystal_BC
        3. Laue_crystal_BC
        4. Reflective grating
        5. SAXS_samples series
        6. Attenuating_mask
        7. Phi_monitor: Phase monitor.
5. Updates to components:
        1. Mirror comp - can now be either in the xz or yz-plane
        2. Virtual option to Mask-component - used to artifically add a 2D-pattern to a subsequent component.
        3. Mirrors now use the reflectivity library
        4. Source_lab: Add Ag as an anode material
        5. Source_lab: Default is now to use lorentzian line-shapes
        6. Undulator: Easier to compile with GSL on windows
        7. PowderN Major improvement in the way incoherent scattering is handled
        8. Monitors: Monitors now have a nowritefile option to dynamically disable monitor (useful if an instrument has a lot of monitors)
        9. PSD_monitor: pixel count can now be set by a variable
        10. PSD_monitor_coh: optionally rays are now treated as if they hit a pixel center. This avoids convoluting the pixel shape in the interference pattern
        11. MCPL: encode polarization vector 
6. several new example and updated instruments:
        1. MAXIV_Bloch
        2. MAXIV_DanMax
        3. DBD_IBM_Si_analyzer
        4. PDB_BT
        5. Template_Johann_spectrometer
        6. Updated Test instruments (many of these can be used as examples)
7. Updates to the GUI - including autoplot options and improved stability of the plotting and display subsystems
8. Performance improvement to MPI
9. Better performance on reading datafiles (especially on windows)
10. Updated manual
... and more

CHANGES in 1.4

1. Source_pt, Source_flat, Source_gaussian, and Source_div now behave in the same manner wrt. phase. The relevant parameters
are randomphase and phase. If randomphase is !=0 the phase is completely random, if ==0 the value of phase is used.
2. EPSD_monitor: Has a parameter nE which denotes a number of energy bins. if >1 the monitor will output a number of files
each corresponding to an energy bin.
3. Lens_parab, Lens_parab_Cyl The functionality of the _rough versions of these components have been merged into the main components
and the _rough versions themselves retired.
4. Support for binary file dump of photons in the mcpl-format is added.
5. On debian class systems, McXtrace now installs to /usr/share to be more standards compliant.
6. New Components:
    sources/Undulator.comp: Undulator model based on Kim, 1989, “Characteristics of synchrotron radiation”
    
    samples/Incoherent.comp: Model sample of an incoherent scatterer
    samples/Polycrystal.comp: Polycrystal sample based on Single_crystal formalism
    samples/SasView_model.comp: All samples included in the SasModels module of SasView.
    	Currently does not take in absorption into account
    
    misc/Air.comp: A “box” full of Air that may scatter-
    misc/Focus.comp: Adds resampling to any component. I.e. causes the preceding object to become a secondary source.
    misc/MCPL_input.comp: Interface components to read/write MCPL-format files. 
    misc/MCPL_output.comp

    monitors/DivE_monitor.comp
    monitors/DivPos_monitor.comp
    monitors/Divergence_monitor.comp

    optics/Bragg_crystal.comp: Superseeds Perfect_Crystal
    optics/Bragg_crystal_bent.comp: Bent crystal model
    optics/Capillary.comp: Capillary tube with reflecting walls.
 
    optics/Collimator_linear.comp: Ideal collimator models
    optics/Collimator_radial.comp
    optics/Mirror.comp: Simple flat mirror component
    optics/Mirror_toroid.comp: Toroidal mirror
 
    contrib/Detector_pn.comp: Detector model with quantum efficiency.
    contrib/SAXS/SAXSCurve.comp: A set of SAXS-sample models
    contrib/SAXS/SAXSCylinders.comp
    contrib/SAXS/SAXSEllipticCylinders.comp
    contrib/SAXS/SAXSLiposomes.comp
    contrib/SAXS/SAXSNanodiscsFast.comp
    contrib/SAXS/SAXSNanodiscsWithTagsFast.comp
    contrib/SAXS/SAXSNanodiscsWithTags.comp
    contrib/SAXS/SAXSNanodiscs.comp
    contrib/SAXS/SAXSPDBFast.comp
    contrib/SAXS/SAXSPDB.comp
    contrib/SAXS/SAXSQMonitor.comp
    contrib/SAXS/SAXSShells.comp
    contrib/SAXS/SAXSSpheres.comp

7. Example Instrument simulations:
  - Full model of proposed DanMAX beamline
  - Pump_probe_solvent: Example of disordered scattering in solution
  - SAXS_saxlab: Laboratory SAXS setup with Montel optic
  - template_1Slit_Diff & template_2Slit_Diff: examples of raytracing with coherent interference effects.
  - ESRF_ID01: Microdiffraction beamline with polycrystal sample
  - templateSasView: Example of using the (experimental) SasView interface 
  ... and various Unit test/Example instruments

8. New python/Qt based GUI/plotting tool
9. Other Changes/additions:
9. PowderN: incoherent scattering (computed from tables)
10. Curved Bragg monochromator crystal
    Major improvements to the flat Bragg monochromator crystal
11. Output in the NeXus-format.
12. Data files can be read only once and reused by other components.