diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py index 61eff5eb4..eec436ac9 100644 --- a/doc/sphinx/source/conf.py +++ b/doc/sphinx/source/conf.py @@ -1,202 +1,205 @@ # -*- coding: utf-8 -*- # # Configuration file for the Sphinx documentation builder. # # This file does only contain a selection of the most common options. For a # full list see the documentation: # http://www.sphinx-doc.org/en/master/config # -- 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 subprocess # import sys # sys.path.insert(0, os.path.abspath('.')) # -- Project information ----------------------------------------------------- project = 'Akantu' copyright = '2019-20, Laboratoire de Simulation en Mécanique des Solides, EPFL' author = 'Nicolas Richart' # The short X.Y version version = '' # The full version, including alpha/beta/rc tags release = '3.0.0' # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. # # needs_sphinx = '1.0' +# Number figures +numfig = True + # 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.mathjax', 'sphinx.ext.viewcode', # 'breathe' ] # Add any paths that contain templates here, relative to this directory. templates_path = ['.templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The master toctree document. master_doc = 'index' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None # 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 = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = None # Default programming language highlight_language = 'cpp' # -- 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' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # # html_theme_options = {} # 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'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. # # The default sidebars (for documents that don't match any pattern) are # defined by theme itself. Builtin themes are using these templates by # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', # 'searchbox.html']``. # # html_sidebars = {} # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = 'Akantudoc' # -- Options for LaTeX output ------------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # # 'preamble': '', # Latex figure (float) alignment # # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'Akantu.tex', 'Akantu Documentation', 'Nicolas Richart', 'manual'), ] # -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'akantu', 'Akantu Documentation', [author], 1) ] # -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'Akantu', 'Akantu Documentation', author, 'Akantu', 'One line description of project.', 'Miscellaneous'), ] # -- Options for Epub output ------------------------------------------------- # Bibliographic Dublin Core info. epub_title = project # The unique identifier of the text. This can be a ISBN number # or the project homepage. # # epub_identifier = '' # A unique identification for the text. # # epub_uid = '' # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] # -- Extension configuration ------------------------------------------------- # If on RTD build, run doxygen # on_read_the_docs = os.environ.get('READTHEDOCS') == 'True' # if on_read_the_docs: # subprocess.call('cd ../../; mkdir -p build/doxygen; ' # + 'doxygen doxygen/Doxyfile', shell=True) # breathe_projects = { # 'akantu': '../../../build/doc/doxygen/xml' # } # breathe_default_project = 'akantu' intersphinx_mapping = { 'numpy': ('https://docs.scipy.org/doc/numpy/', None), 'scipy': ('https://docs.scipy.org/doc/scipy/reference', None), } diff --git a/doc/sphinx/source/fe_engine.rst b/doc/sphinx/source/fe_engine.rst new file mode 100644 index 000000000..4b4fa0e87 --- /dev/null +++ b/doc/sphinx/source/fe_engine.rst @@ -0,0 +1,183 @@ +``FEEngine`` +============ + +The ``FEEngine`` interface is dedicated to handle the +finite-element approximations and the numerical integration of the +weak form. As we will see in Chapter sect:smm, ``Model`` +creates its own ``FEEngine`` object so the explicit creation of the +object is not required. + +Mathematical Operations +----------------------- + +Using the ``FEEngine`` object, one can compute a interpolation, an +integration or a gradient. A simple example is given below:: + + // having a FEEngine object + std::unique_ptr fem = + std::make_unique>( + my_mesh, dim, "my_fem"); + // instead of this, a FEEngine object can be get using the model: + // model.getFEEngine() + + //compute the gradient + Array u; //append the values you want + Array nablauq; //gradient array to be computed + // compute the gradient + fem->gradientOnIntegrationPoints(const Array &u, + Array &nablauq, + const UInt nb_degree_of_freedom, + const ElementType & type); + + // interpolate + Array uq; //interpolated array to be computed + // compute the interpolation + fem->interpolateOnIntegrationPoints(const Array &u, + Array &uq, + UInt nb_degree_of_freedom, + const ElementType & type); + + // interpolated function can be integrated over the elements + Array int_val_on_elem; + // integrate + fem->integrate(const Array &uq, + Array &int_uq, + UInt nb_degree_of_freedom, + const ElementType & type); + +Another example below shows how to integrate stress and strain fields +over elements assigned to a particular material:: + + UInt sp_dim = 3; //spatial dimension + UInt m = 1; //material index of interest + const ElementType type = _tetrahedron_4; //element type + + // get the stress and strain arrays associated to the material index m + const Array & strain_vec = model.getMaterial(m).getGradU(type); + const Array & stress_vec = model.getMaterial(m).getStress(type); + + // get the element filter for the material index + const Array & elem_filter = model.getMaterial(m).getElementFilter(type); + + // initialize the integrated stress and strain arrays + Array int_strain_vec(elem_filter.getSize(), + sp_dim*sp_dim, "int_of_strain"); + Array int_stress_vec(elem_filter.getSize(), + sp_dim*sp_dim, "int_of_stress"); + + // integrate the fields + model.getFEEngine().integrate(strain_vec, int_strain_vec, + sp_dim*sp_dim, type, _not_ghost, elem_filter); + model.getFEEngine().integrate(stress_vec, int_stress_vec, + sp_dim*sp_dim, type, _not_ghost, elem_filter); + +Elements +-------- + +The base for every Finite-Elements computation is its mesh and the elements that +are used within that mesh. The element types that can be used depend on the +mesh, but also on the dimensionality of the problem (1D, 2D or 3D). In Akantu, +several isoparametric Lagrangian element types are supported (and one +serendipity element). Each of these types is discussed in some detail below, +starting with the 1D-elements all the way to the 3D-elements. More detailed +information (shape function, location of Gaussian quadrature points, and so on) +can be found in Appendix app:elements. + +Isoparametric Elements +...................... + +1D +```` + +In Akantu, there are two types of isoparametric elements defined in 1D. These +element types are called ``_segment_2`` and ``_segment_3``, and are +depicted schematically in :numref:`fig:elements:1D`. Some of the basic +properties of these elements are listed in :numref:`tab:elements:1D`. + +.. _fig:elements:1D: +.. figure:: figures/elements/segments.svg + :align: center + + Schematic overview of the two 1D element types in Akantu. In each + element, the node numbering as used in Akantu is indicated and also the + quadrature points are highlighted (gray circles). + + +.. _tab:elements:1D: +.. table:: Some basic properties of the two 1D isoparametric elements in Akantu + + +--------------+---------+------+------+ + |Element |Order |#nodes|#quad | + |type | | |points| + +--------------+---------+------+------+ + |``_segment_2``|linear |2 |1 | + +--------------+---------+------+------+ + |``_segment_3``|quadratic|3 |2 | + +--------------+---------+------+------+ + +2D +```` +In Akantu, there are four types of isoparametric elements defined in 2D. These +element types are called ``_triangle_3``, ``_triangle_6``, +``_quadrangle_4`` and ``_quadrangle_8``, and all of them are depicted +in :numref:`fig:elements:2D`. As with the 1D elements, some of the most basic +properties of these elements are listed in :numref:`tab:elements:2D`. It is +important to note that the first element is linear, the next two quadratic and +the last one cubic. Furthermore, the last element type (``_quadrangle_8``) +is not a Lagrangian but a serendipity element. + +.. _fig:elements:2D: +.. figure:: figures/elements/elements_2d.svg + :align: center + + Schematic overview of the four 2D element types in Akantu. In each + element, the node numbering as used in Akantu is indicated and also the + quadrature points are highlighted (gray circles). + + +.. _tab:elements:2D: +.. table:: Some basic properties of the 2D isoparametric elements in Akantu + + +--------------------+----------+------+------+ + |Element |Order |#nodes|#quad | + |type | | |points| + +--------------------+----------+------+------+ + |``_triangle_3`` |linear |3 |1 | + +--------------------+----------+------+------+ + |``_triangle_6`` |quadratic |6 |3 | + +--------------------+----------+------+------+ + |``_quadrangle_4`` |linear |4 |4 | + +--------------------+----------+------+------+ + |``_quadrangle_8`` |quadratic |8 |9 | + +--------------------+----------+------+------+ + +3D +```` + +In Akantu, there are three types of isoparametric elements defined in 3D. These +element types are called ``_tetrahedron_4``, ``_tetrahedron_10`` and +``_hexahedron_8``, and all of them are depicted schematically in +:numref:`fig:elements:3D`. As with the 1D and 2D elements some of the most +basic properties of these elements are listed in :numref:`tab:elements:3D`. + +.. _fig:elements:3D: +.. figure:: figures/elements/elements_3d.svg + :align: center + + Schematic overview of the three 3D element types in Akantu. In each + element, the node numbering as used in Akantu is indicated and also the + quadrature points are highlighted (gray circles). + +.. _tab:elements:3D: +.. table:: Some basic properties of the 3D isoparametric elements in Akantu + + +--------------------+----------+------+------+ + |Element |Order |#nodes|#quad | + |type | | |points| + +--------------------+----------+------+------+ + |``_tetrahedron_4`` |linear |4 |1 | + +--------------------+----------+------+------+ + |``_tetrahedron_10`` |quadratic |10 |4 | + +--------------------+----------+------+------+ + |``_hexadedron_8`` |cubic |8 |8 | + +--------------------+----------+------+------+ diff --git a/doc/sphinx/source/figures/elements/elements_2d.svg b/doc/sphinx/source/figures/elements/elements_2d.svg new file mode 100644 index 000000000..333418b77 --- /dev/null +++ b/doc/sphinx/source/figures/elements/elements_2d.svg @@ -0,0 +1,2144 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/sphinx/source/figures/elements/elements_3d.svg b/doc/sphinx/source/figures/elements/elements_3d.svg new file mode 100644 index 000000000..7f1e81017 --- /dev/null +++ b/doc/sphinx/source/figures/elements/elements_3d.svg @@ -0,0 +1,4975 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/sphinx/source/figures/elements/segments.svg b/doc/sphinx/source/figures/elements/segments.svg new file mode 100644 index 000000000..489bbd948 --- /dev/null +++ b/doc/sphinx/source/figures/elements/segments.svg @@ -0,0 +1,1173 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index 0abaed090..a96f150b9 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -1,24 +1,25 @@ .. Akantu documentation master file, created by sphinx-quickstart on Wed Dec 11 17:41:48 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Akantu's documentation! ================================== .. toctree:: :maxdepth: 2 :caption: Contents: ./getting_started + ./fe_engine Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`