Merge pull request #2 from openmc-dev/develop

Update alongside openmc-dev

.clang-format

@@ -0,0 +1,108 @@
+---
+Language:        Cpp
+# BasedOnStyle:  Mozilla
+AccessModifierOffset: -2
+AlignAfterOpenBracket: DontAlign
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Right
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass:      false
+  AfterControlStatement: false
+  AfterEnum:       false
+  AfterFunction:   true
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  AfterExternBlock: false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Custom
+BreakInheritanceList: BeforeColon
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: BeforeColon
+BreakStringLiterals: true
+ColumnLimit:     80
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+ConstructorInitializerIndentWidth: 2
+ContinuationIndentWidth: 2
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks:   Preserve
+IncludeCategories:
+  - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
+    Priority:        2
+  - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
+    Priority:        3
+  - Regex:           '.*'
+    Priority:        1
+IncludeIsMainRegex: '(Test)?$'
+IndentCaseLabels: false
+IndentPPDirectives: None
+IndentWidth:     2
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 200
+PointerAlignment: Left
+ReflowComments:  true
+SortIncludes:    true
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: true
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles:  false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Cpp11
+TabWidth:        8
+UseTab:          Never
+...

.gitmodules

@@ -10,3 +10,6 @@
 [submodule "vendor/xtl"]
 	path = vendor/xtl
 	url = https://github.com/xtensor-stack/xtl.git
+[submodule "vendor/fmt"]
+	path = vendor/fmt
+	url = https://github.com/fmtlib/fmt.git

CMakeLists.txt

@@ -9,6 +9,11 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
 # Set module path
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/Modules)
 
+# Allow user to specify <project>_ROOT variables
+if (NOT (CMAKE_VERSION VERSION_LESS 3.12))
+  cmake_policy(SET CMP0074 NEW)
+endif()
+
 #===============================================================================
 # Command line options
 #===============================================================================
@@ -35,18 +40,18 @@ endif()
 #===============================================================================
 if(dagmc)
   find_package(DAGMC REQUIRED)
+  add_library(dagmc-imported INTERFACE IMPORTED)
   link_directories(${DAGMC_LIBRARY_DIRS})
+  target_link_libraries(dagmc-imported INTERFACE ${DAGMC_LIBRARIES})
+  target_include_directories(dagmc-imported INTERFACE ${DAGMC_INCLUDE_DIRS})
+else()
+  set(DAGMC_FOUND false)
 endif()
 
 #===============================================================================
 # HDF5 for binary output
 #===============================================================================
 
-# Allow user to specify HDF5_ROOT
-if (NOT (CMAKE_VERSION VERSION_LESS 3.12))
-  cmake_policy(SET CMP0074 NEW)
-endif()
-
 # Unfortunately FindHDF5.cmake will always prefer a serial HDF5 installation
 # over a parallel installation if both appear on the user's PATH. To get around
 # this, we check for the environment variable HDF5_ROOT and if it exists, use it
@@ -140,6 +145,13 @@ endif()
 
 add_subdirectory(vendor/pugixml)
 
+#===============================================================================
+# {fmt} library
+#===============================================================================
+
+set(FMT_INSTALL ON CACHE BOOL "Generate the install target.")
+add_subdirectory(vendor/fmt)
+
 #===============================================================================
 # xtensor header-only library
 #===============================================================================
@@ -161,7 +173,8 @@ target_link_libraries(xtensor INTERFACE xtl)
 add_subdirectory(vendor/gsl-lite)
 
 # Make sure contract violations throw exceptions
-target_compile_definitions(gsl-lite INTERFACE GSL_THROW_ON_CONTRACT_VIOLATION)
+target_compile_definitions(gsl-lite-v1 INTERFACE GSL_THROW_ON_CONTRACT_VIOLATION)
+target_compile_definitions(gsl-lite-v1 INTERFACE gsl_CONFIG_ALLOWS_NONSTRICT_SPAN_COMPARISON=1)
 
 #===============================================================================
 # RPATH information
