diff --git a/docs/Training_on_GEOUNED_tool.pdf b/docs/Training_on_GEOUNED_tool.pdf deleted file mode 100644 index 6e80849f..00000000 Binary files a/docs/Training_on_GEOUNED_tool.pdf and /dev/null differ diff --git a/docs/User_Guide_GEOUNED_v2.0.pdf b/docs/User_Guide_GEOUNED_v2.0.pdf deleted file mode 100644 index 23a3c843..00000000 Binary files a/docs/User_Guide_GEOUNED_v2.0.pdf and /dev/null differ diff --git a/docs/conf.py b/docs/conf.py index 8ab45740..e92c7e13 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,7 +20,6 @@ project = "GEOUNED" copyright = "2024, UNED" -author = "Juan-Pablo Catalan and Patrick Sauvan" # The full version, including alpha/beta/rc tags import geouned @@ -83,6 +82,6 @@ "json_url": "https://raw.githubusercontent.com/GEOUNED-org/GEOUNED/dev/docs/version_switcher.json", "version_match": version_match, }, - "nav_title": "Geouned", + "nav_title": "GEOUNED", "navbar_start": ["version-switcher", "navbar-icon-links"], } diff --git a/docs/developer_guide.rst b/docs/developers_guide.rst similarity index 99% rename from docs/developer_guide.rst rename to docs/developers_guide.rst index 56bc9d22..0e801357 100644 --- a/docs/developer_guide.rst +++ b/docs/developers_guide.rst @@ -1,4 +1,4 @@ -Developer guide +Developers guide =============== Developer install with Mamba diff --git a/docs/images/mat_list.png b/docs/images/mat_list.png new file mode 100644 index 00000000..4a5e0b4a Binary files /dev/null and b/docs/images/mat_list.png differ diff --git a/docs/images/mat_tag.png b/docs/images/mat_tag.png new file mode 100644 index 00000000..08e71efa Binary files /dev/null and b/docs/images/mat_tag.png differ diff --git a/docs/index.rst b/docs/index.rst index b63c7c50..56f281ec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,4 @@ -.. GEOUNED documentation master file, created by - sphinx-quickstart on Tue Apr 30 09:47:11 2024. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Geouned Documentation +GEOUNED Documentation ===================== **Version**: |version| @@ -13,10 +8,9 @@ Monte Carlo transport codes. Supported codes include OpenMC, PHITS, Serpent and MCNP. .. toctree:: - :maxdepth: 3 + :maxdepth: 2 - install/index - usage/index + quick_install_guide + users_guide/index python_api - methodology - developer_guide + developers_guide diff --git a/docs/methodology.rst b/docs/methodology.rst deleted file mode 100644 index 78fc03f8..00000000 --- a/docs/methodology.rst +++ /dev/null @@ -1,13 +0,0 @@ -Methodology -=========== - - -There are several documents on the methodology of GEOUNED - -`Publication `_ - -`User_Guide_GEOUNED_v2.0.pdf `_ - -`Training_on_GEOUNED_tool `_ - -TODO convert various data sources to rst format for these docs diff --git a/docs/quick_install_guide.rst b/docs/quick_install_guide.rst new file mode 100644 index 00000000..fcb3046b --- /dev/null +++ b/docs/quick_install_guide.rst @@ -0,0 +1,112 @@ +Quick Install Guide +=================== + +Linux +~~~~~ + +First we need to install a Conda distribution. There are a few options but we here we opt for `MiniConda3 `_ as it downloads quicker than the fuller `Anaconda `_. + +You can follow the install instructions for `MiniConda3 `_ or follow the commands below. +Download. + +.. code-block:: sh + + mkdir -p ~/miniconda3 + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh + +Install MiniConda3 + +.. code-block:: sh + + bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3 + + +Activate the base environment in your current terminal + +.. code-block:: sh + + ~/miniconda3/bin/conda init bash + + +It is recommended to create a new environment + +.. code-block:: sh + + conda create --name new_env python=3.11 + + +Activate the new environment + +.. code-block:: sh + + conda activate new_env + +Install GEOUNED from conda-forge + +.. code-block:: sh + + conda install -c conda-forge geouned -y + +Then you will be able to run import GEOUNED from within Python + +.. code-block:: python + + import geouned + +You will also be able to use the GEOUNED command line tool + +.. code-block:: bash + + geouned_cadtocsg --help + + +Windows +~~~~~~~ + +First we need to install a Conda distribution. There are a few options but we here we opt for `MiniConda3 `_ as it downloads quicker than the fuller `Anaconda `_. + +You can follow the install instructions for `MiniConda3 `_ + +Download and execute the Miniforge3 Windows installer + +You can get it from the `Miniforge3 GitHub repository here `_ or from the link below + +`https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe `_ + +Open "Anaconda Prompt (miniconda3)" which will now be available on your start menu. + +It is recommended to create a new environment + +.. code-block:: sh + + conda create --name new_env python=3.11 + +Activate the new environment + +.. code-block:: sh + + conda activate new_env + +Since one of the GEOUNED dependencies is FreeCAD, classic conda solver of dependencies may significantly slow down the installation. For this reason, it is recommended to install and use conda-libmamba-solver + +.. code-block:: sh + + conda install conda-libmamba-solver + +Install GEOUNED from conda-forge, forcing the use of libmamba solver + +.. code-block:: sh + + conda install -c conda-forge geouned -y --solver=libmamba + +Then you will be able to run import GEOUNED from within Python + +.. code-block:: python + + import geouned + +You will also be able to use the GEOUNED command line tool + +.. code-block:: bash + + geouned_cadtocsg --help diff --git a/docs/usage/index.rst b/docs/users_guide/execution_settings/cad2csg/index.rst similarity index 66% rename from docs/usage/index.rst rename to docs/users_guide/execution_settings/cad2csg/index.rst index 157a09ab..49592413 100644 --- a/docs/usage/index.rst +++ b/docs/users_guide/execution_settings/cad2csg/index.rst @@ -1,16 +1,11 @@ -.. usage - -Usage -===== +CAD to CSG Translation +====================== GEOUNED can be used as a Python package with the API or as a command line tool with the CLI. .. toctree:: - :numbered: :maxdepth: 1 python_cadtocsg_api_usage python_cadtocsg_cli_usage - python_csgtocad_api_usage - python_csgtocad_cli_usage diff --git a/docs/usage/python_cadtocsg_api_usage.rst b/docs/users_guide/execution_settings/cad2csg/python_cadtocsg_api_usage.rst similarity index 97% rename from docs/usage/python_cadtocsg_api_usage.rst rename to docs/users_guide/execution_settings/cad2csg/python_cadtocsg_api_usage.rst index 7d3942f2..cabdc7e7 100644 --- a/docs/usage/python_cadtocsg_api_usage.rst +++ b/docs/users_guide/execution_settings/cad2csg/python_cadtocsg_api_usage.rst @@ -1,5 +1,5 @@ -Python Package Usage, CAD to CSG conversion -=========================================== +Python Package Usage +==================== The main class is ``CadToCsg()`` which converts CAD geometry to Constructive Solid Geometry (CSG). There are many arguments that can be passed into the ``CadToCsg()`` class which are documented in the `Python API reference section <../python_api.html>`_ of the documentation. diff --git a/docs/usage/python_cadtocsg_cli_usage.rst b/docs/users_guide/execution_settings/cad2csg/python_cadtocsg_cli_usage.rst similarity index 97% rename from docs/usage/python_cadtocsg_cli_usage.rst rename to docs/users_guide/execution_settings/cad2csg/python_cadtocsg_cli_usage.rst index ec00218d..ddcceeca 100644 --- a/docs/usage/python_cadtocsg_cli_usage.rst +++ b/docs/users_guide/execution_settings/cad2csg/python_cadtocsg_cli_usage.rst @@ -1,5 +1,5 @@ -Command Line Tool Usage, CAD to CSG conversion -============================================== +Command Line Tool Usage +======================= GEOUNED CAD to CSG conversion can be performed in the command line. diff --git a/docs/users_guide/execution_settings/csg2cad/index.rst b/docs/users_guide/execution_settings/csg2cad/index.rst new file mode 100644 index 00000000..78ebd892 --- /dev/null +++ b/docs/users_guide/execution_settings/csg2cad/index.rst @@ -0,0 +1,11 @@ +CSG to CAD Translation +====================== + +GEOUNED can be used as a Python package with the API or as a command line tool with the CLI. + + +.. toctree:: + :maxdepth: 1 + + python_csgtocad_api_usage + python_csgtocad_cli_usage diff --git a/docs/usage/python_csgtocad_api_usage.rst b/docs/users_guide/execution_settings/csg2cad/python_csgtocad_api_usage.rst similarity index 93% rename from docs/usage/python_csgtocad_api_usage.rst rename to docs/users_guide/execution_settings/csg2cad/python_csgtocad_api_usage.rst index 1c9b2987..1ce5984c 100644 --- a/docs/usage/python_csgtocad_api_usage.rst +++ b/docs/users_guide/execution_settings/csg2cad/python_csgtocad_api_usage.rst @@ -1,5 +1,5 @@ -Python Package Usage, CSG to CAD conversion -=========================================== +Python Package Usage +==================== The main class is ``CsgToCad()`` which converts Constructive Solid Geometry (CSG) to CAD. There are a few arguments that can be passed into the ``CsgToCad().export_cad()`` method which are documented in the `Python API reference section <../python_api.html>`_ of the documentation. diff --git a/docs/usage/python_csgtocad_cli_usage.rst b/docs/users_guide/execution_settings/csg2cad/python_csgtocad_cli_usage.rst similarity index 96% rename from docs/usage/python_csgtocad_cli_usage.rst rename to docs/users_guide/execution_settings/csg2cad/python_csgtocad_cli_usage.rst index 83d955e7..0792ac3e 100644 --- a/docs/usage/python_csgtocad_cli_usage.rst +++ b/docs/users_guide/execution_settings/csg2cad/python_csgtocad_cli_usage.rst @@ -1,5 +1,5 @@ -Command Line Tool Usage, CSG to CAD conversion -============================================== +Command Line Tool Usage +======================= GEOUNED CSG to CAD conversion can be performed in the command line. diff --git a/docs/users_guide/execution_settings/index.rst b/docs/users_guide/execution_settings/index.rst new file mode 100644 index 00000000..1952dde3 --- /dev/null +++ b/docs/users_guide/execution_settings/index.rst @@ -0,0 +1,11 @@ +Execution Settings +================== + +GEOUNED can be used as a Python package with the API or as a command line tool with the CLI. + + +.. toctree:: + :maxdepth: 2 + + cad2csg/index + csg2cad/index diff --git a/docs/users_guide/index.rst b/docs/users_guide/index.rst new file mode 100644 index 00000000..c57144da --- /dev/null +++ b/docs/users_guide/index.rst @@ -0,0 +1,14 @@ +Users Guide +=========== + +GEOUNED can be used as a Python package with the API or as a command line tool with the CLI. + + +.. toctree:: + :maxdepth: 2 + + installation/index + execution_settings/index + simplification + material_allocation + void_generation diff --git a/docs/install/index.rst b/docs/users_guide/installation/index.rst similarity index 94% rename from docs/install/index.rst rename to docs/users_guide/installation/index.rst index be94dbe8..56cfa8cd 100644 --- a/docs/install/index.rst +++ b/docs/users_guide/installation/index.rst @@ -1,7 +1,5 @@ -.. usage - -Install -======= +Installation +============ There are several options for installing GEOUNED package. The installation selected has implications for how you run GEOUNED Python scripts. @@ -12,7 +10,6 @@ Users have also had success installing FreeCAD and making use of the Python vers .. toctree:: - :numbered: :maxdepth: 1 install_linux diff --git a/docs/install/install_linux.rst b/docs/users_guide/installation/install_linux.rst similarity index 98% rename from docs/install/install_linux.rst rename to docs/users_guide/installation/install_linux.rst index c7b6f62b..09d94005 100644 --- a/docs/install/install_linux.rst +++ b/docs/users_guide/installation/install_linux.rst @@ -62,7 +62,7 @@ You will also be able to use the GEOUNED command line tool User install with Conda ~~~~~~~~~~~~~~~~~~~~~~~ -First we need to install a Conda distribution. There are a few options but we here we opt for `MiniConda3 `_ as it downloads quicker than the fuller `AnaConda `_. +First we need to install a Conda distribution. There are a few options but we here we opt for `MiniConda3 `_ as it downloads quicker than the fuller `Anaconda `_. You can follow the install instructions for `MiniConda3 `_ or follow the commands below. Download. diff --git a/docs/install/install_windows.rst b/docs/users_guide/installation/install_windows.rst similarity index 98% rename from docs/install/install_windows.rst rename to docs/users_guide/installation/install_windows.rst index cf91966c..41c663e1 100644 --- a/docs/install/install_windows.rst +++ b/docs/users_guide/installation/install_windows.rst @@ -52,7 +52,7 @@ You will also be able to use the GEOUNED command line tool User install with Conda ~~~~~~~~~~~~~~~~~~~~~~~ -First we need to install a Conda distribution. There are a few options but we here we opt for `MiniConda3 `_ as it downloads quicker than the fuller `AnaConda `_. +First we need to install a Conda distribution. There are a few options but we here we opt for `MiniConda3 `_ as it downloads quicker than the fuller `Anaconda `_. You can follow the install instructions for `MiniConda3 `_ diff --git a/docs/users_guide/material_allocation.rst b/docs/users_guide/material_allocation.rst new file mode 100644 index 00000000..25538799 --- /dev/null +++ b/docs/users_guide/material_allocation.rst @@ -0,0 +1,22 @@ +Material Allocation +=================== + +The material of the components can be assigned directly in the tree CAD by including a text with _mXX_ within the component name. + +.. image:: /images/mat_tag.png + :alt: Example of a CAD tree with a _mXX_ tag. + :align: center + :width: 50% + +The material assigned to the corresponding cell should be defined in the material definition file whose name is provided by the matFile keyword. +This file has the following format: + +.. image:: /images/mat_list.png + :alt: Example of a material list. + :align: center + :width: 50% + +Where # is used for comments and the rest of the lines specifies the id of the material, the nominal density and the text to be included as a comment. +The nominal density value is multiplied by -1 so the criterium is inverted with respect to MCNP one (i.e. g/cm3 positive and atm/b/cm negative). +The nominal density can be changed by the inclusion of a multiplication factor using the following text in the CAD tree _mXX_dXX.XX_. +For example, in our case _m01_d2.0_ will produce a cell with material 1 and density 2.0. diff --git a/docs/users_guide/simplification.rst b/docs/users_guide/simplification.rst new file mode 100644 index 00000000..245a406f --- /dev/null +++ b/docs/users_guide/simplification.rst @@ -0,0 +1,4 @@ +Simplification of Geometry +=========================== + +To be added. \ No newline at end of file diff --git a/docs/users_guide/void_generation.rst b/docs/users_guide/void_generation.rst new file mode 100644 index 00000000..d4f62c43 --- /dev/null +++ b/docs/users_guide/void_generation.rst @@ -0,0 +1,4 @@ +Void Generation +=============== + +To be added. \ No newline at end of file