diff --git a/.gitignore b/.gitignore index 298e9ea2..b84b91a1 100644 --- a/.gitignore +++ b/.gitignore @@ -33,6 +33,7 @@ tmp_* *.core .DS_Store # for mac users **/.DS_Store +**/.idea # test cache .pytest_cache @@ -40,3 +41,8 @@ pytestdebug.log # profiler *.prof + +# Documentation builds +docs/build +docs/source/pythonapi/generated/ + diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..033d2c50 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-20.04 + tools: + python: "3.9" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/source/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements-rtd.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..747ffb7b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements-rtd.txt b/docs/requirements-rtd.txt new file mode 100644 index 00000000..ef3ab378 --- /dev/null +++ b/docs/requirements-rtd.txt @@ -0,0 +1,8 @@ +sphinx==7.2.6 +furo +numpy +numba +matplotlib +scipy +h5py + diff --git a/docs/source/_static/.gitkeep b/docs/source/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/_templates/.gitkeep b/docs/source/_templates/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/_templates/omcfunction.rst b/docs/source/_templates/omcfunction.rst new file mode 100644 index 00000000..4d7ea38a --- /dev/null +++ b/docs/source/_templates/omcfunction.rst @@ -0,0 +1,6 @@ +{{ fullname }} +{{ underline }} + +.. currentmodule:: {{ module }} + +.. autofunction:: {{ objname }} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..42d461a1 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,66 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +import os, sys + +sys.path.insert(0, os.path.abspath("../..")) + + +# On Read the Docs, need to mock any python packages that would require c +from unittest.mock import MagicMock + +MOCK_MODULES = ["mpi4py"] +sys.modules.update((mod_name, MagicMock()) for mod_name in MOCK_MODULES) + + +# -- Project information ----------------------------------------------------- + +project = "MC/DC" +copyright = "2023, Center for Exascale Monte Carlo Neutron Transport (CEMeNT)" +author = "Center for Exascale Monte Carlo Neutron Transport (CEMeNT)" + +# The full version, including alpha/beta/rc tags +release = "0.1" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", +] +autosummary_generate = True + + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "furo" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..126b7755 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,38 @@ +.. MC/DC documentation master file, created by + sphinx-quickstart on Fri Oct 27 14:14:47 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + + +================================= +MC/DC: Monte Carlo Dynamic Code +================================= + +MC/DC is a performant, scalable, and machine-portable Python-based +Monte Carlo neutron transport software in active development +by the `Center for Exascale Monte Carlo Neutron Transport `_ (CEMeNT). + +.. note:: + The project is in the early stages of *very* active development, + not even an alpha release! + + +.. only:: html + + -------- + Contents + -------- + +.. toctree:: + :maxdepth: 1 + + install + pythonapi/index + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 00000000..04cd8056 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,89 @@ +.. _install: + +=================== +Installation Guide +=================== + +This outlines the basic steps to install MC/DC on a local +machine or on HPC machine. + +----------------------------------- +Creating an MC/DC Conda environment +----------------------------------- + +`Conda `_ is an open source package and environment management system +that runs on Windows, macOS, and Linux. It allows for easy installing and switching between multiple +versions of software packages and their dependendencies. +We can't force you to use it, but we do *highly* recommend it, particularly +if you plan on running MC/DC in `numba mode `_. +**The included installation script will fail if executed outside of a conda environment.** + +First, `conda` should be installed with `Miniconda `_ +or `Anaconda `_. HPC instructions: + +`Quartz `_ (LLNL, x86_64), + +.. code-block:: sh + + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh + bash Miniconda3-latest-Linux-x86_64.sh + + +`Lassen `_ (LLNL, IBM Power9), + +.. code-block:: sh + + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-ppc64le.sh + bash Miniconda3-latest-Linux-ppc64le.sh + + +Then create and activate a new conda environment called `mcdc-env` in +which to install MC/DC. This creates an environment with python3.11 +installed. + +.. code-block:: sh + + conda create -n mcdc-env python=3.11 + conda activate mcdc-env + +------------------------------------------- +Installing from Source on Linux or Mac OS X +------------------------------------------- + +All MC/DC source code is hosted on `Github `_. +If you have `git `_, you can download MC/DC by entering the +following commands in a terminal: + +.. code-block:: sh + + git clone https://github.com/CEMeNT-PSAAP/MCDC.git + cd MCDC + + +The MC/DC repository includes the script ``install.sh``, which will +build MC/DC and all of its dependencies and execute any necessary patches. +This has been tested on Quartz, Lassen, and Apple M2 (as of 11/01/2023). +The ``install.sh`` script **will fail outside of a conda environment**. + +On HPC machines, the script will install mpi4py +`from source `_. +This means that all appropriate modules must be loaded prior to executing. + +On Quartz, the default modules are sufficient (``intel-classic`` and ``mvapich2``). +On Lassen, ``module load gcc/8 cuda/11.3``. Then, + +.. code-block:: sh + + bash install.sh --hpc + + +On local machines, mpi4py will be installed using conda, + +.. code-block:: sh + + bash install.sh + + +To confirm that everything is properly installed, execute ``pytest`` from the MCDC directory. + + diff --git a/docs/source/pythonapi/index.rst b/docs/source/pythonapi/index.rst new file mode 100644 index 00000000..31a5e32f --- /dev/null +++ b/docs/source/pythonapi/index.rst @@ -0,0 +1,74 @@ +.. _pythonapi: + +================ +Input Definition +================ + +Full API documentation. + + +Defining materials +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: omcfunction.rst + + mcdc.material + mcdc.nuclide + + +Defining geometry +----------------- + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: omcfunction.rst + + mcdc.surface + mcdc.cell + mcdc.universe + mcdc.lattice + + + +Defining simulation +------------------- + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: omcfunction.rst + + mcdc.source + mcdc.tally + mcdc.eigenmode + mcdc.setting + + + +Defining techniques +------------------- + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: omcfunction.rst + + mcdc.implicit_capture + mcdc.weighted_emission + mcdc.population_control + mcdc.branchless_collision + mcdc.time_census + mcdc.weight_window + mcdc.iQMC + mcdc.weight_roulette + mcdc.IC_generator + mcdc.dsm + + + + + diff --git a/install.sh b/install.sh new file mode 100755 index 00000000..b284d568 --- /dev/null +++ b/install.sh @@ -0,0 +1,60 @@ +#!/bin/bash + + +# Install MC/DC module +pip install -e . + + +# Install MC/DC dependencies, reply "y" to conda prompt +conda install numpy numba matplotlib scipy h5py pytest <<< "y" + + +# Patch numba +s=$(python -c 'import numba; print(numba.__path__[0])') +s+='/core/types/scalars.py' + +line=$(grep -n 'class Boolean(Hashable):' $s | cut -f1 -d:) + +head -n $line $s > tmp-scalars.py +cat >> tmp-scalars.py << EOF + def __init__(self, name): + super(Boolean, self).__init__(name) + self.bitwidth = 8 +EOF + +length=$(wc -l < $s) +let "length -= line" +tail -n $length $s >> tmp-scalars.py + +mv tmp-scalars.py $s + + + +# Install or build mpi4py +if [ $# -eq 0 ]; then + conda install mpi4py <<< "y" +fi +while [ $# -gt 0 ]; do + case $1 in + --hpc) + # Rename legacy compiler option in conda + s=$(which python) + s=${s//bin\/python/compiler_compat} + + if [ ! -f $s/ld.bak ] && [ -f $s/ld ]; then + mv $s/ld $s/ld.bak + fi + + mkdir installs; cd installs + wget https://github.com/mpi4py/mpi4py/releases/download/3.1.4/mpi4py-3.1.4.tar.gz -q + tar -zxf mpi4py-3.1.4.tar.gz + cd mpi4py-3.1.4 + python setup.py install + cd ../../ + rm -rf installs/ + ;; + esac + shift +done + + diff --git a/setup.py b/setup.py index c7afd6db..c36fb4e6 100644 --- a/setup.py +++ b/setup.py @@ -1,3 +1,9 @@ from setuptools import setup, find_packages -setup(name="mcdc", version="0.1.0", packages=find_packages(include=["mcdc"])) +kwargs = { + "name": "mcdc", + "version": "0.1.0", + "packages": find_packages(include=["mcdc"]), +} + +setup(**kwargs)