diff --git a/.gitignore b/.gitignore index 0b508b8..5af6842 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,179 @@ -docs/_build/* -docs/_static/* -__pycache__ \ No newline at end of file +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/latest/usage/project/#working-with-version-control +.pdm.toml +.pdm-python +.pdm-build/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ + +# Sphinx build output +_build/ +apidoc/ + +# Sphinx auto-generated files +*.doctrees +searchindex.js + +# Environment-specific files +.env +.venv +venv/ + +# Editor-specific files +.idea/ +.vscode/ \ No newline at end of file diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst new file mode 100644 index 0000000..667f196 --- /dev/null +++ b/docs/_templates/autosummary/base.rst @@ -0,0 +1,15 @@ +{% if objtype == 'property' %} +:orphan: +{% endif %} + +{{ objname | escape | underline}} + +.. rubric:: *module* :mod:`{{ module }}` + +.. currentmodule:: {{ module }} + +{% if objtype == 'property' %} +property +{% endif %} + +.. auto{{ objtype }}:: {{ fullname | replace(module + ".", module + "::") }} diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 0000000..9e9adf1 --- /dev/null +++ b/docs/_templates/autosummary/class.rst @@ -0,0 +1,37 @@ +{{ objname | escape | underline}} + +.. rubric:: *module* :mod:`{{ module }}` + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + +{% block methods %} +{% if methods %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + + {% for item in all_methods %} + {%- if not item.startswith('_') or item in ['__call__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block attributes %} +{% if attributes %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + + {% for item in all_attributes %} + {%- if not item.startswith('_') %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} + + {% if methods or attributes %} + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + {% endif %} diff --git a/docs/_templates/autosummary/exception.rst b/docs/_templates/autosummary/exception.rst new file mode 100644 index 0000000..8d05ab9 --- /dev/null +++ b/docs/_templates/autosummary/exception.rst @@ -0,0 +1,34 @@ +{{ objname | escape | underline}} + +.. rubric:: *module* :mod:`{{ module }}` + +.. currentmodule:: {{ module }} + +.. autoexception:: {{ objname }} + :no-inherited-members: + +{% block methods %} +{% if methods %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + + {% for item in all_methods %} + {%- if not item.startswith('_') or item in ['__call__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block attributes %} +{% if attributes %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + + {% for item in all_attributes %} + {%- if not item.startswith('_') %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst new file mode 100644 index 0000000..83da37c --- /dev/null +++ b/docs/_templates/autosummary/module.rst @@ -0,0 +1,73 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + :exclude-members: {% for item in attributes %}{{ item }}, {% endfor %}{% for item in functions %}{{ item }}, {% endfor %}{% for item in classes %}{{ item }}, {% endfor %}{% for item in exceptions %}{{ item }}, {% endfor %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Module Attributes') }} + + .. autosummary:: + :toctree: + :template: autosummary/base.rst + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + :nosignatures: + :toctree: + :template: autosummary/base.rst + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :nosignatures: + :toctree: + :template: autosummary/class.rst + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :nosignatures: + :toctree: + :template: autosummary/exception.rst + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: + :template: autosummary/module.rst +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/docs/api-doc.rst b/docs/api-doc.rst new file mode 100644 index 0000000..17ef3fb --- /dev/null +++ b/docs/api-doc.rst @@ -0,0 +1,22 @@ +.. _api_documentation: + +================= +API documentation +================= + +.. automodule:: opensg + :no-members: + :no-undoc-members: + :no-inherited-members: + + .. rubric:: Submodules + + .. autosummary:: + :toctree: apidoc + :recursive: + :template: autosummary/module.rst + + compute_utils + io + mesh + solve diff --git a/docs/conf.py b/docs/conf.py index 0560ed4..df61789 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,4 +1,6 @@ -from opensg import __version__ +# from opensg import __version__ +__version__ = "0.0.1" +# import mock # -- Project information ----------------------------------------------------- project = u'opensg' @@ -15,6 +17,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', + 'sphinx.ext.autosummary', # 'sphinx.ext.viewcode', # commenting out for now b/c bad render width 'sphinx.ext.napoleon', 'sphinxcontrib.bibtex', @@ -33,6 +36,19 @@ language = "en" numfig = True +autodoc_mock_imports = ["dolfinx", "basix", "ufl", "gmshio", "gmsh", "petsc4py", "scipy", + "mpi4py", "numpy",] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# autosummary settings +import glob +autosummary_generate = ["api-doc.rst",] + glob.glob("apidoc/*.rst") +# autosummary_generate = True +autosummary_generate_overwrite = True + + # 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 . diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..6496639 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,256 @@ +.. _contributing: + + +Contributing +============ + +Thank you for considering contributing to opensg. We welcome +contributions from the community in the form of bug fixes, feature +enhancements, documentation updates, etc. All contributions are +processed through pull-requests or issues on GitHub. Please follow these +guidelines for contributing. + + +Reporting issues and bugs +------------------------- + +This section guides you through the process of submitting an issue for +opensg. To report issues or bugs please `create a new issue +`_ on GitHub. + +Following these guidelines will help maintainers understand your issue, +reproduce the behavior, and develop a fix in an expedient fashion. +Before submitting your bug report, please perform a cursory search to +see if the problem has been already reported. If it has been reported, +and the issue is still open, add a comment to the existing issue instead +of opening a new issue. + +Tips for effective bug reporting +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Use a clear descriptive title for the issue +- Describe the steps to reproduce the problem, the behavior you + observed after following the steps, and the expected behavior +- Provide the SHA ID of the git commit that you are using +- For runtime errors, provide a function call stack + +Submitting pull-requests +^^^^^^^^^^^^^^^^^^^^^^^^ + +Contributions can take the form of bug fixes, feature enhancements, +documentation updates. All updates to the repository are managed via +`pull requests +`_. +One of the easiest ways to get started is by looking at `open issues +`_ and contributing fixes, +enhancements that address those issues. If your code contribution +involves large changes or additions to the codebase, we recommend +opening an issue first and discussing your proposed changes with the +core development team to ensure that your efforts are well directed, and +so that your submission can be reviewed and merged seamlessly by the +maintenance team. + +Guidelines for preparing and submitting pull-requests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Use a clear descriptive title for your pull-requests + +- Describe if your submission is a bugfix, documentation update, or a + feature enhancement. Provide a concise description of your proposed + changes. + +- Provide references to open issues, if applicable, to provide the + necessary context to understand your pull request + +- Make sure that your pull-request merges cleanly with the `main` + branch of opensg. When working on a feature, always create your + feature branch off of the latest `main` commit + +- Ensure that the code compiles without warnings, (leave for later? the + unit tests and regression tests all pass without errors, and the + documentation builds properly with your modifications) + +- New physics models and code enhancements should be accompanied with + relevant updates to the documentation, supported by necessary + verification and validation, as well as unit tests and regression + tests + +Once a pull-request is submitted you will iterate with opensg +maintainers until your changes are in an acceptable state and can be +merged in. You can push addditional commits to the branch used to create +the pull-request to reflect the feedback from maintainers and users of +the code. + +Stylistic conventions +^^^^^^^^^^^^^^^^^^^^^ + +- Please `black `__ your code. + This enforces a standard style across the project with minimal + thought and effort + +- Please use `snake case `__ + for function and variable names. + +Developer Installation +---------------------- + +To maintain a local installation, developers should use the following +commands: + +.. code:: + + git clone https://github.com/wenbinyugroup/opensg + cd opensg + pip install -e . + + +Running Common Developer Tasks +------------------------------ + +Many common developer tasks have been implemented through nox for +convenient and consistent results. The following subsections describe +the various tasks available through the `nox `__ task-runner. + +Testing +^^^^^^^ + +To run tests locally, run: + +.. code:: + + nox -s tests + +at the root of the repository. + +Formatting +^^^^^^^^^^ + +To check if your code complies to the black style run: + +.. code:: + + nox -s check_style + +at the root of the repository. If you find it does not, please run: + +.. code:: + + nox -s enforce_style + +Building Docs +^^^^^^^^^^^^^ + +To build docs locally, navigate to ``opensg/docs`` and run: + +.. code:: + + nox -s docs + +After building, the static html files can be found in ``_build/html``. + +Serving Docs +^^^^^^^^^^^^ + +To view the docs locally, navigate to ``opensg/docs`` and run: + +.. code:: + + nox -s serve + +Documentation +------------- + +Docstrings +^^^^^^^^^^ + +The documentation for opensg adheres to NumPy style docstrings. Not +only does this help to keep a consistent style, but it is also necessary +for the API documentation to be parsed and displayed correctly. For an +example of what this should look like: + +.. code:: + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Parameters + ---------- + arg1 : int + Description of arg1 + arg2 : str + Description of arg2 + + Returns + ------- + bool + Description of return value + + """ + return True + +Additional examples can be found in the `napoleon documentation +`_. +The following boilerplate can be copy-pasted into the top of a function +definition to help get things started: + +.. code:: + + """Summary line. + + Extended description of function. + + Parameters + ---------- + + Returns + ------- + + """ + +Extending opensg +----------------- + +Below we explain what to do when adding a top level directory +in the opensg source called ``new_mod/`` which contains a submodule called +``new_file.py``. + +Exposing New Functionality to Users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +By default, any functions in ``new_file.py`` would not be automatically +available to users operating outside of the source directory. This is +to enforce a distinction between internal and external functionality. +Any functionality you wish to be accessed externally needs to be imported +inside the appropriate ``__init__.py`` file. For example, the ``__init__.py`` +file inside of ``new_mod/`` might look like:: + + from new_file import new_function + +and the ``__init__.py`` inside of ``src/`` might look like:: + + import new_mod + +This would allow a user to access the functionality by importing ``opensg`` +and then running ``opensg.new_mod.new_function``. If you wanted the call +to be accessed with ``opensg.new_mod.new_file.new_function``, you would +replace ``from new_file import new_function`` with ``import new_file``. If +you are extending an already existing module, please follow the +existing convention within the corresponding ``__init__.py``. + +Expanding the API Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +New functionality for opensg should be properly documented +in the API documentation. A new folder-level module named ``new_mod/`` would +require the creation of the file ``docs/apidoc/opensg.new_mod`` with +the contents recording any submodules that should be captured by the +API documentation. A new file named ``new_file.py`` added to an existing folder would +need the following code to capture its functionality in the auto api documentation:: + + .. automodule:: opensg.new_mod.new_file + :members: + :no-undoc-members: + :show-inheritance: + +This will automatically capture all functions (internal and external) in ``new_file.py``. \ No newline at end of file diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 0000000..f6f517b --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,37 @@ +.. _glossary: + + +Glossary +============ + +This page contains definitions for various terminology and abbreviations +used throughout opensg documentation and code. + +Terminology +----------- + +!!WIP!! + +Mesh: A collection of cells (e.g., triangles, quadrilaterals in 2D, or tetrahedrons, +hexahedrons in 3D) representing a discretized computational domain. +A dolfinx.mesh.Mesh object encapsulates both the geometry and topology of this mesh. + +Cell: A fundamental element of a mesh (e.g., a triangle in 2D, tetrahedron in 3D) +that divides the domain into discrete parts for FEA computations. + +Facet: A boundary entity of a cell that is one dimension lower than the cell itself + +Boundary Condition: A condition imposed on facets or boundaries of a mesh, +such as Dirichlet boundary conditions (specifying function values on the boundary) +or Neumann boundary conditions (specifying derivative values). + +Connectivity: The relationship between different entities in a mesh +(e.g., between vertices and cells, cells and facets). +Connectivity maps define how entities are connected within a mesh. + +Topology: In dolfinx, refers to the structural organization of the mesh, including +the number and types of entities (vertices, edges, faces, cells) and their connectivity. + + +Abbreviations +------------- diff --git a/docs/index.rst b/docs/index.rst index 923e77e..ccaa0d2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,6 @@ .. _home: -pyNuMAD +opensg ======== The structural design and optimization of wind turbine blades is a @@ -8,7 +8,7 @@ complex task. In many cases it is difficult to find the optimal design of a turbine blade by hand, or by trial and error, and the software tools used for such designs are most effective when integrated into automated optimization and analysis algorithms. A new version of the -software tool `pyNuMAD (Python Numerical Manufacturing And Design) `_ for the design +software tool `opensg (Python Numerical Manufacturing And Design) `_ for the design and modeling of wind turbine blades is developed and described. .. toctree:: @@ -16,10 +16,10 @@ and modeling of wind turbine blades is developed and described. :hidden: user-guide/index - contributing - apidoc/pynumad - reference + api-doc + glossary release-notes + contributing publications license @@ -28,18 +28,18 @@ and modeling of wind turbine blades is developed and described. Citing NuMAD =============== -To cite pyNuMAD, please utilize the reference below. +To cite opensg, please utilize the reference below. -[1] Camarena, E., Anderson, E., Bonney, K. L., Clarke, R. J., & Paquette, J. (2023). pyNuMAD 1.0.0. Zenodo. https://doi.org/10.5281/zenodo.10023189 +[1] Camarena, E., Anderson, E., Bonney, K. L., Clarke, R. J., & Paquette, J. (2023). opensg 1.0.0. Zenodo. https://doi.org/10.5281/zenodo.10023189 .. _developers: -pyNuMAD Developers +opensg Developers ===================== -pyNuMAD has been developed by `Sandia National Laboratories +opensg has been developed by `Sandia National Laboratories (Sandia) `_, funded by the U.S. Department of Energy’s Wind Energy Technologies Technologies Office. diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..ba3a940 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,19 @@ +.. _license: + +License +======= +TODO (Any Sandia statements needed?) + +.. Copyright +.. ------------ + +.. .. literalinclude:: ../NOTICE +.. :language: text + + +MIT License +----------- + +.. literalinclude:: ../LICENSE + :language: text + diff --git a/docs/publications.rst b/docs/publications.rst new file mode 100644 index 0000000..0dd14de --- /dev/null +++ b/docs/publications.rst @@ -0,0 +1,7 @@ +.. _publications: + +Publications +============ + +.. .. bibliography:: refs/publications.bib +.. :all: \ No newline at end of file diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..0c93c8a --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,10 @@ +.. _release-notes: + +Release Notes +============= + +.. _opensgv0.0.1: + +0.0.1 +----- +TODO \ No newline at end of file diff --git a/docs/user-guide/getting-started.rst b/docs/user-guide/getting-started.rst new file mode 100644 index 0000000..b56586e --- /dev/null +++ b/docs/user-guide/getting-started.rst @@ -0,0 +1,6 @@ +.. _getting-started: + +Getting Started +=============== + +TODO \ No newline at end of file diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst index ccd24e1..9d593b9 100644 --- a/docs/user-guide/index.rst +++ b/docs/user-guide/index.rst @@ -13,10 +13,5 @@ User’s Guide .. toctree:: :maxdepth: 2 - :caption: User Interface + :caption: Opensg Interface - blade_definition - meshing - beam_models - shell_models - solid_models diff --git a/docs/user-guide/installation.rst b/docs/user-guide/installation.rst index 3622729..4afe50a 100644 --- a/docs/user-guide/installation.rst +++ b/docs/user-guide/installation.rst @@ -3,17 +3,17 @@ Installation ============ -Download pyNuMAD +Download opensg ---------------- -The OpenSG source code is hosted on the `opensg GitHub repository `_. +The OpenSG source code is hosted on the `opensg GitHub repository `_. OpenSG users are recommended to clone the Github repository. -Cloning the repository allows users to easily pull the latest updates to the pyNuMAD source code. +Cloning the repository allows users to easily pull the latest updates to the opensg source code. These updates may improve the code's speed, accuracy and add additional functionality or advanced features. To download OpenSG using `git `_, type the following in a git interface:: - git clone https://github.com/sandialabs/pyNuMAD + git clone https://github.com/wenbinyugroup/opensg Installation ------------ @@ -22,7 +22,7 @@ To install OpenSG and create an environment where the code runs correctly, pleas 1. Download the OpenSG repository:: - git clone https://github.com/sandialabs/pyNuMAD + git clone https://github.com/wenbinyugroup/opensg 2. Create the conda environment named `opensg_env` using the `environment.yml` file:: diff --git a/docs/user-guide/overview.rst b/docs/user-guide/overview.rst new file mode 100644 index 0000000..41dfae2 --- /dev/null +++ b/docs/user-guide/overview.rst @@ -0,0 +1,6 @@ +.. _overview: + +Overview +======================= + +TODO \ No newline at end of file diff --git a/noxfile.py b/noxfile.py index 0c1bd30..707bfc5 100644 --- a/noxfile.py +++ b/noxfile.py @@ -32,14 +32,14 @@ def serve(session): port = "8085" session.run("python", "-m", "http.server", "-b", "localhost", "-d", "docs/_build/html", port) -@nox.session -def check_style(session): - """Check if code follows black style.""" - session.install("black") - session.run("black", "--check", "src") +# @nox.session +# def check_style(session): +# """Check if code follows black style.""" +# session.install("black") +# session.run("black", "--check", "src") -@nox.session -def enforce_style(session): - """Apply black style to code base.""" - session.install("black") - session.run("black", "src") +# @nox.session +# def enforce_style(session): +# """Apply black style to code base.""" +# session.install("black") +# session.run("black", "src")