| Name | ncrystal JSON |
| Version |
4.0.2
JSON |
| download |
| home_page | None |
| Summary | Library for thermal neutron transport in crystals and other materials. |
| upload_time | 2025-02-19 13:18:43 |
| maintainer | None |
| docs_url | None |
| author | NCrystal developers (Thomas Kittelmann, Xiao Xiao Cai) |
| requires_python | >=3.8 |
| license | The Apache 2.0 license is reproduced in the following. See the NOTICE file for important details of how it applies to the distributed NCrystal code. Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
NCrystal : A library for thermal neutron transport in crystals and other materials
----------------------------------------------------------------------------------
This is a source distribution of NCrystal, a library and associated tools which
enables calculations for Monte Carlo simulations of thermal neutrons in crystals
and other materials. Supported is a range of physics including both coherent,
incoherent, elastic and inelastic scatterings in a wide range of materials,
including crystal powders, mosaic single crystals, layered single crystals,
amorphous solids, and liquids. Multiphase materials or isotopically enriched
material are supported as well, and the framework furthermore supports
phase-contrast (SANS) physics. Written in C++, interfaces and infrastructure
facilitate integration into existing simulation frameworks such as OpenMC
(https://docs.openmc.org/), Geant4 (https://geant4.web.cern.ch/) or McStas
(http://mcstas.org/), as well as allowing direct usage from C++, C or Python
code or via command-line tools. While the C++ library is designed with a high
degree of flexibility in mind for developers, typical end-user configuration is
deliberately kept simple and uniform across various applications and APIs - this
for instance allows tuning and validation of a particular material configuration
to be performed in one tool before it is then deployed in another.
In addition to code and tools, the NCrystal distribution also includes a set of
validated data files, covering many crystals important at neutron scattering
facilities. For more information about the properties and validity of each file,
users are referred to the dedicated page at:
https://github.com/mctools/ncrystal/wiki/Data-library
Supporting compilation with all modern C++ standards (C++11 and later), the code
has no third-party dependencies and is available under the highly liberal open
source Apache 2.0 license (see NOTICE and LICENSE files for usage conditions and
the INSTALL file for build and installation instructions). NCrystal was
developed in close collaboration by Xiao Xiao Cai (DTU, ESS) and Thomas
Kittelmann (ESS) and was supported in part by the European Union's Horizon 2020
research and innovation programme under grant agreement No 676548 (the
BrightnESS project) and 951782 (the HighNESS project).
A very substantial effort went into developing NCrystal. If you use it for your
work, we would appreciate it if you would use the following primary reference in
your work:
X.-X. Cai and T. Kittelmann, NCrystal: A library for thermal neutron
transport, Computer Physics Communications 246 (2020) 106851,
https://doi.org/10.1016/j.cpc.2019.07.015
For work benefitting from elastic physics (e.g. Bragg diffraction), we
furthermore request that you additionally also use the following reference in
your work:
T. Kittelmann and X.-X. Cai, Elastic neutron scattering models
for NCrystal, Computer Physics Communications 267 (2021) 108082,
https://doi.org/10.1016/j.cpc.2021.108082
For work benefitting from our inelastic physics, we furthermore request that you
additionally also use the following reference in your work:
X.-X. Cai, T. Kittelmann, et. al., "Rejection-based sampling of inelastic
neutron scattering", Journal of Computational Physics 380 (2019) 400-407,
https://doi.org/10.1016/j.jcp.2018.11.043
The rest of this file gives a brief overview of the manners in which NCrystal
capabilities can be utilised. Further instructions and documentation, along with
the latest version of NCrystal, can be found at https://mctools.github.io/ncrystal/
Using the NCrystal installation from the command-line
-----------------------------------------------------
After installing NCrystal and having sourced the setup.sh script mentioned in
the INSTALL file, you can run any of the commands from the $NCRYSTALDIR/bin
directory, which includes example code as well as the "nctool" command. Start by
reading the usage instructions:
$> nctool --help
Assuming you chose to install data files, you can try to let NCrystal load one
of the data files found in $NCRYSTALDIR/data/ (or provide the absolute path to a
data file downloaded from https://github.com/mctools/ncrystal/wiki/Data-library)
and either dump the derived information to the terminal...:
$> nctool --dump 'Al_sg225.ncmat;temp=10C'
Note that this included a choice of temperature. If you leave it out, it will
usually default to room temperature (20C). You can also plot (powder)
cross-sections and sampled scatter angles with:
$> nctool 'Al_sg225.ncmat;temp=10C'
Using the NCrystal installation from C++, C or Python code
-----------------------------------------------------------------------------
If you wish to use NCrystal from Python code, there is no special setup needed,
assuming NCrystal was installed correctly (cf. INSTALL.md). If you on the other
hand wish to use NCrystal from your compiled C++ or C code, you must put
appropriate build flags. The recommended way is using CMake to do this (see next
section), but otherwise you must ensure that the NCrystal header files are in
your compiler's include path, and that the NCrystal library is linked
correctly. Here are some examples of how this could for instance be done, with a
C and a C++ app respectively:
```
export LDFLAGS="${LDFLAGS:-} -Wl,-rpath,$(ncrystal-config --show libdir) $(ncrystal-config --show libpath)"
export CFLAGS="${CFLAGS:-} -I$(ncrystal-config --show includedir)"
export CXXFLAGS="${CXXFLAGS:-} -I$(ncrystal-config --show includedir)"
cc -std=c11 ${LDFLAGS} ${CFLAGS} my_c_code.c -o my_c_app
c++ -std=c++17 ${LDFLAGS} ${CXXFLAGS} my_cpp_code.cpp -o my_cpp_app
```
Then, in your code you can access the relevant APIs with with statements like:
```
#include "NCrystal/NCrystal.hh" // C++ code, core NCrystal
#include "NCrystal/ncrystal.h" // C code
import NCrystal ## Python code
```
In the ./examples/ directory of your NCrystal distribution that you got after
downloading and unpacking the NCrystal source tar-ball, you will find small
examples of code using NCrystal. For C++/C, there is currently no documentation
beyond the header files and examples. In the case of Python, there is integrated
documentation available via the usual "help" function, accessed with:
```
import NCrystal
help(NCrystal)
```
There are also several jupyter-lab notebooks showcasing the NCrystal python API
at https://github.com/mctools/ncrystal-notebooks
Configuring CMake-based projects to use NCrystal
------------------------------------------------
Assuming NCrystal was built and installed via CMake, it is possible and
recommended for client projects to simply use NCrystal as a CMake package in
order to correctly build their C/C++ code which depends on the NCrystal C++ or C
APIs.
Depending on where NCrystal was installed on the system, it might be necessary
to let CMake know about it via the usual mechanisms (for instance passing
-DNCrystal_DIR=/path/to/ncrystalinstall as an argument to cmake on the command
line).
CMake code for a small project using NCrystal might look like the following
(assume that exampleapp.cc below includes the NCrystal/NCrystal.hh header):
cmake_minimum_required(VERSION 3.10...3.26)
project(MyExampleProject LANGUAGES CXX)
execute_process( COMMAND "ncrystal-config" "--show" "cmakedir"
OUTPUT_VARIABLE NCrystal_DIR
OUTPUT_STRIP_TRAILING_WHITESPACE )
find_package(NCrystal 4.0.0 REQUIRED)
add_executable(exampleapp "${PROJECT_SOURCE_DIR}/exampleapp.cc")
target_link_libraries( exampleapp NCrystal::NCrystal )
install( TARGETS exampleapp DESTINATION bin )
Note that the "execute_process( ... )" command above is optional, but is
required before the code can work in an environment where the NCrystal CMake
modules are not automatically injected into the CMake package search path (this
notably includes NCrystal installed via "pip install ncrystal").
Using the NCrystal with Geant4
------------------------------
The instructions for the NCrystal-Geant4 bindings are currently being
updated. Once complete, they will appear on
https://github.com/mctools/ncrystal-geant4
Using NCrystal with OpenMC
--------------------------
Using NCrystal materials in OpenMc is supported since OpenMC release 13.3, and
uses a nice simple syntax in the Python API:
```
mat = openmc.Material.from_ncrystal('Polyethylene_CH2.ncmat;temp=50C')
```
which when used in a complete OpenMC project, results in the following material
entry being added to the `materials.xml` produced:
```
<material cfg="Polyethylene_CH2.ncmat;temp=50C" id="1" temperature="323.15">
<density units="g/cm3" value="0.92" />
<nuclide ao="0.66656284" name="H1" />
<nuclide ao="0.00010382666666666666" name="H2" />
<nuclide ao="0.32964066666666664" name="C12" />
<nuclide ao="0.003692666666666666" name="C13" />
</material>
```
Temperature, density and material composition were all created automatically
from the cfg-string, and the cfg-string itself was also encoded. Upon launching
the simulation with the OpenMC binary executable `openmc`, it will handle the
material as usual, except that low-energy neutron scattering physics (currently
defined as ($E<5eV$) will be provided by the algorithms in NCrystal.
A few issues might warrent attention:
1. If you try to assemble the above xml manually, it is rather unlikely that you
will get the base densities and compositions right. It is safest to stick to
let the Python API compose the xml for you.
2. After creation with `mat=openmc.Material.from_ncrystal(..)`, you can not use
the usual OpenMC API to modify the material density, temperature, or
composition. So be sure to reflect the final desired material inside the
NCrystal cfg-string.
3. The OpenMC binaries must have been built with NCrystal support, or your job
will fail once you launch the simulation (you can check for this by running
the command `openmc -v`). Specifically (as documented on
https://docs.openmc.org/en/stable/usersguide/install.html) you must supply
the CMake flag `cmake -DOPENMC_USE_NCRYSTAL=on ..` (and make sure NCrystal is
available already). Note: we have agreement from OpenMC developers to enable
NCrystal support by default in the conda-forge version of OpenMC. So in "the
near future" (summer/fall 2023) conda users will always have NCrystal support
available in OpenMC.
For more information, please consult the user guide at:
* https://docs.openmc.org/
In particular note the sections concerning installation and usage of NCrystal in
the sections:
* https://docs.openmc.org/en/stable/usersguide/install.html
* https://docs.openmc.org/en/stable/usersguide/materials.html
Using NCrystal with McStas
--------------------------
NOTE: The following discussion concerns the modern McStas 3 branch, and might in
particular not be 100% accurate for releases earlier than McStas 3.3 (probably
OK for v3.2 though).
You can use NCrystal in two ways in McStas. You can either use it for advanced
studies with the McStas Union sub-system through the NCrystal_process component,
or it can be used via the dedicated NCrystal_sample.comp which is simpler but
less feature rich. In any case, the McStas instrument file compilation will need
to build against NCrystal, and it uses the ncrystal-config command to figure out
the correct settings for doing so. Thus, you can always invoke "ncrystal-config
-s" to find out if you have the right NCrystal installation available and
active. Depending on how you installed McStas, NCrystal is most likely already
available. If not, you can try one of the following ways of enabling it:
```
$> conda install conda-forge::ncrystal [if you are in a conda-forge env]
$> python3 -mpip install ncrystal [for non-conda users]
```
It is beyond the scope for this README to provide a full documentation of
McStas, or the Union sub-system, but if you are using McStasScript to compose
your instruments, you can add NCrystal materials into your Union geometry using
code like:
```
from mcstasscript.tools.ncrystal_union import add_ncrystal_union_material
add_ncrystal_union_material(instr, name="myAl", cfgstr="Al_sg225.ncmat;temp=10C")
```
This creates the material and gives it the name "myAl", which you must later
attach to a particular Union volume, like for instance:
```
myvol.set_parameters(radius=0.01, yheight=0.01,
material_string='"myAl"', priority=1)
```
If you are instead hand-editing your instrument files, you can generate code
which defines Union materials from an NCrystal cfg-string by invoking:
```
$> python3 -mNCrystal.mcstasutils --union myAl 'Al_sg225.ncmat;temp=250K'
```
It should be noted that McStas 3.3 also provides a new SHELL syntax which can
also be used to faciliate this invocation from with a classic .instr file.
On the other hand, the dedicated NCrystal_sample.comp component, embeds NCrystal
material simulations into simple shapes (currently boxes, cylinders and
spheres), and can be used for components representing samples, filters or
monochromators, entrance windows, etc. The component is since McStas v3.3 part
of the McStas release itself, and can be used in a .instr file - for instance if
you wish to set up an r=1cm sphere with powdered sapphire you would write:
COMPONENT mysample = NCrystal_sample(cfg="Al2O3_sg167_Corundum.ncmat",radius=0.01)
AT (0, 0, 0) RELATIVE PREVIOUS
For more documentation about the NCrystal_sample component, run:
$> mcdoc NCrystal_sample
Or consult the documentation online at
https://www.mcstas.org/download/components/
Raw data
{
"_id": null,
"home_page": null,
"name": "ncrystal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "NCrystal developers (Thomas Kittelmann, Xiao Xiao Cai)",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e3/e8/ba29450f03e9453ec62ea139c763b6b40a07438b87d4a4aec23383d39b16/ncrystal-4.0.2.tar.gz",
"platform": null,
"description": "NCrystal : A library for thermal neutron transport in crystals and other materials\n----------------------------------------------------------------------------------\n\n\n\n\n\nThis is a source distribution of NCrystal, a library and associated tools which\nenables calculations for Monte Carlo simulations of thermal neutrons in crystals\nand other materials. Supported is a range of physics including both coherent,\nincoherent, elastic and inelastic scatterings in a wide range of materials,\nincluding crystal powders, mosaic single crystals, layered single crystals,\namorphous solids, and liquids. Multiphase materials or isotopically enriched\nmaterial are supported as well, and the framework furthermore supports\nphase-contrast (SANS) physics. Written in C++, interfaces and infrastructure\nfacilitate integration into existing simulation frameworks such as OpenMC\n(https://docs.openmc.org/), Geant4 (https://geant4.web.cern.ch/) or McStas\n(http://mcstas.org/), as well as allowing direct usage from C++, C or Python\ncode or via command-line tools. While the C++ library is designed with a high\ndegree of flexibility in mind for developers, typical end-user configuration is\ndeliberately kept simple and uniform across various applications and APIs - this\nfor instance allows tuning and validation of a particular material configuration\nto be performed in one tool before it is then deployed in another.\n\nIn addition to code and tools, the NCrystal distribution also includes a set of\nvalidated data files, covering many crystals important at neutron scattering\nfacilities. For more information about the properties and validity of each file,\nusers are referred to the dedicated page at:\n\n https://github.com/mctools/ncrystal/wiki/Data-library\n\nSupporting compilation with all modern C++ standards (C++11 and later), the code\nhas no third-party dependencies and is available under the highly liberal open\nsource Apache 2.0 license (see NOTICE and LICENSE files for usage conditions and\nthe INSTALL file for build and installation instructions). NCrystal was\ndeveloped in close collaboration by Xiao Xiao Cai (DTU, ESS) and Thomas\nKittelmann (ESS) and was supported in part by the European Union's Horizon 2020\nresearch and innovation programme under grant agreement No 676548 (the\nBrightnESS project) and 951782 (the HighNESS project).\n\nA very substantial effort went into developing NCrystal. If you use it for your\nwork, we would appreciate it if you would use the following primary reference in\nyour work:\n\n X.-X. Cai and T. Kittelmann, NCrystal: A library for thermal neutron\n transport, Computer Physics Communications 246 (2020) 106851,\n https://doi.org/10.1016/j.cpc.2019.07.015\n\nFor work benefitting from elastic physics (e.g. Bragg diffraction), we\nfurthermore request that you additionally also use the following reference in\nyour work:\n\n T. Kittelmann and X.-X. Cai, Elastic neutron scattering models\n for NCrystal, Computer Physics Communications 267 (2021) 108082,\n https://doi.org/10.1016/j.cpc.2021.108082\n\nFor work benefitting from our inelastic physics, we furthermore request that you\nadditionally also use the following reference in your work:\n\n X.-X. Cai, T. Kittelmann, et. al., \"Rejection-based sampling of inelastic\n neutron scattering\", Journal of Computational Physics 380 (2019) 400-407,\n https://doi.org/10.1016/j.jcp.2018.11.043\n\nThe rest of this file gives a brief overview of the manners in which NCrystal\ncapabilities can be utilised. Further instructions and documentation, along with\nthe latest version of NCrystal, can be found at https://mctools.github.io/ncrystal/\n\n\n\nUsing the NCrystal installation from the command-line\n-----------------------------------------------------\n\nAfter installing NCrystal and having sourced the setup.sh script mentioned in\nthe INSTALL file, you can run any of the commands from the $NCRYSTALDIR/bin\ndirectory, which includes example code as well as the \"nctool\" command. Start by\nreading the usage instructions:\n\n$> nctool --help\n\nAssuming you chose to install data files, you can try to let NCrystal load one\nof the data files found in $NCRYSTALDIR/data/ (or provide the absolute path to a\ndata file downloaded from https://github.com/mctools/ncrystal/wiki/Data-library)\nand either dump the derived information to the terminal...:\n\n$> nctool --dump 'Al_sg225.ncmat;temp=10C'\n\nNote that this included a choice of temperature. If you leave it out, it will\nusually default to room temperature (20C). You can also plot (powder)\ncross-sections and sampled scatter angles with:\n\n$> nctool 'Al_sg225.ncmat;temp=10C'\n\n\n\nUsing the NCrystal installation from C++, C or Python code\n-----------------------------------------------------------------------------\n\nIf you wish to use NCrystal from Python code, there is no special setup needed,\nassuming NCrystal was installed correctly (cf. INSTALL.md). If you on the other\nhand wish to use NCrystal from your compiled C++ or C code, you must put\nappropriate build flags. The recommended way is using CMake to do this (see next\nsection), but otherwise you must ensure that the NCrystal header files are in\nyour compiler's include path, and that the NCrystal library is linked\ncorrectly. Here are some examples of how this could for instance be done, with a\nC and a C++ app respectively:\n\n```\nexport LDFLAGS=\"${LDFLAGS:-} -Wl,-rpath,$(ncrystal-config --show libdir) $(ncrystal-config --show libpath)\"\nexport CFLAGS=\"${CFLAGS:-} -I$(ncrystal-config --show includedir)\"\nexport CXXFLAGS=\"${CXXFLAGS:-} -I$(ncrystal-config --show includedir)\"\ncc -std=c11 ${LDFLAGS} ${CFLAGS} my_c_code.c -o my_c_app\nc++ -std=c++17 ${LDFLAGS} ${CXXFLAGS} my_cpp_code.cpp -o my_cpp_app\n```\n\nThen, in your code you can access the relevant APIs with with statements like:\n\n```\n#include \"NCrystal/NCrystal.hh\" // C++ code, core NCrystal\n#include \"NCrystal/ncrystal.h\" // C code\nimport NCrystal ## Python code\n```\n\nIn the ./examples/ directory of your NCrystal distribution that you got after\ndownloading and unpacking the NCrystal source tar-ball, you will find small\nexamples of code using NCrystal. For C++/C, there is currently no documentation\nbeyond the header files and examples. In the case of Python, there is integrated\ndocumentation available via the usual \"help\" function, accessed with:\n\n```\nimport NCrystal\nhelp(NCrystal)\n```\n\nThere are also several jupyter-lab notebooks showcasing the NCrystal python API\nat https://github.com/mctools/ncrystal-notebooks\n\n\n\nConfiguring CMake-based projects to use NCrystal\n------------------------------------------------\n\nAssuming NCrystal was built and installed via CMake, it is possible and\nrecommended for client projects to simply use NCrystal as a CMake package in\norder to correctly build their C/C++ code which depends on the NCrystal C++ or C\nAPIs.\n\nDepending on where NCrystal was installed on the system, it might be necessary\nto let CMake know about it via the usual mechanisms (for instance passing\n-DNCrystal_DIR=/path/to/ncrystalinstall as an argument to cmake on the command\nline).\n\nCMake code for a small project using NCrystal might look like the following\n(assume that exampleapp.cc below includes the NCrystal/NCrystal.hh header):\n\n cmake_minimum_required(VERSION 3.10...3.26)\n project(MyExampleProject LANGUAGES CXX)\n execute_process( COMMAND \"ncrystal-config\" \"--show\" \"cmakedir\"\n OUTPUT_VARIABLE NCrystal_DIR\n OUTPUT_STRIP_TRAILING_WHITESPACE )\n find_package(NCrystal 4.0.0 REQUIRED)\n add_executable(exampleapp \"${PROJECT_SOURCE_DIR}/exampleapp.cc\")\n target_link_libraries( exampleapp NCrystal::NCrystal )\n install( TARGETS exampleapp DESTINATION bin )\n\nNote that the \"execute_process( ... )\" command above is optional, but is\nrequired before the code can work in an environment where the NCrystal CMake\nmodules are not automatically injected into the CMake package search path (this\nnotably includes NCrystal installed via \"pip install ncrystal\").\n\n\n\nUsing the NCrystal with Geant4\n------------------------------\n\nThe instructions for the NCrystal-Geant4 bindings are currently being\nupdated. Once complete, they will appear on\nhttps://github.com/mctools/ncrystal-geant4\n\n\n\nUsing NCrystal with OpenMC\n--------------------------\n\nUsing NCrystal materials in OpenMc is supported since OpenMC release 13.3, and\nuses a nice simple syntax in the Python API:\n\n```\nmat = openmc.Material.from_ncrystal('Polyethylene_CH2.ncmat;temp=50C')\n```\n\nwhich when used in a complete OpenMC project, results in the following material\nentry being added to the `materials.xml` produced:\n\n```\n<material cfg=\"Polyethylene_CH2.ncmat;temp=50C\" id=\"1\" temperature=\"323.15\">\n <density units=\"g/cm3\" value=\"0.92\" />\n <nuclide ao=\"0.66656284\" name=\"H1\" />\n <nuclide ao=\"0.00010382666666666666\" name=\"H2\" />\n <nuclide ao=\"0.32964066666666664\" name=\"C12\" />\n <nuclide ao=\"0.003692666666666666\" name=\"C13\" />\n</material>\n```\n\nTemperature, density and material composition were all created automatically\nfrom the cfg-string, and the cfg-string itself was also encoded. Upon launching\nthe simulation with the OpenMC binary executable `openmc`, it will handle the\nmaterial as usual, except that low-energy neutron scattering physics (currently\ndefined as ($E<5eV$) will be provided by the algorithms in NCrystal.\n\nA few issues might warrent attention:\n\n1. If you try to assemble the above xml manually, it is rather unlikely that you\n will get the base densities and compositions right. It is safest to stick to\n let the Python API compose the xml for you.\n2. After creation with `mat=openmc.Material.from_ncrystal(..)`, you can not use\n the usual OpenMC API to modify the material density, temperature, or\n composition. So be sure to reflect the final desired material inside the\n NCrystal cfg-string.\n3. The OpenMC binaries must have been built with NCrystal support, or your job\n will fail once you launch the simulation (you can check for this by running\n the command `openmc -v`). Specifically (as documented on\n https://docs.openmc.org/en/stable/usersguide/install.html) you must supply\n the CMake flag `cmake -DOPENMC_USE_NCRYSTAL=on ..` (and make sure NCrystal is\n available already). Note: we have agreement from OpenMC developers to enable\n NCrystal support by default in the conda-forge version of OpenMC. So in \"the\n near future\" (summer/fall 2023) conda users will always have NCrystal support\n available in OpenMC.\n\nFor more information, please consult the user guide at:\n\n* https://docs.openmc.org/\n\nIn particular note the sections concerning installation and usage of NCrystal in\nthe sections:\n\n* https://docs.openmc.org/en/stable/usersguide/install.html\n* https://docs.openmc.org/en/stable/usersguide/materials.html\n\n\n\nUsing NCrystal with McStas\n--------------------------\n\nNOTE: The following discussion concerns the modern McStas 3 branch, and might in\nparticular not be 100% accurate for releases earlier than McStas 3.3 (probably\nOK for v3.2 though).\n\nYou can use NCrystal in two ways in McStas. You can either use it for advanced\nstudies with the McStas Union sub-system through the NCrystal_process component,\nor it can be used via the dedicated NCrystal_sample.comp which is simpler but\nless feature rich. In any case, the McStas instrument file compilation will need\nto build against NCrystal, and it uses the ncrystal-config command to figure out\nthe correct settings for doing so. Thus, you can always invoke \"ncrystal-config\n-s\" to find out if you have the right NCrystal installation available and\nactive. Depending on how you installed McStas, NCrystal is most likely already\navailable. If not, you can try one of the following ways of enabling it:\n\n```\n$> conda install conda-forge::ncrystal [if you are in a conda-forge env]\n$> python3 -mpip install ncrystal [for non-conda users]\n```\n\nIt is beyond the scope for this README to provide a full documentation of\nMcStas, or the Union sub-system, but if you are using McStasScript to compose\nyour instruments, you can add NCrystal materials into your Union geometry using\ncode like:\n\n```\nfrom mcstasscript.tools.ncrystal_union import add_ncrystal_union_material\nadd_ncrystal_union_material(instr, name=\"myAl\", cfgstr=\"Al_sg225.ncmat;temp=10C\")\n```\n\nThis creates the material and gives it the name \"myAl\", which you must later\nattach to a particular Union volume, like for instance:\n\n```\nmyvol.set_parameters(radius=0.01, yheight=0.01,\n material_string='\"myAl\"', priority=1)\n```\n\nIf you are instead hand-editing your instrument files, you can generate code\nwhich defines Union materials from an NCrystal cfg-string by invoking:\n\n```\n$> python3 -mNCrystal.mcstasutils --union myAl 'Al_sg225.ncmat;temp=250K'\n```\n\nIt should be noted that McStas 3.3 also provides a new SHELL syntax which can\nalso be used to faciliate this invocation from with a classic .instr file.\n\nOn the other hand, the dedicated NCrystal_sample.comp component, embeds NCrystal\nmaterial simulations into simple shapes (currently boxes, cylinders and\nspheres), and can be used for components representing samples, filters or\nmonochromators, entrance windows, etc. The component is since McStas v3.3 part\nof the McStas release itself, and can be used in a .instr file - for instance if\nyou wish to set up an r=1cm sphere with powdered sapphire you would write:\n\nCOMPONENT mysample = NCrystal_sample(cfg=\"Al2O3_sg167_Corundum.ncmat\",radius=0.01)\nAT (0, 0, 0) RELATIVE PREVIOUS\n\nFor more documentation about the NCrystal_sample component, run:\n\n$> mcdoc NCrystal_sample\n\nOr consult the documentation online at\nhttps://www.mcstas.org/download/components/\n",
"bugtrack_url": null,
"license": "The Apache 2.0 license is reproduced in the following. See the NOTICE file for important details of how it applies to the distributed NCrystal code. Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. \"License\" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. \"Licensor\" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. \"Legal Entity\" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, \"control\" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. \"You\" (or \"Your\") shall mean an individual or Legal Entity exercising permissions granted by this License. \"Source\" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. \"Object\" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. \"Work\" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). \"Derivative Works\" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. \"Contribution\" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, \"submitted\" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as \"Not a Contribution.\" \"Contributor\" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a \"NOTICE\" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets \"[]\" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same \"printed page\" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ",
"summary": "Library for thermal neutron transport in crystals and other materials.",
"version": "4.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/mctools/ncrystal/issues",
"Homepage": "https://mctools.github.io/ncrystal/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d9cf6b058648ba38755e787a4c0932cb954596385b33cfd0a0f8f18f4c3ce9c0",
"md5": "ad9881ebf6389ebebb815799170178f8",
"sha256": "18bba5a9c69c03c91d0821c9c3cc3fc2394f4d67d48b6bf00befb8b90c3bec79"
},
"downloads": -1,
"filename": "ncrystal-4.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad9881ebf6389ebebb815799170178f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15020,
"upload_time": "2025-02-19T13:17:58",
"upload_time_iso_8601": "2025-02-19T13:17:58.061667Z",
"url": "https://files.pythonhosted.org/packages/d9/cf/6b058648ba38755e787a4c0932cb954596385b33cfd0a0f8f18f4c3ce9c0/ncrystal-4.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3e8ba29450f03e9453ec62ea139c763b6b40a07438b87d4a4aec23383d39b16",
"md5": "f40108bce6be3e43c6736bd7fa842d0a",
"sha256": "563f847f6421d99b88be385b5865ca3f66bd0754af8b1af4a7eb3981b56f0b55"
},
"downloads": -1,
"filename": "ncrystal-4.0.2.tar.gz",
"has_sig": false,
"md5_digest": "f40108bce6be3e43c6736bd7fa842d0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16755,
"upload_time": "2025-02-19T13:18:43",
"upload_time_iso_8601": "2025-02-19T13:18:43.121760Z",
"url": "https://files.pythonhosted.org/packages/e3/e8/ba29450f03e9453ec62ea139c763b6b40a07438b87d4a4aec23383d39b16/ncrystal-4.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-19 13:18:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mctools",
"github_project": "ncrystal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ncrystal"
}
