Merge dev into main (#171)

* Add a github workflow that prevents PRs to main that is not comming from dev (#92)

* Fix to position of additional cylindrical surface used to limit torus extent (#96)

* camel case for all classes (#95)

* camel case for all classes

* corrected file imports for georeverse

* Apply suggestions from code review

variable back to snake case

* variable back to snake case

* back to snake case

* back to previous var name

* Snake case variables (PR 1 of several) (#98)

* snake case for CellDefinitions file, tests pass

* vars in snake_case 2 more files

* working still

* using is to compare with bool (#99)

* Add comments to Geometry.py and booleanFunction.py files (#101)

* Add comments to Geometry_GU.py

* Add comments to booleanFunction.py

* Add comments to Geometry_GU.py

* Specific imports instead of wild card (#100)

* improved import statements flake8 hints

* removed extra line

* solve issue #75 in getTransMatrix function (#103)

* Changes in users initialization (#102)

* Add a github workflow that prevents PRs to main that is not comming from dev (#92) (#93)

* Add scripting interface

Change to allow setting users parameters by either config file or geouned set method

* minor fix

* Changes in geounedClassCall.py

---------

Co-authored-by: AlvaroCubi <55387701+AlvaroCubi@users.noreply.github.com>

* Adding formatter to CI to keep code in PEP8 (#104)

* added format checker

* run black . locally

* f strings instead of .format (#106)

* replaced all .format with f strings

* corrected f string conversion

* Snake case variables (PR 2 of several)  (#105)

* snake case im more varibles

* formatting

---------

Co-authored-by: Patrick Sauvan <psauvan@ind.uned.es>

* Quicker tests for ci (#109)

* removing slowest two geometries

* removing slow files from CI

* format

* added draft template (#97)

* Removing unused code (#107)

@psauvan comment has been taken into account. Unreachable code that was there for future consideration has been changed to comments.

* if statement includes False so never runs code

* if statement includes True so always run and never reaches else

* line after return never reached

* unused arg

* unused arg

* unused arg calling function

* commented unused code as requested

* formatting

* format

* Testing writing inputs for more MC codes (#108)

* also writting openmc python, phits and serpent files

* formatting

* decreased lcoal run time and added all outFormats

* black using same version as in pyproject

* py3.11 in formatting ci

* matched exactly black versions

* simpler black pinning

* format

* Snake case functions (#115)

* converted more functions

* more snake case functions

* more snake case function names

* more snake case functions

* more snake case functions

* more snake case functions

* formatting

* formatting

* formatting

* formatting

* converting function names to snake class

* duplicate import openmc (#116)

* Sphinx based docs with CI action to build and hosted on gh-pages (#119)

* started rtd

* testing docs action

* update pip

* corrected python version

* added s to docs

* publish every time

* added static folder

* skipping ci for non code files

* changed to rerad the docs theme

* started install section

* added more sections

* added api class

* docs ci using conda

* added -y for freecad

* trying py 3.12

* mimic working conda ci

* using rst so no markdown convertion needed

* added github edit link

* removed path prints

* added readme link, badge

* format

* Add issue templates  (#112)

* Add a github workflow that prevents PRs to main that is not comming from dev (#92) (#93)

* Create feature request template

* improve documentation template

* update feature request template

---------

Co-authored-by: AlvaroCubi <55387701+AlvaroCubi@users.noreply.github.com>

* Trigger docs build on push only (#126)

* pushing triggers doics build

* added if push

* added missing = sign (#130)

* added missing package (#135)

* replaced print statements with log (#133)

* replaced print statements with log

* added logger

* formatting

* removed encoding arg

* removed verbose as all gets logged

* removed unused logger

* removed , from logging cmd

* sorted imports

* added another tqdm loop

* isort

* format

* Fixing logger commands (#137)

* fixed multi comma log statements

* capital letters for progress bar sections

* formatted

* removal of Options as global variable (#138)

* instances of Options class passed by arg

* updated usage to show how to use Options

* format pep8

* added missing options arg

* added missing args options

* passing in options as arg

* bug fix for compsolid

* format

* removal of Tolerances as global variable  (#139)

* passing tolerance as arg not global var

* added tolerance example to usage section

* one set of argument names

* moved atr and types getting out of loop

* format

* passing missing options and tolerances

* format

* found bug hidden in try: except statement

* using tolerance for more local varibles

* formatting

* Numerical format to normal class (#141)

* replaced global with class passed by arg

* format

* Improving docs install section (#145)

* added dev install instructions

* added method section

* testing the setting of all class arguments (#147)

* Adding getters setters type checking to Options, Tolerances, NumericFormat class (#148)

* added type ching setters

* added low limit checking for reals

* format

* added type checkers for Tolerances

* format

* Add settings class (#149)

* settings being passed through the code

* all the attributes show in usage example

* Adding export csg method (#150)

* added export csg method

* format

* leaving comments in tests

* Adding support for json config file (#152)

* testing from json

* returned file to pre PR status

* returned file to init

* returned file to init

* temp fixing for serpent universe, issue raised

* making use of stp file already on repo

* Adding command line tool including documentation and testing (#155)

* split usage into two sections

* added minimal config from cli example to ci

* improved cli docs

* format

* removed duplication between readme and docs (#156)

* Moving code from __init__ file to core.py (#157)

* moved core logic from init

* format

* Fixing issue 154 (#158)

* added test that currently fails

* fixed bug with freecad attribute usage

* added missing arg

* format

* added missing args bug (#159)

* added missing args

* format

* added description of solid being decomposed (#161)

* Context managers for writing try 2 (#160)

* Add a github workflow that prevents PRs to main that is not comming from dev (#92) (#93)

* using context managers to write files

* review comments 4/5

---------

Co-authored-by: AlvaroCubi <55387701+AlvaroCubi@users.noreply.github.com>

* Creating folder if needed (#162)

* added tests to check writing to folder

* back to org

* back to org

* back to org

* creating output folder prior to writing

* isort on the imports

* format

* setting line length to 128 (#163)

* Lower case folder names and files (#165)

* renamed subfolders to lowercase

* renamed files to lower case

* openmc_py and openmc_xml lower case (#166)

* openmc_py and openmc_xml lower case

* removed outdated code comment

* Added type checking on export csg (#167)

* added input checking on export_csg

* compacted same types

* Update src/geouned/GEOUNED/core.py

---------

Co-authored-by: Patrick Sauvan <psauvan@ind.uned.es>

* Adding windows install instructions (#169)

* added windows install instructions

* improved install instructions

---------

Co-authored-by: teade <37874718+teade@users.noreply.github.com>
Co-authored-by: Jonathan Shimwell <drshimwell@gmail.com>
Co-authored-by: Jonathan Shimwell <mail@jshimwell.com>
Co-authored-by: Patrick Sauvan <psauvan@ind.uned.es>
Co-authored-by: alberto743 <4104972+alberto743@users.noreply.github.com>
Co-authored-by: Alex Valentine <40658938+alexvalentine94@users.noreply.github.com>

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[Feature request] - title of the issue"
+labels: enhancement
+assignees: ''
+
+---
+
+# Is your feature request related to a problem? Please describe.
+A clear and concise description of what the problem is.
+
+# Describe the solution you'd like
+A clear and concise description of what you want to happen.
+
+# Describe alternatives you've considered
+A clear and concise description of any alternative solutions or features you've considered.
+
+# Additional context
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/improve_documentation.md

@@ -0,0 +1,23 @@
+---
+name: Improve documentation
+about: Help us improve our documentation
+title: "[DOC] - title of the issue"
+labels: documentation
+assignees: ''
+
+---
+
+# What were you looking for
+Please try to describe in a concise way which kind of information you were looking for and where were you looking.
+
+# Is the information available in the doc but not where you would expect?
+let us know if you ended up finding the information you were looking for in another (unexpected) section of the doc.
+
+# Is information completely lacking or partial?
+please specify if you are asking for better explanation/clarification of the text or if the information is completely lacking.
+
+# Where would you insert the missing information?
+describe here where you would put the information.
+
+# Additional context
+you can use this space to give any other additional information that you think would be useful to solve the issue.

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+If you are a first-time contributor to GEOUNED, please read our contributing guidelines:
+https://github.com/GEOUNED-org/GEOUNED/blob/main/CONTRIBUTING.md
+
+# Description
+
+Please include a summary of the changes and motivation for the changes
+
+# Fixes issue
+
+Please link to any issues that this PR fixes
+
+# Checklist
+
+- [ ] I'm making a PR from a feature branch on my fork into GEOUNED-org/GEOUNED/dev branch
+- [ ] I have followed [PEP8 style guide]([url](https://peps.python.org/pep-0008/)) for Python or run a formatter such as [black]([url](https://github.com/psf/black)) or [ruff format]([url](https://github.com/astral-sh/ruff)) on my code
+- [ ] I have made corresponding changes to the documentation
+- [ ] I have added tests that prove my fix is effective or that my feature works

.github/workflows/black.yml

@@ -0,0 +1,12 @@
+name: Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: psf/black@stable
+        with:
+          version: "24.4.2"

.github/workflows/ci.yml

@@ -5,6 +5,12 @@ on:
       branches:
         - dev
         - main
+      paths-ignore:
+        - "**.md"
+        - "**.txt"
+        - "**.cff"
+        - 'docs/**'
+        - '.gitignore'
     push:
       branches:
         - main
@@ -44,13 +50,17 @@ jobs:
           run: |
             python -m pip install --upgrade pip
             python -m pip install .
+            geouned_cadtocsg --help
             python -c 'import geouned'
-            python -c 'from geouned import GEOUNED'
+            python -c 'from geouned import CadToCsg'
             python -c 'from geouned.GEOReverse import reverse'
             python -m pip install .[tests]
 
         - name: testing GEOUNED functionality
-          run: python -m pytest -v tests/test_convert.py
+          run: |
+            python -m pytest -v tests/test_convert.py
+            geouned_cadtocsg -i tests/config_complete_defaults.json
+            geouned_cadtocsg -i tests/config_non_defaults.json
 
         - name: install openmc
           if: ${{ matrix.os == 'ubuntu-latest'}}

.github/workflows/documentation.yml

@@ -0,0 +1,52 @@
+name: documentation
+
+on:
+  pull_request:
+    branches:
+      - dev
+      - main
+  push:
+    branches:
+      - main
+      - dev
+
+permissions:
+  contents: write
+
+jobs:
+  testing:
+    name: Documentation
+    runs-on: "ubuntu-latest"
+    defaults:
+      run:
+        shell: bash -el {0}
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+    steps:
+      - name: checkout actions
+        uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          python-version: ${{ matrix.python-version }}
+          channels: conda-forge
+
+      - name: install dependencies
+        run: conda install -c conda-forge freecad -y
+
+      - name: install package
+        run: |
+          pip install --upgrade pip
+          pip install .[docs]
+      - name: Sphinx build
+        run: |
+          sphinx-build docs _build
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

.github/workflows/python-publish.yml

@@ -1,4 +1,4 @@
-name: Upload Python Package
+name: PyPI Python Package
 
 on:
   release:

.gitignore

@@ -166,8 +166,16 @@ cython_debug/
 # testing folder
 tests_outputs/
 
+# debug output folders
+fuzzySurfaces
+Suspicious_solids/
+Warning_Solids_definition.txt
+
 .vscode
 **/__pycache__
+
+# documentation
+_build
 docs/source/_build/**
 docs/build/**
 docs/source/_autosummary/*

README.md

@@ -1,82 +1,14 @@
 [![CI testing](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/ci.yml)
+[![Upload Python Package](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/python-publish.yml/badge.svg)](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/python-publish.yml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/psf/black)
+[![documentation](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/documentation.yml/badge.svg)](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/documentation.yml)
+
 
 # GEOUNED
 A tool to convert from CAD to CSG & CSG to CAD for Monte Carlo transport codes (MCNP & OpenMC).
 This repository contains the implementation of the algorithm presented in the paper [GEOUNED: A new conversion tool from CAD to Monte Carlo geometry](https://doi.org/10.1016/j.net.2024.01.052).
 
-## Installation 
-
-Install directly from the repository (for python versions > 3.7 => FreeCAD >= 0.19 ):
-
-```bash
-pip install git+https://github.com/GEOUNED-code/GEOUNED.git
-```
-
-Otherwise, the source code included in the ~src/ folder can be directly downloaded and properly reached by path variable as follows:
-
-```python
-import sys
-GEO_path='the path in your local computer'
-sys.path.append('GEO_path')
-``` 
-
-the same should be made for FreeCAD libraries. You can also define appropriately the PYTHONPATH variable for both modules. 
-
-If you are using FreeCAD in windows there is included a python distribution within FreeCAD distribution (by default located in C:\Program Files\FreeCAD 0.XX\bin\).
-In that case you can install directly de module using:
-
-```bash
-C:\Program Files\FreeCAD 0.XX\bin\python.exe -m pip install git+https://github.com/GEOUNED-code/GEOUNED.git
-```
-using this option you have directly access to both FreeCAD and GEOUNED python modules. 
-Furthermore, using this python compatibilities problems between different versions of python are avoided (some dynamic libraries of FreeCAD depends on the version of python used during the built process). 
-
-## How to use
-
-The code is used via python scripting.  
-
-The first step is to call the python modules of both FreeCAD and GEOUNED (this can be avoided if you have installed GEOUNED as commented in the previous section and using the python distributed with FreeCAD).
-
-```python
-import sys
-GEO_path='the path in your local computer, the complete or relative path to the ~src/ folder'
-FreeCAD_path='path of FreeCAD python modules'
-sys.path.append(GEO_path)
-sys.path.append(FreeCAD_path)
-``` 
-The second step is to call or GEOUNED for CAD to CSG conversion or GEOReverse for CSG to CAD.
-
-From CAD to CSG:
-
-```python
-from geouned import GEOUNED
-inifile='Name of config file for forward conversion'
-GEO = GEOUNED(inifile)
-GEO.SetOptions()
-GEO.Start()
-``` 
-From CSG to CAD (so far only for MCNP): 
-
-```python
-from GEOReverse.reverse import reverse
-inifile='Name of config file for reverse conversion'
-reverse(inifile)
-``` 
-In the ~scripts/ folder you can find a script (geouned for linux or geouned.py for windows) to call both modules directly by command line as follows:
-
-windows (forward and reverse):
-```bash
-/~>python geouned.py file_config_name
-/~>python geouned.py -r file_config_name
-```
-
-linux (forward and reverse):
-```bash
-/~>geouned file_config_name
-/~>geouned -r file_config_name
-```
-
-Detailed descriptions of all options of the config files (forward and reverse) are given in the manual located in ~docs/ folder.
+See the [online documentation](https://geouned-org.github.io/GEOUNED/index.html) for installation, usage and API reference.
 
 ## Citation
 

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     = .
+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)

docs/conf.py

@@ -0,0 +1,67 @@
+# 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
+import sys
+
+sys.path.insert(0, os.path.abspath("../../src"))
+
+# -- Project information -----------------------------------------------------
+
+project = "GEOUNED"
+copyright = "2024, UNED"
+author = "Juan-Pablo Catalan and Patrick Sauvan"
+
+# The full version, including alpha/beta/rc tags
+release = "1.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",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.coverage",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
+    "sphinx.ext.viewcode",
+]
+
+# 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 = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- 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 = "sphinx_rtd_theme"
+
+# 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"]
+
+html_context = {
+    "display_github": True,
+}
+# html_favicon = "favicon.ico"

docs/developer_guide.rst

@@ -0,0 +1,4 @@
+Developer guide
+===============
+
+TOOD

docs/index.rst

@@ -0,0 +1,20 @@
+.. 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
+=======
+
+GEOUNED converts CAD to Constructive Solid Geometry (CSG) formats for use in
+Monte Carlo transport codes.
+Supported codes include OpenMC, PHITS, Serpent and MCNP.
+
+.. toctree::
+   :maxdepth: 3
+
+   install/index
+   usage/index
+   python_api
+   methodology
+   developer_guide