diff --git a/CMakeLists.txt b/CMakeLists.txt index c8d4c7613..1c69954cc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,210 +1,212 @@ #=============================================================================== # @file CMakeLists.txt # # @author Guillaume Anciaux # @author Nicolas Richart # # @date creation: Mon Jun 14 2010 # @date last modification: Fri Jan 22 2016 # # @brief main configuration file # # @section LICENSE # # Copyright (©) 2010-2012, 2014, 2015 EPFL (Ecole Polytechnique Fédérale de # Lausanne) Laboratory (LSMS - Laboratoire de Simulation en Mécanique des # Solides) # # Akantu is free software: you can redistribute it and/or modify it under the # terms of the GNU Lesser General Public License as published by the Free # Software Foundation, either version 3 of the License, or (at your option) any # later version. # # Akantu is distributed in the hope that it will be useful, but WITHOUT ANY # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR # A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more # details. # # You should have received a copy of the GNU Lesser General Public License # along with Akantu. If not, see . # # @section DESCRIPTION #------------------------------------------------------------------------------- # _ _ # | | | | # __ _| | ____ _ _ __ | |_ _ _ # / _` | |/ / _` | '_ \| __| | | | # | (_| | < (_| | | | | |_| |_| | # \__,_|_|\_\__,_|_| |_|\__|\__,_| # #=============================================================================== #=============================================================================== # CMake Project #=============================================================================== cmake_minimum_required(VERSION 3.5.1) # add this options before PROJECT keyword set(CMAKE_DISABLE_SOURCE_CHANGES ON) set(CMAKE_DISABLE_IN_SOURCE_BUILD ON) if(CMAKE_VERSION VERSION_GREATER 3.12) cmake_policy(SET CMP0074 NEW) endif() set(AKANTU_MAJOR_VERSION 3) set(AKANTU_MINOR_VERSION 1) set(AKANTU_PATCH_VERSION 0) +set(AKANTU_COPYRING "2010-2020, EPFL (Ecole Polytechnique Fédérale de Lausanne) Laboratory (LSMS - Laboratoire de Simulation en Mécanique des Solides)") +set(AKANTU_MAINTAINER "Nicolas Richart") project(Akantu HOMEPAGE_URL "htpps://akantu.ch") enable_language(CXX) #=============================================================================== # Misc. config for cmake #=============================================================================== set(AKANTU_CMAKE_DIR "${PROJECT_SOURCE_DIR}/cmake") set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${PROJECT_SOURCE_DIR}/cmake") set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${PROJECT_SOURCE_DIR}/cmake/Modules") set(BUILD_SHARED_LIBS ON CACHE BOOL "Build shared libraries.") set(CMAKE_EXPORT_COMPILE_COMMANDS ON CACHE BOOL "Enable/Disable output of compile commands during generation" FORCE) mark_as_advanced(BUILD_SHARED_LIBS) if(NOT AKANTU_TARGETS_EXPORT) set(AKANTU_TARGETS_EXPORT AkantuTargets) endif() include(CMakeVersionGenerator) include(CMakePackagesSystem) include(CMakeFlagsHandling) include(AkantuPackagesSystem) include(AkantuMacros) include(AkantuCleaning) #cmake_activate_debug_message() include(GNUInstallDirs) set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib") # add the automatically determined parts of the RPATH # which point to directories outside the build tree to the install RPATH set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE) #=============================================================================== # Version Number #=============================================================================== # AKANTU version number. An even minor number corresponds to releases. define_project_version() #=============================================================================== # Options #=============================================================================== # Debug set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG -DAKANTU_NDEBUG" CACHE STRING "Flags used by the compiler during release builds" FORCE) #add_flags(cxx "-Wall -Wextra -pedantic -Werror") if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR CMAKE_CXX_COMPILER_ID STREQUAL "Clang") add_flags(cxx "-Wall -Wextra -pedantic") # -Weffc++ set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG_INIT} -ggdb3" CACHE STRING "Flags used by the compiler during debug builds" FORCE) set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT} -ggdb3" CACHE STRING "Flags used by the compiler during debug builds" FORCE) else() add_flags(cxx "-Wall") endif() option(AKANTU_EXAMPLES "Activate examples" OFF) option(AKANTU_TESTS "Activate tests" OFF) option(AKANTU_RUN_IN_DOCKER "Set the approriate flage tu run in docker" OFF) set(AKANTU_PREFERRED_PYTHON_VERSION 3 CACHE STRING "Preferred version for python related things") mark_as_advanced(AKANTU_PREFERRED_PYTHON_VERSION AKANTU_RUN_IN_DOCKER) include(AkantuExtraCompilationProfiles) #=============================================================================== # Dependencies #=============================================================================== declare_akantu_types() package_list_packages(${PROJECT_SOURCE_DIR}/packages EXTRA_PACKAGES_FOLDER ${PROJECT_SOURCE_DIR}/extra_packages NO_AUTO_COMPILE_FLAGS) ## meta option \todo better way to do it when multiple package give enable the ## same feature if(AKANTU_SCOTCH) set(AKANTU_PARTITIONER ON) else() set(AKANTU_PARTITIONER OFF) endif() if(AKANTU_MUMPS) set(AKANTU_SOLVER ON) else() set(AKANTU_SOLVER OFF) endif() #=============================================================================== # Akantu library #=============================================================================== add_subdirectory(src) #=============================================================================== # Documentation #=============================================================================== if(AKANTU_DOCUMENTATION_DEVELOPER_MANUAL OR AKANTU_DOCUMENTATION_USER_MANUAL) add_subdirectory(doc) else() set(AKANTU_DOC_EXCLUDE_FILES "${PROJECT_SOURCE_DIR}/doc/manual" CACHE INTERNAL "") endif() #=============================================================================== # Python interface #=============================================================================== package_is_activated(python_interface _python_act) if(_python_act) if(IS_ABSOLUTE "${CMAKE_INSTALL_PREFIX}") set(AKANTU_PYTHON_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}) else() set(AKANTU_PYTHON_INSTALL_PREFIX "${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_PREFIX}") endif() add_subdirectory(python) endif() #=============================================================================== # Examples and tests #=============================================================================== include(AkantuTestsMacros) include(AkantuExampleMacros) if(AKANTU_TESTS) option(AKANTU_BUILD_ALL_TESTS "Build all tests" ON) find_package(GMSH REQUIRED) endif() # tests add_test_tree(test) if(AKANTU_EXAMPLES) if(AKANTU_TESTS) option(AKANTU_TEST_EXAMPLES "Run the examples" ON) endif() find_package(GMSH REQUIRED) add_subdirectory(examples) endif() #=============================================================================== # Install and Packaging #=============================================================================== include(AkantuInstall) option(AKANTU_DISABLE_CPACK "This option commands the generation of extra info for the \"make package\" target" ON) mark_as_advanced(AKANTU_DISABLE_CPACK) if(NOT AKANTU_DISABLE_CPACK) include(AkantuCPack) endif() diff --git a/doc/dev-doc/CMakeLists.txt b/doc/dev-doc/CMakeLists.txt index 7cf00e618..32ad1a411 100644 --- a/doc/dev-doc/CMakeLists.txt +++ b/doc/dev-doc/CMakeLists.txt @@ -1,181 +1,184 @@ set(DOXYGEN_INPUT_DOX ${CMAKE_CURRENT_BINARY_DIR}/akantu.dox) set(DOXYGEN_XML_DIR ${CMAKE_CURRENT_BINARY_DIR}/xml) set(DOXYGEN_OUTPUT ${DOXYGEN_XML_DIR}/index.xml) # configured documentation tools and intermediate build results set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build") # Sphinx cache with pickled ReST documents set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees") # HTML output directory set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html") set(SPHINX_OUTPUT "${SPHINX_HTML_DIR}/index.html") # ---------------------------------------------------------------------------- # # Doxygen # # ---------------------------------------------------------------------------- # find_package(Doxygen REQUIRED) set(DOXYGEN_WARNINGS NO) set(DOXYGEN_QUIET YES) if(CMAKE_VERBOSE_MAKEFILE) set(DOXYGEN_WARNINGS YES) set(DOXYGEN_QUIET NO) endif(CMAKE_VERBOSE_MAKEFILE) package_get_all_source_files( AKANTU_LIBRARY_SRCS AKANTU_LIBRARY_PUBLIC_HDRS AKANTU_LIBRARY_PRIVATE_HDRS ) package_get_all_include_directories( _akantu_include_dirs ) package_get_all_external_informations( PRIVATE_INCLUDE AKANTU_PRIVATE_EXTERNAL_INCLUDE_DIR INTERFACE_INCLUDE AKANTU_INTERFACE_EXTERNAL_INCLUDE_DIR LIBRARIES AKANTU_EXTERNAL_LIBRARIES ) list(APPEND _akantu_include_dirs ${AKANTU_PRIVATE_EXTERNAL_INCLUDE_DIR} ${AKANTU_INTERFACE_EXTERNAL_INCLUDE_DIR} ${PROJECT_BINARY_DIR}/src) file(STRINGS ${PROJECT_SOURCE_DIR}/.clang-format AKANTU_TAB_SIZE REGEX "^TabWidth: *([0-9]*)" ) string(REGEX REPLACE ".*([0-9]+)" "\\1" AKANTU_TAB_SIZE "${AKANTU_TAB_SIZE}") if (CMAKE_VERSION VERSION_GREATER 3.9.5) #set(DOXYGEN_WARNINGS YES) #set(DOXYGEN_QUIET NO) set(DOXYGEN_STRIP_FROM_PATH ${PROJECT_SOURCE_DIR}) set(DOXYGEN_STRIP_FROM_INC_PATH ${PROJECT_SOURCE_DIR}) set(DOXYGEN_TAB_SIZE ${AKANTU_TAB_SIZE}) set(DOXYGEN_ALIASES "rst=\\verbatim embed:rst" "endrst=\\endverbatim" ) set(DOXYGEN_WARN_IF_UNDOCUMENTED NO) set(DOXYGEN_WARN_IF_DOC_ERROR YES) set(DOXYGEN_WARN_AS_ERROR NO) set(DOXYGEN_EXCLUDE "${PROJECT_SOURCE_DIR}/src/common/aka_fwd.hh") set(DOXYGEN_RECURSIVE YES) set(DOXYGEN_EXCLUDE "aka_named_argument.hh" ) set(DOXYGEN_EXAMPLE_PATH "${PROJECT_SOURCE_DIR}/examples") set(DOXYGEN_EXAMPLE_RECURSIVE YES) set(DOXYGEN_SOURCE_BROWSER NO) set(DOXYGEN_CLANG_ASSISTED_PARSING NO) #set(DOXYGEN_CLANG_OPTIONS ) set(DOXYGEN_CLANG_DATABASE_PATH ${CMAKE_BINARY_DIR}) set(DOXYGEN_USE_MATHJAX YES) set(DOXYGEN_GENERATE_HTML NO) set(DOXYGEN_GENERATE_HTMLHELP NO) set(DOXYGEN_GENERATE_LATEX NO) set(DOXYGEN_GENERATE_XML YES) set(DOXYGEN_XML_OUTPUT xml) set(DOXYGEN_ENABLE_PREPROCESSING YES) set(DOXYGEN_MACRO_EXPANSION YES) set(DOXYGEN_INCLUDE_PATH ${_akantu_include_dirs}) set(DOXYGEN_PREDEFINED ${AKANTU_DEFINITIONS} "DOXYGEN" "AKANTU_TO_IMPLEMENT()=" "DECLARE_NAMED_ARGUMENT()=" "OPTIONAL_NAMED_ARGUMENT(n, v)=v" "REQUIRED_NAMED_ARGUMENT(n)=" ) set(DOXYGEN_COLLABORATION_GRAPH NO) set(DOXYGEN_UML_LOOK YES) set(DOXYGEN_TEMPLATE_RELATIONS YES) set(DOXYGEN_CALL_GRAPH YES) set(DOXYGEN_CALLER_GRAPH YES) set(DOXYGEN_DOT_GRAPH_MAX_NODES 500) set(DOXYGEN_SHOW_FILES NO) set(DOXYGEN_LOOKUP_CACHE_SIZE 9) set(_SRCS ${AKANTU_LIBRARY_SRCS} ${AKANTU_LIBRARY_PUBLIC_HDRS} ${AKANTU_LIBRARY_PRIVATE_HDRS} ) list(REMOVE_ITEM _SRCS "${PROJECT_SOURCE_DIR}/src/common/aka_named_argument.hh") doxygen_add_docs(doxygen-doc ${_SRCS} USE_STAMP_FILE COMMENT "Building XML documentation with Doxygen in ${DOXYGEN_XML_DIR}" ) else() string(REGEX REPLACE ";" " " AKANTU_DOXYGEN_DEFINTIONS "${AKANTU_DEFINITIONS};DOXYGEN") string(REGEX REPLACE ";" " " AKANTU_DOXYGEN_INCLUDE_DIRS "${_akantu_include_dirs}") make_directory(${DOXYGEN_XML_DIR}) configure_file(${CMAKE_CURRENT_SOURCE_DIR}/akantu.dox.in ${DOXYGEN_INPUT_DOX} ) add_custom_command( OUTPUT ${DOXYGEN_OUTPUT} COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT_DOX} DEPENDS ${DOXYGEN_INPUT_DOX} COMMENT "Building XML documentation with Doxygen in ${DOXYGEN_XML_DIR}" ) add_custom_target(doxygen-doc ALL DEPENDS ${DOXYGEN_OUTPUT} ) add_custom_target(doxygen-doc-forced COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT} COMMENT "Building XML documentation with Doxygen (forced) in ${DOXYGEN_XML_DIR}" ) endif() # ---------------------------------------------------------------------------- # # Sphinx # # ---------------------------------------------------------------------------- # find_package(Sphinx REQUIRED) set(SPHINX_VERBOSE_FLAG "-q") if(CMAKE_VERBOSE_MAKEFILE) set(SPHINX_VERBOSE_FLAG) endif(CMAKE_VERBOSE_MAKEFILE) configure_file( "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in" "${CMAKE_CURRENT_BINARY_DIR}/conf.py" @ONLY) set(_sphinx_command ${SPHINX_BUILD_EXECUTABLE} -j auto ${SPHINX_VERBOSE_FLAG} -b html -c "${CMAKE_CURRENT_BINARY_DIR}" -d "${SPHINX_CACHE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}" "${SPHINX_HTML_DIR}" ) +file(GLOB_RECURSE _SPHINX_SRCS + "*.rst") + add_custom_command( OUTPUT ${SPHINX_OUTPUT} COMMAND ${_sphinx_command} - DEPENDS doxygen-doc ${SPHINX_INPUT} + DEPENDS doxygen-doc ${SPHINX_INPUT} ${_SPHINX_SRCS} COMMENT "Building HTML documentation with Sphinx in ${SPHINX_HTML_DIR}" ) add_custom_target(sphinx-doc ALL DEPENDS ${SPHINX_OUTPUT}) add_custom_target(sphinx-doc-forced COMMAND ${_sphinx_command} DEPENDS doxygen-doc COMMENT "Building HTML documentation with Sphinx (forced) in ${SPHINX_HTML_DIR}" ) diff --git a/doc/dev-doc/conf.py.in b/doc/dev-doc/conf.py.in index d297e8743..fb87b1f96 100644 --- a/doc/dev-doc/conf.py.in +++ b/doc/dev-doc/conf.py.in @@ -1,214 +1,212 @@ # -*- 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 = '2020, EPFL LSMS' -author = 'Nicolas Richart' +project = '@PROJECT_NAME@' +copyright = '@AKANTU_COPYRING@' +author = '@AKANTU_MAINTAINER@' -# The short X.Y version -version = '' +version = '@AKANTU_VERSION_MAJOR@.@AKANTU_VERSION_MINOR@' # The full version, including alpha/beta/rc tags -release = '3.1.0' - +release = '@AKANTU_VERSION@' # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. # # needs_sphinx = '1.0' # 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.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'breathe', ] read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' -if read_the_docs_build: - print("${READTHEDOCS} = " + os.environ.get('READTHEDOCS')) - -if read_the_docs_build: - akantu_path = "." -else: - akantu_path = "@CMAKE_CURRENT_BINARY_DIR@" - os.makedirs("@CMAKE_CURRENT_BINARY_DIR@/_static", exist_ok=True) - -# print("akantu_path = '{}'".format(akantu_path)) -breathe_projects = {"Akantu": os.path.join(akantu_path, "xml")} -breathe_default_project = "Akantu" # 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 = ["CMakeLists.txt"] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +primary_domain = 'cpp' +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. # if read_the_docs_build: html_theme = 'default' else: 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 = {} html_sidebars = { '**': [ 'relations.html', # needs 'show_related': True theme option to display - 'searchbox.html', ] } + 'searchbox.html', + ]} # -- 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': r'''\usepackage{amsmath}''', # 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 epub_author = author epub_publisher = author epub_copyright = copyright # 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 read_the_docs_build: + akantu_path = "." +else: + akantu_path = "@CMAKE_CURRENT_BINARY_DIR@" + os.makedirs("@CMAKE_CURRENT_BINARY_DIR@/_static", exist_ok=True) + +# print("akantu_path = '{}'".format(akantu_path)) +breathe_projects = {"Akantu": os.path.join(akantu_path, "xml")} +breathe_default_project = "Akantu" # -- Options for intersphinx extension --------------------------------------- -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} -primary_domain = 'cpp' -highlight_language = 'cpp' +intersphinx_mapping = { + 'numpy': ('https://docs.scipy.org/doc/numpy/', None), + 'scipy': ('https://docs.scipy.org/doc/scipy/reference', None), +} diff --git a/doc/dev-doc/manual/getting_started.rst b/doc/dev-doc/manual/getting_started.rst index 5b8fc9157..ffd4b4bb3 100644 --- a/doc/dev-doc/manual/getting_started.rst +++ b/doc/dev-doc/manual/getting_started.rst @@ -1,324 +1,302 @@ Getting Started =============== Compiling Akantu ---------------- Akantu is a `CMake `_ project, so to configure it, you can either follow the usual way:: > cd akantu > mkdir build > cd build > ccmake .. [ Set the options that you need ] > make > make install -Or, use the ``Makefile`` we added for your convenience to -handle the CMake configuration:: - - > cd akantu - > make config - > make - > make install - All the Akantu options are documented in Appendix app:package-dependencies. Writing a ``main`` function --------------------------- Akantu first needs to be initialized. The memory management included in the core library handles the correct allocation and de-allocation of vectors, structures and/or objects. Moreover, in parallel computations, the initialization procedure -performs the communication setup. This is achieved by a pair of functions -(:cpp:func:`initialize ` and :cpp:func:`finalize -`) that are used as follows:: +performs the communication setup. This is achieved by the function +:cpp:func:`initialize ` that is used as follows:: #include "aka_common.hh" #include "..." using namespace akantu; int main(int argc, char *argv[]) { initialize("input_file.dat", argc, argv); // your code ... - finalize(); } The :cpp:func:`initialize ` function takes the text inpute file and the program parameters which can be parsed by Akantu in due form (see sect:parser). Obviously it is necessary to include all files needed in main. In this manual all provided code implies the usage of ``akantu`` as namespace. Creating and Loading a Mesh --------------------------- In its current state, Akantu supports three types of meshes: Gmsh, Abaqus and Diana. Once a :cpp:class:`akantu::Mesh` object is created with a given spatial dimension, it can be filled by reading a mesh input file. The method :cpp:func:`read ` of the class :cpp:class:`Mesh ` infers the mesh type from the file extension. If a non-standard file extension is used, the mesh type has to be specified. :: UInt spatial_dimension = 2; Mesh mesh(spatial_dimension); // Reading Gmsh files mesh.read("my_gmsh_mesh.msh"); mesh.read("my_gmsh_mesh", _miot_gmsh); - // Reading Abaqus files - mesh.read("my_abaqus_mesh.inp"); - mesh.read("my_abaqus_mesh", _miot_abaqus); - - // Reading Diana files - mesh.read("my_diana_mesh.dat"); - mesh.read("my_diana_mesh", _miot_diana); - The Gmsh reader adds the geometrical and physical tags as mesh data. The physical values are stored as a :cpp:type:`UInt ` data called ``tag_0``, if a string name is provided it is stored as a ``std::string`` data named ``physical_names``. The geometrical tag is stored as a :cpp:type:`UInt ` data named ``tag_1``. -The Abaqus reader stores the ``ELSET`` in ElementGroups and the ``NSET`` -in NodeGroups. The material assignment can be retrieved from the -``std::string`` mesh data named ``abaqus_material``. - Using Arrays ------------ Data in Akantu can be stored in data containers implemented by the :cpp:class:`akantu::Array` class. In its most basic usage, the :cpp:class:`Array ` class implemented in \akantu is similar to the ``std::vector`` class of the Standard Template Library (STL) for C++. A simple :cpp:class:`Array ` containing a sequence of ``nb_element`` values (of a given type) can be generated with:: Array example_array(nb_element); where ``type`` usually is ``Real``, ``Int``, ``UInt`` or ``bool``. Each value is associated to an index, so that data can be accessed by typing:: auto & val = example_array(index); ``Arrays`` can also contain tuples of values for each index. In that case, the number of components per tuple must be specified at the :cpp:class:`Array ` creation. For example, if we want to create an :cpp:class:`Array ` to store the coordinates (sequences of three values) of ten nodes, the appropriate code is the following:: UInt nb_nodes = 10; UInt spatial_dimension = 3; Array position(nb_nodes, spatial_dimension); In this case the :math:`x` position of the eighth node number will be given by ``position(7, 0)`` (in C++, numbering starts at 0 and not 1). If the number of components for the sequences is not specified, the default value of 1 is used. Here is a list of some basic operations that can be performed on :cpp:class:`Array `: - ``resize(size)`` change the size of the :cpp:class:`Array `. - ``clear()`` set all entries of the :cpp:class:`Array ` to zero. - ``set(t)`` set all entries of the :cpp:class:`Array ` to ``t``. - ``copy(const Array & other)`` copy another :cpp:class:`Array ` into the current one. The two :cpp:class:`Array ` should have the same number of components. - ``push_back(tuple)`` append a tuple with the correct number of components at the end of the :cpp:class:`Array `. - ``erase(i)`` erase the value at the i-th position. - ``find(value)`` search ``value`` in the current :cpp:class:`Array `. Return position index of the first occurence or -1 if not found. - ``storage()`` Return the address of the allocated memory of the :cpp:class:`Array `. Array iterators ------------------- It is very common in Akantu to loop over arrays to perform a specific treatment. This ranges from geometric calculation on nodal quantities to tensor algebra (in constitutive laws for example). The :cpp:class:`Array ` object has the possibility to request iterators in order to make the writing of loops easier and enhance readability. For instance, a loop over the nodal coordinates can be performed like:: // accessing the nodal coordinates Array // with spatial_dimension components const auto & nodes = mesh.getNodes(); for (const auto & coords : make_view(nodes, spatial_dimension)) { // do what you need .... } In that example, each ``coords`` is a ``Vector`` containing geometrical array of size ``spatial_dimension`` and the iteration is conveniently performed by the :cpp:class:`Array ` iterator. The :cpp:class:`Array ` object is intensively used to store second order tensor values. In that case, it should be specified that the returned object type is a matrix when constructing the iterator. This is done when calling the :cpp:func:`make_view `. For instance, assuming that we have a :cpp:class:`Array ` storing stresses, we can loop over the stored tensors by:: for (const auto & stress : make_view(stresses, spatial_dimension, spatial_dimension)) { // stress is of type `const Matrix&` } In that last example, the :cpp:class:`Matrix ` objects are ``spatial_dimension`` :math:`\times` ``spatial_dimension`` matrices. The light objects :cpp:class:`Matrix ` and :cpp:class:`Vector ` can be used and combined to do most common linear algebra. If the number of component is 1, it is possible to use :cpp:func:`make_view ` to this effect. In general, a mesh consists of several kinds of elements. Consequently, the amount of data to be stored can differ for each element type. The straightforward example is the connectivity array, namely the sequences of nodes belonging to each element (linear triangular elements have fewer nodes than, say, rectangular quadratic elements etc.). A particular data structure called :cpp:class:`ElementTypeMapArray ` is provided to easily manage this kind of data. It consists of a group of ``Arrays``, each associated to an element type. The following code can retrieve the ``ElementTypeMapArray`` which stores the connectivity arrays for a mesh:: const ElementTypeMapArray & connectivities = mesh.getConnectivities(); Then, the specific array associated to a given element type can be obtained by:: const Array & connectivity_triangle = connectivities(_triangle_3); where the first order 3-node triangular element was used in the presented piece of code. Vector & Matrix ``````````````` The :cpp:class:`Array ` iterators as presented in the previous section can be shaped as :cpp:class:`Vector ` or :cpp:class:`Matrix `. This objects represent 1st and 2nd order tensors. As such they come with some functionalities that we will present a bit more into detail in this here. ``Vector`` ''''''''''''' - Accessors: - ``v(i)`` gives the ``i`` -th component of the vector ``v`` - ``v[i]`` gives the ``i`` -th component of the vector ``v`` - ``v.size()`` gives the number of component - Level 1: (results are scalars) - ``v.norm()`` returns the geometrical norm (:math:`L_2`) - ``v.norm()`` returns the :math:`L_N` norm defined as :math:`\left(\sum_i |v(i)|^N\right)^{1/N}`. N can take any positive integer value. There are also some particular values for the most commonly used norms, ``L_1`` for the Manhattan norm, ``L_2`` for the geometrical norm and ``L_inf`` for the norm infinity. - ``v.dot(x)`` return the dot product of ``v`` and ``x`` - ``v.distance(x)`` return the geometrical norm of :math:`v - x` - Level 2: (results are vectors) - ``v += s``, ``v -= s``, ``v *= s``, ``v /= s`` those are element-wise operators that sum, substract, multiply or divide all the component of ``v`` by the scalar ``s`` - ``v += x``, ``v -= x`` sums or substracts the vector ``x`` to/from ``v`` - ``v.mul(A, x, alpha)`` stores the result of :math:`\alpha \boldsymbol{A} \vec{x}` in ``v``, :math:`\alpha` is equal to 1 by default - ``v.solve(A, b)`` stores the result of the resolution of the system :math:`\boldsymbol{A} \vec{x} = \vec{b}` in ``v`` - ``v.crossProduct(v1, v2)`` computes the cross product of ``v1`` and ``v2`` and stores the result in ``v`` ``Matrix`` ''''''''''''' - Accessors: - ``A(i, j)`` gives the component :math:`A_{ij}` of the matrix ``A`` - ``A(i)`` gives the :math:`i^{th}` column of the matrix as a ``Vector`` - ``A[k]`` gives the :math:`k^{th}` component of the matrix, matrices are stored in a column major way, which means that to access :math:`A_{ij}`, :math:`k = i + j M` - ``A.rows()`` gives the number of rows of ``A`` (:math:`M`) - ``A.cols()`` gives the number of columns of ``A`` (:math:`N`) - ``A.size()`` gives the number of component in the matrix (:math:`M \times N`) - Level 1: (results are scalars) - ``A.norm()`` is equivalent to ``A.norm()`` - ``A.norm()`` returns the :math:`L_N` norm defined as :math:`\left(\sum_i\sum_j |A(i,j)|^N\right)^{1/N}`. N can take any positive integer value. There are also some particular values for the most commonly used norms, ``L_1`` for the Manhattan norm, ``L_2`` for the geometrical norm and ``L_inf`` for the norm infinity. - ``A.trace()`` return the trace of ``A`` - ``A.det()`` return the determinant of ``A`` - ``A.doubleDot(B)`` return the double dot product of ``A`` and ``B``, :math:`\mat{A}:\mat{B}` - Level 3: (results are matrices) - ``A.eye(s)``, ``Matrix::eye(s)`` fills/creates a matrix with the :math:`s\mat{I}` with :math:`\mat{I}` the identity matrix - ``A.inverse(B)`` stores :math:`\mat{B}^{-1}` in ``A`` - ``A.transpose()`` returns :math:`\mat{A}^{t}` - ``A.outerProduct(v1, v2)`` stores :math:`\vec{v_1} \vec{v_2}^{t}` in ``A`` - ``C.mul(A, B, alpha)``: stores the result of the product of ``A`` and code{B} time the scalar ``alpha`` in ``C``. ``t_A`` and ``t_B`` are boolean defining if ``A`` and ``B`` should be transposed or not. +----------+----------+--------------+ |``t_A`` |``t_B`` |result | | | | | +----------+----------+--------------+ |false |false |:math:`\mat{C}| | | |= \alpha | | | |\mat{A} | | | |\mat{B}` | | | | | +----------+----------+--------------+ |false |true |:math:`\mat{C}| | | |= \alpha | | | |\mat{A} | | | |\mat{B}^t` | | | | | +----------+----------+--------------+ |true |false |:math:`\mat{C}| | | |= \alpha | | | |\mat{A}^t | | | |\mat{B}` | | | | | +----------+----------+--------------+ |true |true |:math:`\mat{C}| | | |= \alpha | | | |\mat{A}^t | | | |\mat{B}^t` | +----------+----------+--------------+ - ``A.eigs(d, V)`` this method computes the eigenvalues and eigenvectors of ``A`` and store the results in ``d`` and ``V`` such that :math:`d(i) = \lambda_i` and :math:`V(i) = \vec{v_i}` with :math:`\mat{A}\vec{v_i} = \lambda_i\vec{v_i}` and :math:`\lambda_1 > ... > \lambda_i > ... > \lambda_N`