Metadata-Version: 2.5
Name: niess
Version: 0.5.0
Summary: Neutron instruments of the European Spallation Source as calibrated Python objects, emitting McStas instruments and ESS NeXus Structure JSON
Project-URL: Documentation, https://mcdotstar.github.io/niess/
Project-URL: Issues, https://github.com/mcdotstar/niess/issues
Project-URL: Source, https://github.com/mcdotstar/niess
Project-URL: Changelog, https://github.com/mcdotstar/niess/releases
Author-email: Gregory Tucker <gregory.tucker@ess.eu>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.11
Requires-Dist: mccode-antlr>=0.24.0
Requires-Dist: mccode-to-kafka>=0.5.0
Requires-Dist: msgspec>=0.21.1
Requires-Dist: ncrystal>=4.4.6
Requires-Dist: networkx>=3.6.1
Requires-Dist: numpy
Requires-Dist: scipp>=26.8.0
Requires-Dist: scipy
Provides-Extra: docs
Requires-Dist: mkdocstrings-python>=2.0.6; extra == 'docs'
Requires-Dist: zensical==0.0.56; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# niess

[![PyPI - Version](https://img.shields.io/pypi/v/niess.svg)](https://pypi.org/project/niess)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/niess.svg)](https://pypi.org/project/niess)

-----

## Table of Contents

- [Installation](#installation)
- [Documentation](https://mcdotstar.github.io/niess/)
- [License](#license)
- [Motivation](#motivation)
- [Use](#use)

## Installation

```console
pip install niess
```

## License

`niess` is distributed under the terms of the [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) license.

## Motivation
This package is intended to hold information about the **N**eutron **I**nsruments
of the **E**uropean **S**pallation **S**ource for use in defining Monte Carlo 
ray-tracing simulations, file-layout information for use by the ESS
file-writers, and other yet-undefined uses; in a use-agnostic approach.

The information required about an instrument for `McStas` and `NeXusStructure` is
similar but not identical -- the latter attempts to hold all information needed to
produce a valid `NeXus` file, which requires geometry information _inspired_ by the
`McCode` implementation used by `McStas`.

The two uses each have their own vocabulary, and the vocabulary used here is more
closely in line with that of `McCode`. The basic building block of the two uses
is the `Comp` in `McCode` and the `NXclass` in `NeXus`; here the term 'component' is
used to refer to such a building block.
Since there are sometimes slight differences between the 'same' `Comp` and `NXclass` 
in how equivalent information is stored, `niess` is intended to be component-aware as
a single translation between the two is not possible globally.

Rather than attempting to store one implementation or the other, `niess` components
are an independent low-level representation of the properties of a component.
This representation can be written as a dictionary with pre-defined keys, and 
it is intended that serializing to and deserializing from such a representation can be 
used to provide calibrated instrument information to `McStas` and `NeXusStructure`.


## Use

`niess` describes an instrument once, as calibration data, and emits it as a McStas
instrument, ESS NeXus Structure JSON, or CAD geometry:

```python
from mccode_antlr import Flavor
from mccode_antlr.assembler import Assembler
from niess.bifrost import Primary, Tank
from niess.bifrost.parameters import primary_parameters, tank_parameters
from niess.nexus import to_nexus_structure
from niess.nexus.bifrost import BIFROST_REGISTRY

assembler = Assembler('bifrost', flavor=Flavor.MCSTAS)
Primary.from_calibration(primary_parameters()).to_mccode(assembler)
Tank.from_calibration(tank_parameters()).to_mccode(assembler, 'sample_origin')

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

Full documentation, including how to translate an existing McStas `.instr` into a
`niess` submodule and how to write your own NeXus translators, is at
**<https://mcdotstar.github.io/niess/>**.

- [Install and first instrument](https://mcdotstar.github.io/niess/getting-started/)
- [Translate a McStas .instr](https://mcdotstar.github.io/niess/how-to/translate-an-instr/)
- [Build a new instrument submodule](https://mcdotstar.github.io/niess/how-to/new-instrument-submodule/)
- [Produce NeXus Structure JSON](https://mcdotstar.github.io/niess/how-to/nexus-structure/)
