Merge pull request #125 from njoy/release

ENDFtk v0.2.0 Release

Author: whaeck

.github/workflows/ContinuousIntegration.yml

@@ -2,10 +2,10 @@
 name: Continuous Integration
 
 # This workflow is triggered on pushes and pull requests to the repository.
-on: 
+on:
   push:
     branches: '**'
-  pull_request: 
+  pull_request:
     branches: 'master'
 
 jobs:
@@ -14,23 +14,31 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-18.04, macos-10.15 ]
-        cxx: [ g++-9, clang++ ]
+        cxx: [ clang++ ]
         build_type: [ Debug, Release ]
 
     steps:
     - name: which CXX
       run: |
-        which ${{matrix.cxx}} 
+        which ${{matrix.cxx}}
         ${{matrix.cxx}} --version
     - uses: actions/checkout@v2
     - name: mkdir bin
-      run: mkdir bin 
+      run: mkdir bin
     - name: cmake
-      run: cmake -D CMAKE_CXX_COMPILER=`which ${{matrix.cxx}}` -D CMAKE_BUILD_TYPE=${{matrix.build_type}} ..  
+      run: cmake -DPYTHON_EXECUTABLE=$(which python3) -D CMAKE_CXX_COMPILER=`which ${{matrix.cxx}}` -D CMAKE_BUILD_TYPE=${{matrix.build_type}} ..
       working-directory: ./bin
     - name: make
       run: make -j2
       working-directory: ./bin
     - name: ctest
       run: ctest -j2
       working-directory: ./bin
