Skip to content

Install and first instrument

pip install niess

niess needs Python 3.11 or newer. It pulls in scipp for units and geometry and mccode-antlr for the McStas side.

Build an instrument

niess.teaching is a small instrument that ships with niess. Building it means turning its calibration into a McStas instrument:

from mccode_antlr import Flavor
from mccode_antlr.assembler import Assembler
from niess.teaching import Primary

assembler = Assembler('teaching', flavor=Flavor.MCSTAS)
Primary.from_calibration().to_mccode(assembler)
instrument = assembler.instrument

instrument is an mccode_antlr object. str(instrument) is the .instr text, and it can be compiled and run by McStas like any other.

Seven components come out of that: the moderator, two guide units, a chopper, a jaw, a monitor and the sample position. So do six run-time parameters — source_lambda_min, source_lambda_max, chopperspeed, chopperdelay, jaw_l and jaw_r — which nothing had to declare by hand. The chopper and the jaw generate their own, and the source wavelengths were given in the calibration as parameter specifications rather than values.

Convert it to NeXus

The same object converts to the JSON the ESS filewriter consumes:

from niess.nexus import to_nexus_structure

structure = to_nexus_structure(assembler.instrument, origin='sample_origin')

and its contents can be inspected without walking dictionaries by hand:

from niess.nexus import find_child, get_attribute

instrument = structure['children'][0]['children'][0]
classes = {
    get_attribute(child, 'NX_class')
    for child in instrument['children'] if child.get('type') == 'group'
}

That yields NXmoderator, NXguide, NXdisk_chopper, NXaperture, NXmonitor and NXcoordinate_system groups. The chopper's rotation_speed is not a number but a link to an NXlog, because chopperspeed is settable at run time — see constants become values, run-time knobs become links.

Or from the command line

$ instr2ns my_instrument.instr --origin sample --indent 2 -o structure.json

instr2ns works on any .instr file, whether or not niess built it.

Next