Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc review 2023 03 round 01 #869

Merged
merged 12 commits into from
Aug 20, 2023
1 change: 1 addition & 0 deletions doc/CHANGELOG.rst
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Next version
* Patch to compile with gcc-13 (#882)
* Tweak conda environment for Windows build to avoid conflicting gtest headers (#888)
* Restrict cython version for MOAB (#893)
* Various documentation updates (#869)

v3.2.2
====================
Expand Down
34 changes: 21 additions & 13 deletions doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,20 +11,31 @@ DAGMC: Direct Accelerated Geometry Monte Carlo

|

.. image:: https://circleci.com/gh/svalinn/DAGMC.svg?style=shield
:target: https://circleci.com/gh/svalinn/DAGMC
:height: 20
:width: 90
:align: left
.. image:: https://github.com/svalinn/DAGMC/actions/workflows/linux_build_test.yml/badge.svg?branch=develop
:target: https://github.com/svalinn/DAGMC/actions/workflows/linux_build_test.yml

.. image:: https://github.com/svalinn/DAGMC/actions/workflows/mac_build_test.yml/badge.svg?branch=develop
:target: https://github.com/svalinn/DAGMC/actions/workflows/mac_build_test.yml

.. image:: https://github.com/svalinn/DAGMC/actions/workflows/windows_build_test.yml/badge.svg?branch=develop
:target: https://github.com/svalinn/DAGMC/actions/workflows/windows_build_test.yml

.. image:: https://github.com/svalinn/DAGMC/actions/workflows/docker_publish.yml/badge.svg?branch=develop
:target: https://github.com/svalinn/DAGMC/actions/workflows/docker_publish.yml

.. image:: https://anaconda.org/conda-forge/dagmc/badges/version.svg
:target: https://anaconda.org/conda-forge/dagmc

|

Direct Accelerated Geometry Monte Carlo (DAGMC) is a software package that
allows users to perform Monte Carlo radiation transport directly on CAD models.

DAGMC has been integrated into a variety of Monte Carlo radiation codes
including MCNP5_, MCNP6_, Geant4_, FLUKA_, Tripoli4_, OpenMC_, and Shift_. There are also
efforts planned to integrate DAGMC into other codes such as Serpent2_, Phits_, and FRENSIE_.
DAGMC has been integrated into a variety of Monte Carlo radiation codes.
Implementations are actively maintained from OpenMC_ and MCNP6_. Implementations
are occasionally updated for Geant4_ and FLUKA_. The last implementation for
Shift_ is still used internally at ORNL. An implementation is available for
MCNP5_. DAGMC was demonstrated in Tripoli4_ in 2010, but not maintained.

DAGMC currently relies on using the commercial solid modeling software Cubit_ (or its
`government-use counterpart <https://cubit.sandia.gov>`_ available from
Expand All @@ -48,15 +59,12 @@ materials and other geometry-related information.
gallery/gallery

.. _CNERG: https://cnerg.github.io
.. _MOAB: https://press3.mcs.anl.gov/sigma/moab-library
.. _MOAB: https://sigma.mcs.anl.gov/moab-library/
.. _Cubit: https://coreform.com/products/coreform-cubit/
.. _MCNP5: https://laws.lanl.gov/vhosts/mcnp.lanl.gov/mcnp5.shtml
.. _MCNP5: https://mcnp.lanl.gov
.. _MCNP6: https://mcnp.lanl.gov
.. _Geant4: https://geant4.cern.ch
.. _FLUKA: http://www.fluka.org/fluka.php
.. _Tripoli4: https://rsicc.ornl.gov/codes/ccc/ccc8/ccc-806.html
.. _Shift: https://meitner.ornl.gov/doe-codes/shift
.. _Serpent2: http://montecarlo.vtt.fi
.. _OpenMC: https://docs.openmc.org/en/latest/index.html
.. _Phits: https://phits.jaea.go.jp
.. _FRENSIE: https://github.com/FRENSIE/FRENSIE
39 changes: 13 additions & 26 deletions doc/install/dependencies.rst
Original file line number Diff line number Diff line change
Expand Up @@ -79,45 +79,32 @@ Redhat linux users can do likewise with:
MOAB installation
~~~~~~~~~~~~~~~~~

As of DAGMC version 3.1, MOAB version 5.1.0 or higher is required. The following
As of DAGMC version 3.2, a MOAB version between 5.1.0 and 5.3.0 is required. The following
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why does this need to be between 5.10 and 5.3.0 again? I thought we could also support newer versions.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are significant changes in v5.4.0 that are causing some build fail. We need to resolve this issue before proceeding to v5.4 MOAB.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see. Perhaps we could clarify that the restriction to 5.4.0 is only for Windows if that is the case?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our CI is stuck on 5.3.0 until we can figure out all the issues. It's a limitation for Ubuntu as well for 20.04 and older - seems to work on 22.04, though.

With all those caveats, it's seems best to stick with 5.3.0 for now

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough! Strange though... hopefully we can figure it out someday.

commands can be used to download MOAB from its `source repository <MOAB_>`_ and
set it up for building.
::

$ cd $HOME/dagmc_bld
$ mkdir -p MOAB/bld
$ cd MOAB
$ git clone https://bitbucket.org/fathomteam/moab
$ cd moab
$ git checkout Version5.1.0
$ autoreconf -fi
$ cd ..
$ ln -s moab src

If you have followed the source install route, then the following commands
should be used to build MOAB.
$ git clone --depth 1 -b 5.3.0 https://bitbucket.org/fathomteam/moab

To build moab using the default packages:
::

$ cd bld
$ ../src/configure --enable-optimize \
--enable-shared \
--disable-debug \
--with-hdf5=$HOME/dagmc_bld/HDF5 \
--prefix=$HOME/dagmc_bld/MOAB
$ cmake ../moab -DENABLE_HDF5=ON -DHDF5_ROOT=${hdf5_install_dir} \
-DCMAKE_BUILD_TYPE=Release \
-DENABLE_PYMOAB=ON \
-DENABLE_BLASLAPACK=OFF \
-DENABLE_FORTRAN=OFF \
-DCMAKE_INSTALL_PREFIX=$HOME/dagmc_bld/MOAB \
-DBUILD_SHARED_LIBS=ON \
-DCMAKE_INSTALL_RPATH=${hdf5_install_dir}/lib:${moab_install_dir}/lib
$ make
$ make check
$ make install

If you have followed the package manager install route, then the following
configure command should be used to build MOAB.
::

$ ../src/configure --enable-optimize \
--enable-shared \
--disable-debug \
--with-hdf5=/usr/lib/x86_64-linux-gnu/hdf5/serial \
--prefix=$HOME/dagmc_bld/MOAB

Making sure the dependencies were installed correctly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -137,7 +124,7 @@ successfully.
$ which h5ls
$ which mbconvert

If you have installed the dependencies corretly, you are now ready to
If you have installed the dependencies correctly, you are now ready to
`install DAGMC <dagmc.html>`_.

.. _HDF5: http://www.hdfgroup.org/HDF5
Expand Down
20 changes: 14 additions & 6 deletions doc/install/index.rst
Original file line number Diff line number Diff line change
@@ -1,17 +1,23 @@
DAGMC installation overview
===========================

This document describes the DAGMC installation process. Before you begin, you
should know that the following will be required:
This document describes the DAGMC installation process.

If you plan to use OpenMC_, you can follow `their installation
instructions <OpenMC_install>`_ with
DAGMC built-in.

Otherwise, before you begin, you should know that the following will be
required:

1. A basic understanding of Unix/Linux shell commands and how to navigate
the shell, for installing dependencies and DAGMC enabled codes
2. MCNP5_ or MCNP6_ source code, if you intend to install DAG-MCNP5 or
DAG-MCNP6
2. MCNP6_ source code, if you intend to install DAG-MCNP6 (or MCNP5_ source
code for DAG-MCNP5)
3. FLUKA_, if you intend to install FluDAG
4. Coreform Cubit_ for the creation of geometry
shimwell marked this conversation as resolved.
Show resolved Hide resolved

Once you have the basic pre-requisite peices in place you can proceed to the
Once you have the basic pre-requisite pieces in place you can proceed to the
DAGMC installation. There are three main steps in the DAGMC installation:

.. toctree::
Expand All @@ -26,7 +32,9 @@ DAGMC-based radiation transport calculations. The
`User's Guide <../usersguide/index.html>`_ will guide you through the workflow
options available to you.

.. _MCNP5: https://laws.lanl.gov/vhosts/mcnp.lanl.gov/mcnp5.shtml
.. _MCNP5: https://mcnp.lanl.gov
.. _MCNP6: https://mcnp.lanl.gov
.. _FLUKA: http://www.fluka.org/fluka.php
.. _Cubit: https://coreform.com/products/coreform-cubit/
.. _OpenMC_install: https://docs.openmc.org/en/stable/quickinstall.html
.. _OpenMC: https://docs.openmc.org/en/latest/index.html
43 changes: 43 additions & 0 deletions tmp
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope - definitely not!!!

Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
#ifndef _DAGMC_LOGGER
#define _DAGMC_LOGGER

#include <iostream>
#include <string>

class DagMC_Logger {
public:
DagMC_Logger(int _verbosity = 1) { set_verbosity(_verbosity); };

void set_verbosity(int val) {
int verbosity_min = 0;
int verbosity_max = 1;
if (val < verbosity_min || val > verbosity_max)
warning("Invalid verbosity value " + std::to_string(val) +
" will be set to nearest valid value.");
val = std::min(std::max(verbosity_min, val), verbosity_max);
verbosity = val;
}

int get_verbosity() const { return verbosity; };

void message(const std::string& msg, int lvl = 1, bool newline = true) const {
if (lvl > verbosity) return;
std::cout << msg;

if (newline) std::cout << "\n";
}

void warning(const std::string& msg, int lvl = 1, bool newline = true) const {
message("WARNING: " + msg, -1, newline);
}

void error(const std::string& msg, bool newline = true) const {
std::cerr << "ERROR: " << msg;
if (newline) std::cerr << "\n";
}

private:
int verbosity{1};
};

#endif