+    - name: make ENDFtk.python
+      run: make ENDFtk.python -j2
+      working-directory: ./bin
+    - name: python -m unittest
+      run: |
+        cp ../bin/*.so .
+        python3 -m unittest discover -v -p "Test*"
+      working-directory: ./python

.gitignore

@@ -29,7 +29,9 @@
 *.app
 
 bin
+build
 subprojects
+dependencies
 
 # emacs
 *~

.gitmodules

@@ -52,6 +52,12 @@ endif()
 # Project targets
 ########################################################################
 
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# ENDFtk : library
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+include_directories( src/ )
+
 add_library( ENDFtk INTERFACE
     )
 target_include_directories( ENDFtk INTERFACE src/ )
@@ -64,6 +70,154 @@ target_link_libraries( ENDFtk
     INTERFACE range-v3-adapter
     )
 
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# ENDFtk : python bindings
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+include_directories( python/src/ )
+
+pybind11_add_module( ENDFtk.python
+    EXCLUDE_FROM_ALL
+    python/src/ENDFtk.python.cpp
+    python/src/record/DirectoryRecord.python.cpp
+    python/src/record/TapeIdentification.python.cpp
+    python/src/section/1/TabulatedMultiplicity.python.cpp
+    python/src/section/1/PolynomialMultiplicity.python.cpp
+    python/src/section/1/451.python.cpp
+    python/src/section/1/452.python.cpp
+    python/src/section/1/455.python.cpp
+    python/src/section/1/455/DecayConstants.python.cpp
+    python/src/section/1/455/EnergyIndependentConstants.python.cpp
+    python/src/section/1/455/EnergyDependentConstants.python.cpp
+    python/src/section/1/456.python.cpp
+    python/src/section/1/458.python.cpp
+    python/src/section/1/458/EnergyReleaseComponent.python.cpp
+    python/src/section/1/458/ThermalPointComponents.python.cpp
+    python/src/section/1/458/PolynomialComponents.python.cpp
+    python/src/section/1/458/TabulatedComponents.python.cpp
+    python/src/section/1/460.python.cpp
+    python/src/section/1/460/DiscretePhotonMultiplicity.python.cpp
+    python/src/section/1/460/DiscretePhotons.python.cpp
+    python/src/section/1/460/ContinuousPhotons.python.cpp
+    python/src/section/2/151.python.cpp
+    python/src/section/2/151/Isotope.python.cpp
+    python/src/section/2/151/ScatteringRadius.python.cpp
+    python/src/section/2/151/ResonanceRange.python.cpp
+    python/src/section/2/151/SpecialCase.python.cpp
+    python/src/section/2/151/BreitWignerLValue.python.cpp
+    python/src/section/2/151/ReichMooreLValue.python.cpp
+    python/src/section/2/151/SingleLevelBreitWigner.python.cpp
+    python/src/section/2/151/MultiLevelBreitWigner.python.cpp
+    python/src/section/2/151/ReichMoore.python.cpp
+    python/src/section/2/151/ParticlePairs.python.cpp
+    python/src/section/2/151/ResonanceChannels.python.cpp
+    python/src/section/2/151/ResonanceParameters.python.cpp
+    python/src/section/2/151/NoBackgroundRMatrix.python.cpp
+    python/src/section/2/151/SammyBackgroundRMatrix.python.cpp
+    python/src/section/2/151/FrohnerBackgroundRMatrix.python.cpp
+    python/src/section/2/151/TabulatedBackgroundRMatrix.python.cpp
+    python/src/section/2/151/BackgroundChannels.python.cpp
+    python/src/section/2/151/SpinGroup.python.cpp
+    python/src/section/2/151/RMatrixLimited.python.cpp
+    python/src/section/2/151/UnresolvedEnergyDependentFissionWidthsJValue.python.cpp
+    python/src/section/2/151/UnresolvedEnergyDependentJValue.python.cpp
+    python/src/section/2/151/UnresolvedEnergyIndependentLValue.python.cpp
+    python/src/section/2/151/UnresolvedEnergyDependentFissionWidthsLValue.python.cpp
+    python/src/section/2/151/UnresolvedEnergyDependentLValue.python.cpp
+    python/src/section/2/151/UnresolvedEnergyDependent.python.cpp
+    python/src/section/2/151/UnresolvedEnergyDependentFissionWidths.python.cpp
+    python/src/section/2/151/UnresolvedEnergyIndependent.python.cpp
+    python/src/section/2/152.python.cpp
+    python/src/section/3.python.cpp
+    python/src/section/4.python.cpp
+    python/src/section/4/Isotropic.python.cpp
+    python/src/section/4/LegendreCoefficients.python.cpp
+    python/src/section/4/TabulatedDistribution.python.cpp
+    python/src/section/4/LegendreDistributions.python.cpp
+    python/src/section/4/TabulatedDistributions.python.cpp
+    python/src/section/4/MixedDistributions.python.cpp
+    python/src/section/5.python.cpp
+    python/src/section/5/Parameter.python.cpp
+    python/src/section/5/OutgoingEnergyDistribution.python.cpp
+    python/src/section/5/TabulatedSpectrum.python.cpp
+    python/src/section/5/DistributionFunction.python.cpp
+    python/src/section/5/EffectiveTemperature.python.cpp
+    python/src/section/5/GeneralEvaporationSpectrum.python.cpp
+    python/src/section/5/EvaporationSpectrum.python.cpp
+    python/src/section/5/MaxwellianFissionSpectrum.python.cpp
+    python/src/section/5/WattSpectrum.python.cpp
+    python/src/section/5/MadlandNixSpectrum.python.cpp
+    python/src/section/5/Probability.python.cpp
+    python/src/section/5/PartialDistribution.python.cpp
+    python/src/section/6.python.cpp
+    python/src/section/6/Multiplicity.python.cpp
+    python/src/section/6/DefinedElsewhere.python.cpp
+    python/src/section/6/Unknown.python.cpp
+    python/src/section/6/LAW1/LegendreCoefficients.python.cpp
+    python/src/section/6/LAW1/TabulatedDistribution.python.cpp
+    python/src/section/6/LAW1/KalbachMann.python.cpp
+    python/src/section/6/LAW1/ThermalScatteringData.python.cpp
+    python/src/section/6/ContinuumEnergyAngle.python.cpp
+    python/src/section/6/LAW2/LegendreCoefficients.python.cpp
+    python/src/section/6/LAW2/TabulatedDistribution.python.cpp
+    python/src/section/6/DiscreteTwoBodyScattering.python.cpp
+    python/src/section/6/IsotropicDiscreteEmission.python.cpp
+    python/src/section/6/DiscreteTwoBodyRecoils.python.cpp
+    python/src/section/6/ChargedParticleElasticScattering.python.cpp
+    python/src/section/6/LAW5/LegendreCoefficients.python.cpp
+    python/src/section/6/LAW5/NuclearAmplitudeExpansion.python.cpp
+    python/src/section/6/LAW5/NuclearPlusInterference.python.cpp
+    python/src/section/6/NBodyPhaseSpace.python.cpp
+    python/src/section/6/LAW7/EnergyDistribution.python.cpp
+    python/src/section/6/LAW7/AngularDistribution.python.cpp
+    python/src/section/6/LaboratoryAngleEnergy.python.cpp
+    python/src/section/6/ReactionProduct.python.cpp
+    python/src/section/7/2.python.cpp
+    python/src/section/7/2/CoherentElastic.python.cpp
+    python/src/section/7/2/IncoherentElastic.python.cpp
+    python/src/section/7/2/MixedElastic.python.cpp
+    python/src/section/7/4.python.cpp
+    python/src/section/7/4/EffectiveTemperature.python.cpp
+    python/src/section/7/4/ScatteringLawConstants.python.cpp
+    python/src/section/7/4/AnalyticalFunctions.python.cpp
+    python/src/section/7/4/TabulatedFunctions.python.cpp
+    python/src/section/7/4/ScatteringFunction.python.cpp
+    python/src/section/8/457.python.cpp
+    python/src/section/8/457/AverageDecayEnergies.python.cpp
+    python/src/section/8/457/DecayMode.python.cpp
+    python/src/section/8/457/DecayModes.python.cpp
+    python/src/section/8/457/DiscreteSpectrum.python.cpp
+    python/src/section/8/457/ContinuousSpectrum.python.cpp
+    python/src/section/8/457/DecaySpectrum.python.cpp
+    python/src/section/12.python.cpp
+    python/src/section/12/TotalMultiplicity.python.cpp
+    python/src/section/12/PartialMultiplicity.python.cpp
+    python/src/section/12/Multiplicities.python.cpp
+    python/src/section/12/TransitionProbabilities.python.cpp
+    python/src/section/13.python.cpp
+    python/src/section/13/TotalCrossSection.python.cpp
+    python/src/section/13/PartialCrossSection.python.cpp
+    python/src/file/1.python.cpp
+    python/src/file/2.python.cpp
+    python/src/file/3.python.cpp
+    python/src/file/4.python.cpp
+    python/src/file/5.python.cpp
+    python/src/file/6.python.cpp
+    python/src/file/7.python.cpp
+    python/src/file/8.python.cpp
+    python/src/file/12.python.cpp
+    python/src/file/13.python.cpp
+    python/src/Material.python.cpp
+    python/src/tree/Section.python.cpp
+    python/src/tree/File.python.cpp
+    python/src/tree/Material.python.cpp
+    python/src/tree/Tape.python.cpp
+    )
+target_link_libraries( ENDFtk.python PRIVATE ENDFtk )
+target_compile_options( ENDFtk.python PRIVATE "-fPIC" )
+target_compile_options( ENDFtk.python PRIVATE "-fvisibility=hidden" )
+set_target_properties( ENDFtk.python PROPERTIES OUTPUT_NAME ENDFtk )
+set_target_properties( ENDFtk.python PROPERTIES COMPILE_DEFINITIONS "PYBIND11" )
 
 #######################################################################
 # Top-level Only

CMakeLists.txt

@@ -1,7 +1,116 @@
 ![Continuous Integration](https://github.com/njoy/ENDFtk/workflows/Continuous%20Integration/badge.svg)
 
 # ENDFtk
-Toolkit for reading and interacting with ENDF-6 formatted files
+Toolkit for reading and interacting with ENDF-6 formatted files. This toolkit provides a full C++ library along with python bindings.
+
+## ENDFtk in python
+
+The python bindings for ENDFtk are still work in progress and should be used accordingly. Please report any issues encountered while using the python bindings using the issue tracker on this repository.
+
+### Installing ENDFtk for python
+
+First of all, a user should clone the ENDFtk repository and build the python bindings:
+```
+git clone https://github.com/njoy/ENDFtk
+cd ENDFtk
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ../
+make ENDFtk.python -j8
+```
+
+ENDFtk in python requires python 3.x so you will need to have at least one python 3.x installed. When multiple python versions are installed, it may be beneficial to include ```-DPYTHON_EXECUTABLE=$(which python3)``` in the cmake configuration step so that the default python3 version will be picked. The compilation will produce a dynamic library linked to the python libraries on the user's computer (it'll be named something like `ENDFtk.cpython-37m-darwin.so`). This name will also indicate which version of the python libraries this library is linked to. This is important since you will need to use the associated python version with the ENDFtk python package.
+
+In order to use the ENDFtk python package, the user should make sure that the library is within the python path. This can be done in multiple ways. You can set that up by adding the ENDFtk build path to the python path `$PYTHONPATH` environmental variable on your machine, or by using the following in your python code:
+```
+import sys
+sys.path.append( < ENDFtk-build-path > )
+```
+where `< ENDFtk-build-path >` is the path to the ENDFtk python dynamic library.
+
+When running python in the build directory directly, none of these steps are required.
+
+#### Troubleshooting ####
+
+##### CMake doesn’t detect the right Python version #####
+
+Taken from the pybind11 FAQ.
+
+The CMake-based build system will try to automatically detect the installed version of Python and link against that. When this fails, or when there are multiple versions of Python and it finds the wrong one, delete CMakeCache.txt and then add -DPYTHON_EXECUTABLE=$(which python) to your CMake configure line. (Replace $(which python) with a path to python if your prefer.)
+
+A version of python 3.x is preferred.
+
+##### importError cannot import name <sysconfig> #####
+
+This error sometimes comes up when running the cmake command. This appears to be related to an incomplete/corrupted python installation. It can be rectified by installing the distutils package for the python version that is being used. On a linux system, the following command should install the distutils package:
+```
+sudo apt install python3-distutils
+```
+
+##### cannot find python.h #####
+
+When compiling the python bindings, this error indicates that the python header files and static library we need to link to are not installed on your system. This appears to be related to an incomplete python installation. It can be rectified by installing the python3-dev package (when using python 3). On a linux system, the following command should install the header files:
+```
+sudo apt install python3-dev
+```
+
+### A minimal user guide:
+
+Opening up a tape:
+```
+import ENDFtk
+tape = ENDFtk.tree.Tape.from_file( 'n-001_H_001.endf' )
+```
+
+An `ENDFtk.tree.Tape` effectively indexes the file into available materials, files and sections, which can be parsed at will by the user. The `ENDFtk.tree` submodule also provides an `ENDFtk.tree.Material`, `ENDFtk.tree.File` and `ENDFtk.tree.Section` that the user can look through before parsing the data that is contained in any of these. Parsing the data requires strict adherence to the ENDF6 format but loading the data into an `ENDFtk.tree.Tape` does not. As a result, the `ENDFtk.tree.Tape` is also capable of indexing older ENDF files that do not conform with the ENDF6 standard (tests have shown that we can index files as old as ENDF/B-II).
+
+Once the data is indexed, a user can retrieve an/or parse components (entire materials, files or sections) as follows:
+```
+mat = tape.material(125).parse()
+file = tape.material(125).file(6).parse()
+section = tape.material(125).file(6).section(102).parse()
+```
+
+Accessing the underlying files and sections from parsed materials and sections uses the same function names:
+```
+mat = tape.material(125).parse()
+file = mat.file(6)
+section = file.section(102)
+```
+but since they are already parsed, no need to use the `.parse()` at the end. There are also ENDF-speak equivalents to this for both the `ENDFtk.tree` components as well as the parsed components:
+```
+mat = tape.MAT(125).parse()
+file = mat.MF(6)
+section = file.MT(102)
+```
+
+Every component in ENDFtk has python documentation associated to it that can be viewed using the `help(...)` function in python:
+```
+mat = tape.material(125).parse()
+file = tape.material(125).file(6).parse()
+section = tape.material(125).file(6).section(102).parse()
+help( section ) # this will display the help for an ENDF MF6 section
+```
+
+A simple example for looking at the different secondary particles and the distribution types used for them:
+```
+pu = tape.material(9437).parse()
+for product in pu.file(6).section(102).reaction_products :
+
+    print( product.ZAP, product.LAW )
+```
+
+ENDFtk uses a concept called ranges (aka sequences) so as a result, anything coming out as a range will be a custom type. These custom range types allow subscripting and iteration like any other sequence or list. To convert such a range into a proper list, you can use the `to_list()` method or slicing. This will do a deep copy of primitive types (int, doubles, etc.). It will not do a deep copy for custom types like sections or underlying components. To deep copy a range of custom types, a user can use the `copy()` method on the range.
+
+For example:
+```
+file = tape.material(125).file(6).parse()
+sections = file.sections           # this is the custom range type for MF6 sections
+sections = file.sections.to_list() # this is a list of MF6 sections, with the same memory address as those contained in the file object
+
+sections = file.sections[:]        # this is also a list of MF6 sections, with the same memory address as those contained in the file object
+sections = file.sections.copy()    # this is a list of MF6 sections that have been copied, with a different memory address as those contained in the file object
+```
 
 ## LICENSE
 The software contained in this repository is covered under the associated [LICENSE](LICENSE) file.

README.md

@@ -41,6 +41,12 @@ FetchContent_Declare( range-v3-adapter
     GIT_SHALLOW     TRUE
     )
 
+FetchContent_Declare( pybind11
+    GIT_REPOSITORY  https://github.com/pybind/pybind11
+    GIT_TAG         v2.6.1
+    GIT_SHALLOW     TRUE
+    )
+
 #######################################################################
 # Load dependencies
 #######################################################################
@@ -52,4 +58,5 @@ FetchContent_MakeAvailable(
     hana-adapter
     header-utilities
     range-v3-adapter
+    pybind11
     )

cmake/develop_dependencies.cmake

@@ -30,6 +30,11 @@ FetchContent_Declare( Log
     GIT_TAG         52962b7796afe37ef1d8f7edb4bf9ecb1b868d15
     )
 
+FetchContent_Declare( pybind11
+    GIT_REPOSITORY  https://github.com/pybind/pybind11
+    GIT_TAG         f1abf5d9159b805674197f6bc443592e631c9130 # tag: v2.6.1
+    )
+
 FetchContent_Declare( range-v3-adapter
     GIT_REPOSITORY  https://github.com/njoy/range-v3-adapter
     GIT_TAG         252679d4737c8f755d87c0e1eed6c37394a2ec59
@@ -51,6 +56,7 @@ FetchContent_MakeAvailable(
     hana-adapter
     header-utilities
     Log
+    pybind11
     range-v3-adapter
     spdlog
     )