@@ -345,12 +358,11 @@ endif()
 # target_link_libraries treats any arguments starting with - but not -l as
 # linker flags. Thus, we can pass both linker flags and libraries together.
 target_link_libraries(libopenmc ${ldflags} ${HDF5_LIBRARIES} ${HDF5_HL_LIBRARIES}
-                      pugixml faddeeva xtensor gsl-lite)
+                      pugixml faddeeva xtensor gsl-lite-v1 fmt::fmt)
 
 if(dagmc)
   target_compile_definitions(libopenmc PRIVATE DAGMC)
-  target_link_libraries(libopenmc ${DAGMC_LIBRARIES})
-  target_include_directories(libopenmc PRIVATE ${DAGMC_INCLUDE_DIRS})
+  target_link_libraries(libopenmc dagmc-imported)
 endif()
 
 #===============================================================================
@@ -380,6 +392,8 @@ add_custom_command(TARGET libopenmc POST_BUILD
 # Install executable, scripts, manpage, license
 #===============================================================================
 
+configure_file(cmake/OpenMCConfig.cmake.in "${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/OpenMCConfig.cmake" @ONLY)
+
 set(INSTALL_CONFIGDIR ${CMAKE_INSTALL_LIBDIR}/cmake/OpenMC)
 install(TARGETS openmc libopenmc faddeeva
   EXPORT openmc-targets
@@ -393,7 +407,7 @@ install(EXPORT openmc-targets
   DESTINATION ${INSTALL_CONFIGDIR})
 
 install(DIRECTORY src/relaxng DESTINATION ${CMAKE_INSTALL_DATADIR}/openmc)
-install(FILES cmake/OpenMCConfig.cmake DESTINATION ${INSTALL_CONFIGDIR})
+install(FILES "${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/OpenMCConfig.cmake" DESTINATION ${INSTALL_CONFIGDIR})
 install(FILES man/man1/openmc.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
 install(FILES LICENSE DESTINATION "${CMAKE_INSTALL_DOCDIR}" RENAME copyright)
 install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

cmake/Modules/FindDAGMC.cmake

@@ -12,7 +12,9 @@ find_path(DAGMC_CMAKE_CONFIG NAMES DAGMCConfig.cmake
           PATHS ENV LD_LIBRARY_PATH
           PATH_SUFFIXES lib Lib cmake lib/cmake
           NO_DEFAULT_PATH)
-
-message(STATUS "Found DAGMC in ${DAGMC_CMAKE_CONFIG}")
-
-include(${DAGMC_CMAKE_CONFIG}/DAGMCConfig.cmake)
+if(DAGMC_CMAKE_CONFIG)
+  message(STATUS "Found DAGMC in ${DAGMC_CMAKE_CONFIG}")
+  include(${DAGMC_CMAKE_CONFIG}/DAGMCConfig.cmake)
+else()
+  message(WARNING "Cound not find DAGMC")
+endif()

cmake/OpenMCConfig.cmake.in

@@ -0,0 +1,20 @@
+get_filename_component(OpenMC_CMAKE_DIR "${CMAKE_CURRENT_LIST_FILE}" DIRECTORY)
+
+find_package(fmt REQUIRED HINTS ${OpenMC_CMAKE_DIR}/../fmt)
+find_package(gsl-lite REQUIRED HINTS ${OpenMC_CMAKE_DIR}/../gsl-lite)
+find_package(pugixml REQUIRED HINTS ${OpenMC_CMAKE_DIR}/../pugixml)
+find_package(xtl REQUIRED HINTS ${OpenMC_CMAKE_DIR}/../xtl)
+find_package(xtensor REQUIRED HINTS ${OpenMC_CMAKE_DIR}/../xtensor)
+if(@DAGMC_FOUND@)
+  find_package(DAGMC REQUIRED HINTS @DAGMC_LIBRARY_DIRS@)
+  add_library(dagmc-imported INTERFACE IMPORTED)
+  target_link_libraries(dagmc-imported INTERFACE ${DAGMC_LIBRARIES})
+  foreach(dir ${DAGMC_LIBRARY_DIRS})
+    target_link_libraries(dagmc-imported INTERFACE "-L${dir}")
+  endforeach()
+  target_include_directories(dagmc-imported INTERFACE ${DAGMC_INCLUDE_DIRS})
+endif()
+
+if(NOT TARGET OpenMC::libopenmc)
+  include("${OpenMC_CMAKE_DIR}/OpenMCTargets.cmake")
+endif()

docs/source/devguide/styleguide.rst

@@ -12,6 +12,14 @@ adding new code in OpenMC.
 C++
 ---
 
+.. important:: To ensure consistent styling with little effort, this project
+    uses `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_. The
+    repository contains a ``.clang-format`` file that can be used to
+    automatically apply the style rules that are described below. The easiest
+    way to use clang-format is through a plugin/extension for your editor/IDE
+    that automatically runs clang-format using the ``.clang-format`` file
+    whenever a file is saved.
+
 Indentation
 -----------
 

docs/source/io_formats/settings.rst

@@ -142,7 +142,7 @@ materials in the problem and is specified using a :ref:`mesh_element`.
 ----------------------------
 
 Determines whether to use event-based parallelism instead of the default
-history-based parallelism. 
+history-based parallelism.
 
   *Default*: false
 
@@ -459,6 +459,15 @@ attributes/sub-elements:
 
     *Default*: None
 
+  :library:
+    If this attribute is given, it indicates that the source is to be
+    instantiated from an externally compiled source function. This source can be
+    as complex as is required to define the source for your problem. The only
+    requirement is that there is a function called ``sample_source()``. More
+    documentation on how to build sources can be found in :ref:`custom_source`.
+
+    *Default*: None
+
   :space:
     An element specifying the spatial distribution of source sites. This element
     has the following attributes:
@@ -591,6 +600,67 @@ attributes/sub-elements:
 
     *Default*: false
 
+.. _custom_source:
+
+Custom Sources
+++++++++++++++
+
+It is often the case that one may wish to simulate a complex source
+distribution, which may include physics not present within OpenMC or to be phase
+space complex. It is possible to define a complex source with an externally
+defined source function that is loaded at runtime. A simple example source is
+shown below.
+
+.. code-block:: c++
+
+   #include "openmc/random_lcg.h"
+   #include "openmc/source.h"
+   #include "openmc/particle.h"
+
+   // you must have external C linkage here
+   extern "C" openmc::Particle::Bank sample_source(uint64_t* seed) {
+     openmc::Particle::Bank particle;
+     // weight
+     particle.particle = openmc::Particle::Type::neutron;
+     particle.wgt = 1.0;
+     // position
+     double angle = 2.0 * M_PI * openmc::prn(seed);
+     double radius = 3.0;
+     particle.r.x = radius * std::cos(angle);
+     particle.r.y = radius * std::sin(angle);
+     particle.r.z = 0.0;
+     // angle
+     particle.u = {1.0, 0.0, 0.0};
+     particle.E = 14.08e6;
+     particle.delayed_group = 0;
+     return particle;
+  }
+
+The above source, creates 14.08 MeV neutrons, with an istropic direction
+vector but distributed in a ring with a 3 cm radius. This routine is
+not particularly complex, but should serve as an example upon which to build
+more complicated sources.
+
+  .. note:: The function signature must be declared to be extern "C".
+
+  .. note:: You should only use the openmc::prn() random number generator
+
+In order to build your external source, you will need to link it against the
+OpenMC shared library. This can be done by writing a CMakeLists.txt file:
+
+.. code-block:: cmake
+
+   cmake_minimum_required(VERSION 3.3 FATAL_ERROR)
+   project(openmc_sources CXX)
+   add_library(source SHARED source_ring.cpp)
+   find_package(OpenMC REQUIRED HINTS <path to openmc>)
+   target_link_libraries(source OpenMC::libopenmc)
+
+After running ``cmake`` and ``make``, you will have a libsource.so (or .dylib)
+file in your build directory. Setting the :attr:`openmc.Source.library`
+attribute to the path of this shared library will indicate that it should be
+used for sampling source particles at runtime.
+
 .. _univariate:
 
 Univariate Probability Distributions