Overview
Contents
Overview¶
McStas / McXtrace simulations¶
McStasScript is a python API for writing and running McStas / McXtrace simulations. These are sister packages meant for simulation of neutron and x-ray scattering instrumentation respectively and share a common syntax. The packages are used widely in the field and come with a large repository of components that describe smaller parts of the beamline. The community of users contribute such components to the packages, and they have in this way grown over the years.
McStas and McXtrace simulations are described by an instrument file which is a custom language built on C. Here a number of components are placed in simulated space to describe the physical instrument, along with a number of monitors that record the properties of the beam. The instrument file is used to generate a c code, which is then compiled to an executable on the users system. The simulation itself is a Monte Carlo ray-tracing simulation that tracks individual rays from the source, through the instrument, through any scattering events and deposits the rays intensity onto any monitors along the way.
McStasScript¶
McStasScript provides a pythonic alternative to writing the instrument file as a textfile in the simulation meta language. A McStasScript instrument object is create which in turn can generate the instrument file and perform the simulation. The user still has to understand the underlying software and logic in McStas / McXtrace to make meaningful simulations, and it is possible to add snippets of C code to the generated instrument, so some C knowledge is still an advantage.
McStasScript is developed with the intent of use in Jupyter Notebooks, with for example available widgets for performing the simulation and plotting the results. The package can be used in python scripts, but won’t have the interfaces.
McStasScript is developed under PaNOSC and specifically WP5 on simulations. Our collected github repo can be found here. McStasScript uses libpyvinyl which imposes some standards on how parameters are handled along with the syntax for constructing and running the simulation, and thus using McStasScript is similar to other packages that follow this standard.
The instrument class¶
The central class of McStasScript is the McCode_instr class that describes the instrument object, from which both the McStas_instr and McXtrace_instr classes are derived. The McCode_instr class itself inherits from the libpyvinyl BaseCalculator that provides some basic functionality, such as loading from and dumping to file.
Upon initialization an instrument object reads the available component database along with components in the work directory, and from this information can guide the user and check for errors. When adding a component to the instrument, a component object is returned which can then be customized further.
It is possible to add practically anything to the instrument object that one would normally add to a instrument file, which includes parameters, declared variables, lines of initialize code and lines of finally code.
The instrument object has methods for adjusting settings of the simulation such as the number of rays to simulate and setting the parameters. The backengine method runs the currently specified simulation, and loads the data into the data attribute which can the be accessed by the user. The data is loaded as a McStasData object for each monitor output, these objects contain the data itself as numpy arrays and relevant metadata.
Component objects¶
Component objects belong to an instrument but are returned to the user whenever one is added to an instrument. At that point a custom class is generated for this kind of component, and the attributes will correspond to the parameters of the component. This is achieved by reading the McStas components in the users installation of McStas, and any custom components they may have added. Because the attributes correspond with the component parameters, it is not allowed to create new attributes in component objects, and in this way any misspelling of parameters are caught early. Since the component object is aware of the allowed inputs, it can provide help and for example show when any required parameters have not yet been specified.
Plotting tools¶
McStasScript includes tools for plotting the resulting simulation data, providing a convenient way to quickly see the results from the performed simulation.