HOWTO: Modifying a McStas 2 component for use under McStas 3

1) Examples of conversion

For examples of converted components please compare the mcstas 3.1 components with their counterparts from mcstas 2.7.1

2) No more DEFINITION parameters

All DEFINITION parameters must be removed.

• normal double/int/numeric ones are no issue, they can be transferred to SETTING parameters without issues
• Similarly, strings are a new supported type in SETTING parameters and can be transferred without issues
• Pointers/lists should be handled with the new vector type. (vector V={a,b,c,d))

3) DECLARE section

The DECLARE section needs adjustments so that

• It only contains declarations without initialisation (init part goes in INITIALIZE)
• variables in the DECLARE section must be present with type on line by line, i.e.

  DECLARE %{
    double a,b;  
  %}

must become

  DECLARE %{
    double a;
    double b;  
  %}

• If there are any functions in DECLARE these must be moved to SHARE.
• If such functions are used in TRACE they, they will need a #pragma acc routine - if they are to be GPU-compatible
• Any function that uses e.g. rand01() inside must have a footprint that includes _class_particle* _particle for forwarding RNG information

4) Handle calls to external libs, if any

If the component is to be used on GPU and uses external libraries in TRACE, one must either

• Find a way to do the library-work in INTIALIZE and/or FINALLY
• Mark the component NOACC in the header - which means that it will execute on CPU only

5) Thread-protect TRACE

… and then there may be further work in TRACE to ensure that DECLARE-parameters are not used to store particle-derived information... A good way to ensure this is that results on CPU and GPU should be identical if run with the same seed.

6) What to do if problems persist

If you still have issues converting your component, feel free to write us an issue (https://github.com/McStasMcXtrace/McCode/issues) or send [email protected] an email including the component in question plus a relevant test-instrument :)