From a02ca09a9d7123a625b77b22d16b173fe5730652 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Klinkovsk=C3=BD?= Date: Mon, 14 Dec 2020 13:29:14 +0100 Subject: [PATCH 1/4] Removed obsolete scripts tnl-bindir and tnl-compile and update quickstart's Makefile - The concept of tnl-bindir is completely useless - it was intended for checking if the user configured their $PATH, but the user had to already configure $PATH in order to use the script. - The tnl-compile script was used in the quickstart-generated Makefile, but gave obsolete output. Moreover, the script approach is inflexible and does not provide any benefits compared to hard-coding flags directly in the Makefile. --- src/Tools/CMakeLists.txt | 12 +- src/Tools/tnl-bindir.in | 3 - src/Tools/tnl-compile.in | 16 --- src/Tools/tnl-err2eoc | 0 src/Tools/tnl-quickstart/CMakeLists.txt | 6 +- src/Tools/tnl-quickstart/Makefile | 30 +++++ src/Tools/tnl-quickstart/Makefile.in | 37 ------ src/Tools/tnl-quickstart/config.mk | 49 ++++++++ src/Tools/tnl-quickstart/tnl-quickstart | 137 ++++++++++++++++++--- src/Tools/tnl-quickstart/tnl-quickstart.py | 118 ------------------ 10 files changed, 206 insertions(+), 202 deletions(-) delete mode 100644 src/Tools/tnl-bindir.in delete mode 100644 src/Tools/tnl-compile.in mode change 100644 => 100755 src/Tools/tnl-err2eoc create mode 100644 src/Tools/tnl-quickstart/Makefile delete mode 100644 src/Tools/tnl-quickstart/Makefile.in create mode 100644 src/Tools/tnl-quickstart/config.mk mode change 100644 => 100755 src/Tools/tnl-quickstart/tnl-quickstart delete mode 100644 src/Tools/tnl-quickstart/tnl-quickstart.py diff --git a/src/Tools/CMakeLists.txt b/src/Tools/CMakeLists.txt index 802d67b45..66eb6ce76 100644 --- a/src/Tools/CMakeLists.txt +++ b/src/Tools/CMakeLists.txt @@ -1,7 +1,4 @@ -add_subdirectory (tnl-quickstart) - -CONFIGURE_FILE( "tnl-compile.in" "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/tnl-compile" @ONLY ) -CONFIGURE_FILE( "tnl-bindir.in" "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/tnl-bindir" @ONLY ) +add_subdirectory(tnl-quickstart) ADD_EXECUTABLE(tnl-grid-setup tnl-grid-setup.cpp ) ADD_EXECUTABLE(tnl-grid-to-mesh tnl-grid-to-mesh.cpp ) @@ -84,9 +81,6 @@ INSTALL( TARGETS tnl-init tnl-lattice-init DESTINATION bin ) -INSTALL( FILES ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/tnl-bindir - ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/tnl-compile - tnl-err2eoc +INSTALL( FILES tnl-err2eoc tnl-log-to-html.py - DESTINATION bin - PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE ) + DESTINATION bin ) diff --git a/src/Tools/tnl-bindir.in b/src/Tools/tnl-bindir.in deleted file mode 100644 index 2ce673808..000000000 --- a/src/Tools/tnl-bindir.in +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env bash - -echo @CMAKE_INSTALL_PREFIX@/bin \ No newline at end of file diff --git a/src/Tools/tnl-compile.in b/src/Tools/tnl-compile.in deleted file mode 100644 index b106c613c..000000000 --- a/src/Tools/tnl-compile.in +++ /dev/null @@ -1,16 +0,0 @@ -#!/usr/bin/env bash - -DEBUG_FLAGS="-DNDEBUG" # -march=native" -CUDA_FLAGS="" -CXX_STD_FLAGS="-std=c++11" - -for option in "$@" -do - case $option in - --cuda ) CUDA_FLAGS="-DHAVE_CUDA `tnl-cuda-arch`" ;; - --debug ) DEBUG_FLAGS="-g -O0" - esac -done - -echo -I@CMAKE_INSTALL_PREFIX@/include ${CUDA_FLAGS} ${CXX_STD_FLAGS} ${DEBUG_FLAGS} - diff --git a/src/Tools/tnl-err2eoc b/src/Tools/tnl-err2eoc old mode 100644 new mode 100755 diff --git a/src/Tools/tnl-quickstart/CMakeLists.txt b/src/Tools/tnl-quickstart/CMakeLists.txt index 02d7425d2..accfcd88e 100644 --- a/src/Tools/tnl-quickstart/CMakeLists.txt +++ b/src/Tools/tnl-quickstart/CMakeLists.txt @@ -1,10 +1,10 @@ INSTALL( FILES tnl-quickstart - tnl-quickstart.py DESTINATION bin PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE ) INSTALL( FILES build-config-tag.h.in - Makefile.in + Makefile + config.mk explicit-laplace-grid-1d_impl.h.in explicit-laplace-grid-2d_impl.h.in explicit-laplace-grid-3d_impl.h.in @@ -23,4 +23,4 @@ INSTALL( FILES build-config-tag.h.in rhs.h.in run-script.in DESTINATION ${TNL_TARGET_DATA_DIRECTORY} - PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ ) \ No newline at end of file + PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ ) diff --git a/src/Tools/tnl-quickstart/Makefile b/src/Tools/tnl-quickstart/Makefile new file mode 100644 index 000000000..1736cd877 --- /dev/null +++ b/src/Tools/tnl-quickstart/Makefile @@ -0,0 +1,30 @@ +include config.mk + +SOURCES := $(wildcard *.cpp) +TARGETS := $(SOURCES:%.cpp=%) +CUDA_SOURCES := $(wildcard *.cu) +CUDA_TARGETS := $(CUDA_SOURCES:%.cu=%) + +## targets definitions follow +.PHONY: all host cuda +all: host cuda +host: $(TARGETS) +cuda: $(CUDA_TARGETS) + +.PHONY: clean +clean: + rm -f *.d *.o *.cuo $(TARGETS) $(CUDA_TARGETS) + +$(TARGETS): % : %.o + $(CXX) $(LDFLAGS) -o $@ $< $(LDLIBS) + +# use .cuo instead of .cu.o to avoid problems with the implicit rules: https://stackoverflow.com/q/62967939 +# (and use the host compiler for linking CUDA, nvcc does not understand that .cuo is an object file) +$(CUDA_TARGETS): % : %.cuo + $(CXX) $(CUDA_LDFLAGS) -o $@ $< $(CUDA_LDLIBS) + +$(SOURCES:%.cpp=%.o): %.o: %.cpp + $(CXX) $(CPPFLAGS) $(CXXFLAGS) -c -o $@ $< + +$(CUDA_SOURCES:%.cu=%.cuo): %.cuo : %.cu + $(CUDA_CXX) $(CUDA_CPPFLAGS) $(CUDA_CXXFLAGS) -c -o $@ $< diff --git a/src/Tools/tnl-quickstart/Makefile.in b/src/Tools/tnl-quickstart/Makefile.in deleted file mode 100644 index cc9e46b4b..000000000 --- a/src/Tools/tnl-quickstart/Makefile.in +++ /dev/null @@ -1,37 +0,0 @@ -TARGET = {problemBaseName} -INSTALL_DIR = ${{HOME}}/local - -ifdef WITH_CUDA - CXX = nvcc - CXX_FLAGS = $(shell tnl-compile --cuda) -else - CXX = g++ - CXX_FLAGS = $(shell tnl-compile) -endif - -SOURCES = {problemBaseName}.cpp -HEADERS = {problemBaseName}.h -DIST = $(SOURCES) $(CUDA_SOURCES) $(HEADERS) Makefile - -ifdef WITH_CUDA - OBJECTS = {problemBaseName}-cuda.o -else - OBJECTS = {problemBaseName}.o -endif - -all: $(TARGET) - -clean: - rm -f *.o - -dist: $(DIST) - tar zcvf $(TARGET).tgz $(DIST) - -$(TARGET): $(OBJECTS) - $(CXX) -o $@ $< $(LDFLAGS) - -%.o: %.cpp - $(CXX) $(CPPFLAGS) $(CXX_FLAGS) -c -o $@ $< - -%.o: %.cu - $(CXX) $(CPPFLAGS) $(CXX_FLAGS) -c -o $@ $< diff --git a/src/Tools/tnl-quickstart/config.mk b/src/Tools/tnl-quickstart/config.mk new file mode 100644 index 000000000..5b2f0d7f6 --- /dev/null +++ b/src/Tools/tnl-quickstart/config.mk @@ -0,0 +1,49 @@ +# configure the include path(s) according to your TNL installation +TNL_INCLUDE_DIRS := -I ~/.local/include + +WITH_OPENMP := yes +WITH_DEBUG := no + +# If TNL is installed on your system, the CUDA architecture can be detected +# automatically by tnl-cuda-arch. This is done if CUDA_ARCH is set to "auto". +# Otherwise, CUDA_ARCH has to be set manually to the desired CUDA architecture +# number, e.g. 60, 61, etc. +CUDA_ARCH := auto + +# compilers +CXX := g++ +CUDA_CXX := nvcc + +# host compiler flags +CXXFLAGS := -std=c++14 $(TNL_INCLUDE_DIRS) +ifeq ($(WITH_DEBUG),yes) + CXXFLAGS += -O0 -g +else + CXXFLAGS += -O3 -DNDEBUG +endif + +# CUDA compiler flags +CUDA_CXXFLAGS := -std=c++14 --expt-relaxed-constexpr --expt-extended-lambda $(TNL_INCLUDE_DIRS) +CUDA_CXXFLAGS += -DHAVE_CUDA +ifeq ($(CUDA_ARCH),auto) + CUDA_CXXFLAGS += $(shell tnl-cuda-arch) +else + CUDA_CXXFLAGS += -gencode arch=compute_$(CUDA_ARCH),code=sm_$(CUDA_ARCH) +endif + +# determine path to the CUDA toolkit installation +# (autodetection is attempted, set it manually if it fails) +CUDA_PATH ?= $(abspath $(dir $(shell command -v nvcc))/..) +#$(info Detected CUDA_PATH: $(CUDA_PATH)) + +# flags for linking CUDA with the host compiler +CUDA_LDFLAGS := -L $(CUDA_PATH)/lib64 +CUDA_LDLIBS := -lcudart -ldl -lrt + +# enable OpenMP +ifeq ($(WITH_OPENMP),yes) + CXXFLAGS += -fopenmp -DHAVE_OPENMP + LDLIBS += -lgomp + CUDA_CXXFLAGS += -Xcompiler -fopenmp -DHAVE_OPENMP + CUDA_LDLIBS += -lgomp +endif diff --git a/src/Tools/tnl-quickstart/tnl-quickstart b/src/Tools/tnl-quickstart/tnl-quickstart old mode 100644 new mode 100755 index eefb6910f..51a4d1418 --- a/src/Tools/tnl-quickstart/tnl-quickstart +++ b/src/Tools/tnl-quickstart/tnl-quickstart @@ -1,17 +1,122 @@ -#!/usr/bin/env bash - -PYTHON=`which python3` -TNL_BINDIR=`tnl-bindir` - -if test x${PYTHON} = x; -then - echo "It seems that Python 3 is not install on your system." - echo "You may install it as follows:" - echo "" - echo "In Ubuntu: sudo apt-get install python3" - echo "In OpenSuse:" - echo "In CentOS:" -else -${PYTHON} ${TNL_BINDIR}/tnl-quickstart.py -fi +#! /usr/bin/env python3 + +# To change this license header, choose License Headers in Project Properties. +# To change this template file, choose Tools | Templates +# and open the template in the editor. + +__author__ = "Tomas Oberhuber" +__date__ = "$May 6, 2015 8:40:59 PM$" + +import TNL + +def generateRunScript( problemBaseName ): + file = open( "run-" + problemBaseName, "w" ) + file.close() + +print( "TNL Quickstart -- solver generator") +print( "----------------------------------") + +definitions = {} + +definitions['problemName'] = input( "Problem name:" ) +definitions['problemBaseName'] = input( "Problem class base name (base name acceptable in C++ code):" ) +definitions['operatorName'] = input( "Operator name:") + +#### +# Makefile +# +with open( TNL.__install_prefix__+"/share/TNL/Makefile", 'r') as ftemp: + templateString = ftemp.read() +with open( "Makefile", 'w') as file: + file.write( templateString.format(**definitions ) ) +with open( TNL.__install_prefix__+"/share/TNL/config.mk", 'r') as ftemp: + templateString = ftemp.read() +with open( "config.mk", 'w') as file: + file.write( templateString.format(**definitions ) ) + +#### +# Main files +# +with open( TNL.__install_prefix__+"/share/TNL/main.h.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['problemBaseName']+".h", 'w') as file: + file.write( templateString.format(**definitions ) ) + +with open( TNL.__install_prefix__+"/share/TNL/main.cu.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['problemBaseName']+"-cuda.cu", 'w') as file: + file.write( templateString.format(**definitions ) ) + +with open( TNL.__install_prefix__+"/share/TNL/main.cpp.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['problemBaseName']+".cpp", 'w') as file: + file.write( templateString.format(**definitions ) ) + +#### +# Problem definition +# +with open( TNL.__install_prefix__+"/share/TNL/problem.h.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['problemBaseName'] + "Problem.h", 'w') as file: + file.write( templateString.format(**definitions ) ) + +with open( TNL.__install_prefix__+"/share/TNL/problem_impl.h.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['problemBaseName'] + "Problem_impl.h", 'w') as file: + file.write( templateString.format(**definitions ) ) + +#### +# Operator +# +dimensions = [ '1', '2', '3' ] +for meshDimension in dimensions: + definitions[ 'meshDimension' ] = meshDimension + key = 'operatorGridSpecializationHeader_' + meshDimension + 'D' + with open( TNL.__install_prefix__+"/share/TNL/operator-grid-specialization.h.in", 'r') as ftemp: + templateString = ftemp.read() + definitions[ key ] = templateString.format( **definitions ) + + with open( TNL.__install_prefix__+"/share/TNL/explicit-laplace-grid-" + meshDimension + "d_impl.h.in", 'r') as ftemp: + definitions[ 'explicitScheme' ] = ftemp.read(); + with open( TNL.__install_prefix__+"/share/TNL/implicit-laplace-grid-" + meshDimension + "d_impl.h.in", 'r') as ftemp: + definitions[ 'semiimplicitScheme' ] = ftemp.read(); + + key = 'operatorGridSpecializationImplementation_' + meshDimension + 'D' + with open( TNL.__install_prefix__+"/share/TNL/operator-grid-specialization_impl.h.in", 'r') as ftemp: + templateString = ftemp.read() + definitions[ key ] = templateString.format( **definitions ) + +with open( TNL.__install_prefix__+"/share/TNL/operator.h.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['operatorName'] + ".h", 'w') as file: + file.write( templateString.format(**definitions ) ) + +with open( TNL.__install_prefix__+"/share/TNL/operator_impl.h.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['operatorName'] + "_impl.h", 'w') as file: + file.write( templateString.format(**definitions ) ) + +#### +# Right-hand side +# +with open( TNL.__install_prefix__+"/share/TNL/rhs.h.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['problemBaseName'] + "Rhs.h", 'w') as file: + file.write( templateString.format(**definitions ) ) + +#### +# Build config tag +# +with open( TNL.__install_prefix__+"/share/TNL/build-config-tag.h.in", 'r') as ftemp: + templateString = ftemp.read() +with open( definitions['problemBaseName'] + "BuildConfigTag.h", 'w') as file: + file.write( templateString.format(**definitions ) ) + +#### +# Run script +# +with open( TNL.__install_prefix__+"/share/TNL/run-script.in", 'r') as ftemp: + templateString = ftemp.read() +with open( "run-" + definitions['problemBaseName'], 'w') as file: + file.write( templateString.format(**definitions ) ) diff --git a/src/Tools/tnl-quickstart/tnl-quickstart.py b/src/Tools/tnl-quickstart/tnl-quickstart.py deleted file mode 100644 index 6fa0e8187..000000000 --- a/src/Tools/tnl-quickstart/tnl-quickstart.py +++ /dev/null @@ -1,118 +0,0 @@ -#! /usr/bin/python - -# To change this license header, choose License Headers in Project Properties. -# To change this template file, choose Tools | Templates -# and open the template in the editor. - -__author__ = "Tomas Oberhuber" -__date__ = "$May 6, 2015 8:40:59 PM$" - -import TNL - -def generateRunScript( problemBaseName ): - file = open( "run-" + problemBaseName, "w" ) - file.close() - -print( "TNL Quickstart -- solver generator") -print( "----------------------------------") - -definitions = {} - -definitions['problemName'] = input( "Problem name:" ) -definitions['problemBaseName'] = input( "Problem class base name (base name acceptable in C++ code):" ) -definitions['operatorName'] = input( "Operator name:") - -#### -# Makefile -# -with open( TNL.__install_prefix__+"/share/TNL/Makefile.in", 'r') as ftemp: - templateString = ftemp.read() -with open( "Makefile", 'w') as file: - file.write( templateString.format(**definitions ) ) - -#### -# Main files -# -with open( TNL.__install_prefix__+"/share/TNL/main.h.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['problemBaseName']+".h", 'w') as file: - file.write( templateString.format(**definitions ) ) - -with open( TNL.__install_prefix__+"/share/TNL/main.cu.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['problemBaseName']+"-cuda.cu", 'w') as file: - file.write( templateString.format(**definitions ) ) - -with open( TNL.__install_prefix__+"/share/TNL/main.cpp.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['problemBaseName']+".cpp", 'w') as file: - file.write( templateString.format(**definitions ) ) - -#### -# Problem definition -# -with open( TNL.__install_prefix__+"/share/TNL/problem.h.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['problemBaseName'] + "Problem.h", 'w') as file: - file.write( templateString.format(**definitions ) ) - -with open( TNL.__install_prefix__+"/share/TNL/problem_impl.h.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['problemBaseName'] + "Problem_impl.h", 'w') as file: - file.write( templateString.format(**definitions ) ) - -#### -# Operator -# -dimensions = [ '1', '2', '3' ] -for meshDimension in dimensions: - definitions[ 'meshDimension' ] = meshDimension - key = 'operatorGridSpecializationHeader_' + meshDimension + 'D' - with open( TNL.__install_prefix__+"/share/TNL/operator-grid-specialization.h.in", 'r') as ftemp: - templateString = ftemp.read() - definitions[ key ] = templateString.format( **definitions ) - - with open( TNL.__install_prefix__+"/share/TNL/explicit-laplace-grid-" + meshDimension + "d_impl.h.in", 'r') as ftemp: - definitions[ 'explicitScheme' ] = ftemp.read(); - with open( TNL.__install_prefix__+"/share/TNL/implicit-laplace-grid-" + meshDimension + "d_impl.h.in", 'r') as ftemp: - definitions[ 'semiimplicitScheme' ] = ftemp.read(); - - key = 'operatorGridSpecializationImplementation_' + meshDimension + 'D' - with open( TNL.__install_prefix__+"/share/TNL/operator-grid-specialization_impl.h.in", 'r') as ftemp: - templateString = ftemp.read() - definitions[ key ] = templateString.format( **definitions ) - -with open( TNL.__install_prefix__+"/share/TNL/operator.h.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['operatorName'] + ".h", 'w') as file: - file.write( templateString.format(**definitions ) ) - -with open( TNL.__install_prefix__+"/share/TNL/operator_impl.h.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['operatorName'] + "_impl.h", 'w') as file: - file.write( templateString.format(**definitions ) ) - -#### -# Right-hand side -# -with open( TNL.__install_prefix__+"/share/TNL/rhs.h.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['problemBaseName'] + "Rhs.h", 'w') as file: - file.write( templateString.format(**definitions ) ) - -#### -# Build config tag -# -with open( TNL.__install_prefix__+"/share/TNL/build-config-tag.h.in", 'r') as ftemp: - templateString = ftemp.read() -with open( definitions['problemBaseName'] + "BuildConfigTag.h", 'w') as file: - file.write( templateString.format(**definitions ) ) - -#### -# Run script -# -with open( TNL.__install_prefix__+"/share/TNL/run-script.in", 'r') as ftemp: - templateString = ftemp.read() -with open( "run-" + definitions['problemBaseName'], 'w') as file: - file.write( templateString.format(**definitions ) ) - -- GitLab From 3d7de70d737a53a0d9aeca7a5531adefe3ddeb8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Klinkovsk=C3=BD?= Date: Mon, 14 Dec 2020 14:20:29 +0100 Subject: [PATCH 2/4] Reorganized README.md and the documentation front page - README is shorter, includes only an introduction and links to the full documentation for details - New documented topics: optional dependencies, compiler flags, environment variables --- Documentation/Pages/main-page.md | 208 ++++++++++++++++++++++------ README.md | 84 ++++------- src/TNL/Meshes/Readers/MeshReader.h | 1 + src/TNL/Meshes/Writers/VTKWriter.h | 1 + 4 files changed, 195 insertions(+), 99 deletions(-) diff --git a/Documentation/Pages/main-page.md b/Documentation/Pages/main-page.md index 4780f7685..db9aceccb 100644 --- a/Documentation/Pages/main-page.md +++ b/Documentation/Pages/main-page.md @@ -46,14 +46,35 @@ several modules: TNL provides a framework for the development of ODE or PDE solvers. - \ref TNL::Images "Image processing". TNL provides structures for the representation of image data. Imports and - exports from several file formats are provided using external libraries, such - as [DCMTK](http://dicom.offis.de/dcmtk.php.en) for DICOM files, - [libpng](http://www.libpng.org/pub/png/libpng.html) for PNG files, or - [libjpeg](http://libjpeg.sourceforge.net/) for JPEG files. + exports from several file formats such as DICOM, PNG, and JPEG are provided + using external libraries (see below). See also \ref comparison_with_other_libraries "Comparison with other libraries". -## Installation +TNL also provides several optional components: + + +- TNL header files in the + [src/TNL](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/TNL) + directory. +- Various pre-processing and post-processing tools in the + [src/Tools](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Tools) + directory. +- Python bindings and scripts in the + [src/Python](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Python) + directory. +- Examples of various numerical solvers in the + [src/Examples](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Examples) + directory. +- Benchmarks in the + [src/Benchmarks](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Benchmarks) + directory. + +These components can be individually enabled or disabled and installed by a +convenient `install` script. See the [Installation](#installation) section for +details. + +## Installation You can either download the [stable version](http://tnl-project.org/download/) or directly clone the git repository via HTTPS: @@ -65,21 +86,82 @@ or via SSH: git clone gitlab@mmg-gitlab.fjfi.cvut.cz:tnl/tnl-dev.git Since TNL is a header-only library, no installation is necessary to actually use -the library. You can just extract the [src/TNL]( -https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/TNL) -subdirectory, for example into `~/.local/include/`, and configure your compiler -to include headers from this path. - -Optionally, you may want to compile and install various [tools and examples]( -#optional-components). - -### Supported compilers - -You need a compiler which supports the [C++14]( -https://en.wikipedia.org/wiki/C%2B%2B14) standard, for example [GCC]( -https://gcc.gnu.org/) 5.0 or later or [Clang](http://clang.llvm.org/) 3.4 or -later. For CUDA support, you also need [CUDA]( -https://docs.nvidia.com/cuda/index.html) 9.0 or later. +the library in your project. See the [Usage](#usage) section for details. + +You may also want to install some optional dependencies and/or compile and +install various tools and examples. See the following section for details. + +### Dependencies + +In order to use TNL, you need to install a compatible compiler, a parallel +computing platform, and (optionally) some libraries. + +- __Supported compilers:__ + You need a compiler which supports the [C++14]( + https://en.wikipedia.org/wiki/C%2B%2B14) standard, for example [GCC]( + https://gcc.gnu.org/) 5.0 or later or [Clang](http://clang.llvm.org/) 3.4 or + later. + +- __Parallel computing platforms:__ + TNL can be used with one or more of the following platforms: + - [OpenMP](https://en.wikipedia.org/wiki/OpenMP) -- for computations on + shared-memory multiprocessor platforms. + - [CUDA](https://docs.nvidia.com/cuda/index.html) 9.0 or later -- for + computations on Nvidia GPUs. + - [MPI](https://en.wikipedia.org/wiki/Message_Passing_Interface) -- TNL can + use an MPI library such as [OpenMPI](https://www.open-mpi.org/) for + distributed computing. For distributed CUDA computations, the library must + be [CUDA-aware]( + https://developer.nvidia.com/blog/introduction-cuda-aware-mpi/). + +- __Libraries:__ + Various libraries are needed to enable optional features or enhance the + functionality of some TNL components. Make sure that all relevant packages are + installed and use the appropriate flags when compiling your project. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryAffected componentsCompiler flagsNotes
[zlib](http://zlib.net/) \ref TNL::Meshes::Readers "XML-based mesh readers" and \ref TNL::Meshes::Writers "writers" `-DHAVE_ZLIB -lz`
[TinyXML2](https://github.com/leethomason/tinyxml2/) \ref TNL::Meshes::Readers "XML-based mesh readers" `-DHAVE_TINYXML2 -ltinyxml2` If TinyXML2 is not found as a system library, the `install` script + will download, compile and install TinyXML2 along with TNL.
[Metis](http://glaros.dtc.umn.edu/gkhome/metis/metis/overview) `tnl-decompose-mesh` Only used for the compilation of the `tnl-decompose-mesh` tool.
[libpng](http://www.libpng.org/pub/png/libpng.html) \ref TNL::Images "Image processing" classes `-DHAVE_PNG_H -lpng`
[libjpeg](http://libjpeg.sourceforge.net/) \ref TNL::Images "Image processing" classes `-DHAVE_JPEG_H -ljpeg`
[DCMTK](http://dicom.offis.de/dcmtk.php.en) \ref TNL::Images "Image processing" classes `-DHAVE_DCMTK_H -ldcm...`
+ +- __Other language toolchains/interpreters:__ + - Python – install an interpreter for using the Python scripts from TNL and + the corresponding development package (depending on your operating system) + for building the Python bindings. ### Optional components @@ -89,29 +171,73 @@ post-processing tools which can be compiled and installed by executing the ./install -[CMake](https://cmake.org/) 3.12.2 or later is required for the compilation. The -script compiles and/or installs the following components into the `~/.local/` -directory: +[CMake](https://cmake.org/) 3.13 or later is required for the compilation. -- TNL header files from the - [src/TNL](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/TNL) - directory. -- Various pre-processing and post-processing tools from the - [src/Tools](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Tools) - directory. -- Python bindings and scripts from the - [src/Python](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Python) - directory. -- Examples of various numerical solvers from the - [src/Examples](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Examples) - directory. -- Benchmarks from the - [src/Benchmarks](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Benchmarks) - directory. -- Compiles and executes the unit tests from the - [src/UnitTests](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/UnitTests) - directory. +The script compiles and/or installs all [optional components](#optional-components) +into the `~/.local/` directory, and compiles and executes all unit tests from +the [src/UnitTests]( +https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/UnitTests) +directory. Individual components can be disabled and the installation prefix can be changed by passing command-line arguments to the install script. Run `./install --help` for details. + +## Usage + +TNL can be used with various build systems if you configure the compiler flags +as explained below. See also an [example project]( +https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/example-project) providing a simple +`Makefile`. + +### C++ compiler flags + +- Enable the C++14 standard: `-std=c++14` +- Configure the include path: `-I /path/to/include` + - If you installed TNL with the install script, the include path is + `/include`, where `` is the installation path (it is + `~/.local` by default). + - If you want to include from the git repository directly, you need to + specify two include paths: `/src` and `` is the path where you have cloned the TNL git + repository. + - Instead of using the `-I` flag, you can set the `CPATH` environment + variable to a colon-delimited list of include paths. Note that this may + affect the build systems of other projects as well. For example: + + export CPATH="$HOME/.local/include:$CPATH" + +- Enable optimizations: `-O3 -DNDEBUG` (you can also add + `-march=native -mtune=native` to enable CPU-specific optimizations). +- Of course, there are many other useful compiler flags. See, for example, our + [CMakeLists.txt](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/-/blob/develop/CMakeLists.txt) + file for flags that we use when developing TNL (there are flags for e.g. + hiding some useless compiler warnings). + +### Compiler flags for parallel computing + +To enable parallel computing platforms in TNL, additional compiler flags are +needed. They can be enabled by defining a corresponding C preprocessor macro +which has the form `HAVE_`, i.e.: + +- `-D HAVE_OPENMP` enables OpenMP (also `-fopenmp` is usually needed to enable + OpenMP support in the compiler) +- `-D HAVE_CUDA` enables CUDA (the compiler must actually support CUDA, use e.g. + `nvcc` or `clang++`) + - For `nvcc`, the following experimental flags are also required: + `--expt-relaxed-constexpr --expt-extended-lambda` +- `-D HAVE_MPI` enables MPI (use a compiler wrapper such as `mpicxx` or link + manually against the MPI libraries) + +### Environment variables + +If you installed some TNL tools or examples using the `install` script, we +recommend you to configure several environment variables for convenience. If you +used the default installation path `~/.local/`: + +- `export PATH=$PATH:$HOME/.local/bin` +- If TinyXML2 was installed by the `install` script and not as a system package, + also `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/.local/lib` + +These commands can be added to the initialization scripts of your favourite +shell, e.g. `.bash_profile`. diff --git a/README.md b/README.md index 3845e4332..ab954f3fa 100644 --- a/README.md +++ b/README.md @@ -41,10 +41,11 @@ several modules: TNL provides a framework for the development of ODE or PDE solvers. - _[Image processing][image processing]_. TNL provides structures for the representation of image data. Imports and - exports from several file formats are provided using external libraries, such - as [DCMTK](http://dicom.offis.de/dcmtk.php.en) for DICOM files, - [libpng](http://www.libpng.org/pub/png/libpng.html) for PNG files, or - [libjpeg](http://libjpeg.sourceforge.net/) for JPEG files. + exports from several file formats such as DICOM, PNG, and JPEG are provided + using external libraries (see below). + +See also [Comparison with other libraries]( +https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/comparison_with_other_libraries.html). [allocators]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/namespaceTNL_1_1Allocators.html [devices]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/namespaceTNL_1_1Devices.html @@ -57,77 +58,44 @@ several modules: [meshes]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/namespaceTNL_1_1Meshes.html [image processing]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/namespaceTNL_1_1Images.html -For more information, see the [full documentation][full documentation]. - -## Installation - -You can either download the [stable version](http://tnl-project.org/download/) -or directly clone the git repository via HTTPS: - - git clone https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev.git - -or via SSH: - - git clone gitlab@mmg-gitlab.fjfi.cvut.cz:tnl/tnl-dev.git - -Since TNL is a header-only library, no installation is necessary to actually use -the library. You can just extract the [src/TNL]( -https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/TNL) -subdirectory, for example into `~/.local/include/`, and configure your compiler -to include headers from this path. - -Optionally, you may want to compile and install various [tools and examples]( -#optional-components). - -### Supported compilers +TNL also provides several optional components: -You need a compiler which supports the [C++14]( -https://en.wikipedia.org/wiki/C%2B%2B14) standard, for example [GCC]( -https://gcc.gnu.org/) 5.0 or later or [Clang](http://clang.llvm.org/) 3.4 or -later. For CUDA support, you also need [CUDA]( -https://docs.nvidia.com/cuda/index.html) 9.0 or later. - -### Optional components - -TNL provides several optional components such as pre-processing and -post-processing tools which can be compiled and installed by executing the -`install` script: - - ./install - -[CMake](https://cmake.org/) 3.12.2 or later is required for the compilation. The -script compiles and/or installs the following components into the `~/.local/` -directory: - -- TNL header files from the +- TNL header files in the [src/TNL](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/TNL) directory. -- Various pre-processing and post-processing tools from the +- Various pre-processing and post-processing tools in the [src/Tools](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Tools) directory. -- Python bindings and scripts from the +- Python bindings and scripts in the [src/Python](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Python) directory. -- Examples of various numerical solvers from the +- Examples of various numerical solvers in the [src/Examples](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Examples) directory. -- Benchmarks from the +- Benchmarks in the [src/Benchmarks](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/Benchmarks) directory. -- Compiles and executes the unit tests from the - [src/UnitTests](https://mmg-gitlab.fjfi.cvut.cz/gitlab/tnl/tnl-dev/tree/develop/src/UnitTests) - directory. -Individual components can be disabled and the installation prefix can be changed -by passing command-line arguments to the install script. Run `./install --help` -for details. +These components can be individually enabled or disabled and installed by a +convenient `install` script. See the [Installation][installation] section in +the documentation for details. ## Documentation -See the [full documentation][full documentation] for the API reference manual, -tutorials and other documented topics. +See the [full documentation][full documentation] for information about: + +- [installation instructions][installation], +- [usage hints][usage], +- [tutorials][tutorials], +- [API reference manual][API], + +and other documented topics. [full documentation]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/ +[installation]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/#installation +[usage]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/#usage +[tutorials]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/Tutorials.html +[API]: https://mmg-gitlab.fjfi.cvut.cz/doc/tnl/annotated.html ## Authors diff --git a/src/TNL/Meshes/Readers/MeshReader.h b/src/TNL/Meshes/Readers/MeshReader.h index 087e8c1dd..88e2986ba 100644 --- a/src/TNL/Meshes/Readers/MeshReader.h +++ b/src/TNL/Meshes/Readers/MeshReader.h @@ -21,6 +21,7 @@ namespace TNL { namespace Meshes { +//! \brief Namespace for mesh readers. namespace Readers { struct MeshReaderError diff --git a/src/TNL/Meshes/Writers/VTKWriter.h b/src/TNL/Meshes/Writers/VTKWriter.h index 8010317a3..e1c5fae97 100644 --- a/src/TNL/Meshes/Writers/VTKWriter.h +++ b/src/TNL/Meshes/Writers/VTKWriter.h @@ -16,6 +16,7 @@ namespace TNL { namespace Meshes { +//! \brief Namespace for mesh writers. namespace Writers { namespace details { -- GitLab From bca052c834ea873693a541c3d97d29d2202a1496 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Klinkovsk=C3=BD?= Date: Mon, 14 Dec 2020 14:35:23 +0100 Subject: [PATCH 3/4] Documentation: add programming principles and smart pointers to the core concepts --- Documentation/Pages/core-concepts.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/Documentation/Pages/core-concepts.md b/Documentation/Pages/core-concepts.md index 8e151191e..3770602b8 100644 --- a/Documentation/Pages/core-concepts.md +++ b/Documentation/Pages/core-concepts.md @@ -38,5 +38,23 @@ TNL is based on the following core concepts: - Views have a copy-assignment operator which does a deep copy. - Views have all other methods present in the relevant container (data structure). +7. Smart pointers + - TODO TODO: formalize the concepts involving lambda functions (e.g. in `Reduction`) + +## Programming principles + +TNL follows common programming principles and design patterns to maintain a +comprehensible and efficient code base. We highlight some principles with +respect to the support for different compute architectures: + +- CUDA kernels should not operate with needlessly extensive objects, e.g. + objects which include smart pointers, because this wastes the device + registers. +- CUDA kernels should not operate with "distributed" objects – they should + operate only with the "local parts" of the distributed objects. MPI support is + a higher layer than CUDA support and distributed objects generally contain + attributes which should not be needed by CUDA kernels. +- Smart pointers should be cached if appropriate in order to avoid repeated + memory allocations and copies. -- GitLab From 559a56aacb98b51615a57ace6852dac82aa159de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Klinkovsk=C3=BD?= Date: Mon, 14 Dec 2020 14:58:56 +0100 Subject: [PATCH 4/4] Removed tutorial 'Building applications with TNL' It is superseded by the usage hints documented on the front page and by the linked example project. --- .../Tutorials/BuildWithTNL/CMakeLists.txt | 0 Documentation/Tutorials/BuildWithTNL/Makefile | 54 --------- .../Tutorials/BuildWithTNL/Makefile.inc | 48 -------- .../Tutorials/BuildWithTNL/example-cuda-2.cpp | 1 - .../Tutorials/BuildWithTNL/example-cuda-2.cu | 1 - .../Tutorials/BuildWithTNL/example-cuda-2.h | 27 ----- .../Tutorials/BuildWithTNL/example-cuda.cpp | 25 ---- .../Tutorials/BuildWithTNL/example-cuda.cu | 1 - .../Tutorials/BuildWithTNL/example-host.cpp | 19 --- .../BuildWithTNL/tnl-make-example-cuda.cu | 1 - .../BuildWithTNL/tnl-make-example.cpp | 1 - ...tutorial_building_applications_with_tnl.md | 111 ------------------ Documentation/Tutorials/CMakeLists.txt | 1 - Documentation/Tutorials/index.md | 11 +- 14 files changed, 5 insertions(+), 296 deletions(-) delete mode 100644 Documentation/Tutorials/BuildWithTNL/CMakeLists.txt delete mode 100644 Documentation/Tutorials/BuildWithTNL/Makefile delete mode 100644 Documentation/Tutorials/BuildWithTNL/Makefile.inc delete mode 100644 Documentation/Tutorials/BuildWithTNL/example-cuda-2.cpp delete mode 120000 Documentation/Tutorials/BuildWithTNL/example-cuda-2.cu delete mode 100644 Documentation/Tutorials/BuildWithTNL/example-cuda-2.h delete mode 100644 Documentation/Tutorials/BuildWithTNL/example-cuda.cpp delete mode 120000 Documentation/Tutorials/BuildWithTNL/example-cuda.cu delete mode 100644 Documentation/Tutorials/BuildWithTNL/example-host.cpp delete mode 120000 Documentation/Tutorials/BuildWithTNL/tnl-make-example-cuda.cu delete mode 120000 Documentation/Tutorials/BuildWithTNL/tnl-make-example.cpp delete mode 100644 Documentation/Tutorials/BuildWithTNL/tutorial_building_applications_with_tnl.md diff --git a/Documentation/Tutorials/BuildWithTNL/CMakeLists.txt b/Documentation/Tutorials/BuildWithTNL/CMakeLists.txt deleted file mode 100644 index e69de29bb..000000000 diff --git a/Documentation/Tutorials/BuildWithTNL/Makefile b/Documentation/Tutorials/BuildWithTNL/Makefile deleted file mode 100644 index 50f3297be..000000000 --- a/Documentation/Tutorials/BuildWithTNL/Makefile +++ /dev/null @@ -1,54 +0,0 @@ -include Makefile.inc - -SUBDIRS = -HEADERS = -SOURCES = tnl-make-example.cpp -CUDA_SOURCES = tnl-make-example-cuda.cu -TARGETS = tnl-make-example -CUDA_TARGETS = tnl-make-example-cuda - -FILES = Makefile \ - Makefile.inc \ - $(CUDA_SOURCES) \ - $(SOURCES) \ - $(HEADERS) - -SUBDIRSCLEAN=$(addsuffix clean,$(SUBDIRS)) - -all: bin subdirs $(TARGETS) $(CUDA_TARGETS) - -.PHONY: subdirs $(SUBDIRS) -subdirs: $(SUBDIRS) -$(SUBDIRS): - $(MAKE) -C $@ - -bin: - mkdir -p bin - -install: all - mkdir -p $(INSTALL_DIR)/bin - cp bin/* $(INSTALL_DIR)/bin - -.PHONY: clean -clean: $(SUBDIRSCLEAN) clean_curdir - -clean_curdir: - rm -f *.o - -%clean: % - $(MAKE) -C $< clean - -dist: clean - tar zcvf $(PROJECT_NAME)-src.tgz $(SUBDIRS) $(FILES) - -$(TARGETS): % : %.o - $(CXX) $(LDFLAGS) -o $@ $< $(LDLIBS) - -$(CUDA_TARGETS): % : %.cu.o - $(CUDA_CXX) $(CUDA_LDFLAGS) -o $@ $< $(CUDA_LDLIBS) - -$(SOURCES:%.cpp=%.o): %.o: %.cpp - $(CXX) $(CPPFLAGS) $(CXXFLAGS) -c -o $@ $< - -$(CUDA_SOURCES:%.cu=%.cu.o): %.cu.o : %.cu - $(CUDA_CXX) $(CUDA_CPPFLAGS) $(CUDA_CXXFLAGS) -c -o $@ $< \ No newline at end of file diff --git a/Documentation/Tutorials/BuildWithTNL/Makefile.inc b/Documentation/Tutorials/BuildWithTNL/Makefile.inc deleted file mode 100644 index 2d05fcdee..000000000 --- a/Documentation/Tutorials/BuildWithTNL/Makefile.inc +++ /dev/null @@ -1,48 +0,0 @@ -# Replace the following with your project name -PROJECT_NAME = tnl-make-example - -# Replace the following with your TNL installation path -TNL_HEADERS = ${HOME}/.local/include -INSTALL_DIR = ${HOME}/.local -WITH_CUDA = yes -WITH_OPENMP = yes -WITH_DEBUG = no - -# If TNL is installed on your system, CUDA arch can be detected automatically using -# a tool 'tnl-cuda-arch'. This is done by default if CUDA_ARCH is set to 'auto'. -# Otherwise, if you set it manually by telling the CUDA architecture number -# i.e 50, 60 etc. -CUDA_ARCH = auto - -# Set-up compilers -CXX = g++ -CUDA_CXX = nvcc - -# Set-up CXX_FLAGS -CXXFLAGS = -pthread -Wall -Wno-unused-local-typedefs -Wno-unused-variable -Wno-unknown-pragmas -std=c++14 -I$(TNL_HEADERS) -ifeq ( $(WITH_DEBUG), yes ) - CXXFLAGS += -O0 -g -else - CXXFLAGS += -DNDEBUG -O3 -funroll-loops -endif - -# Set-up CUDA_CXXFLAGS -CUDA_CXXFLAGS = -Wno-deprecated-gpu-targets --expt-relaxed-constexpr --expt-extended-lambda -Xcudafe --std c++14 -I$(TNL_HEADERS) -ifeq ( $(WITH_CUDA), yes ) - CUDA_CXXFLAGS += -DHAVE_CUDA - ifeq ( $(CUDA_ARCH), auto ) - CUDA_CXXFLAGS += `tnl-cuda-arch` - else - CUDA_CXXFLAGS += -gencode arch=compute_$(CUDA_ARCH),code=sm_$(CUDA_ARCH) - endif -endif - -# Set-up CPPFLAGS -CPPFLAGS = -MD -MP - -# Set-up LDFLAGS -LDFLAGS += -lm -ifeq ( $(WITH_OPENMP), yes ) - LDFLAGS += -lgomp -endif - diff --git a/Documentation/Tutorials/BuildWithTNL/example-cuda-2.cpp b/Documentation/Tutorials/BuildWithTNL/example-cuda-2.cpp deleted file mode 100644 index 7ea4ace2a..000000000 --- a/Documentation/Tutorials/BuildWithTNL/example-cuda-2.cpp +++ /dev/null @@ -1 +0,0 @@ -#include "example-cuda-2.h" \ No newline at end of file diff --git a/Documentation/Tutorials/BuildWithTNL/example-cuda-2.cu b/Documentation/Tutorials/BuildWithTNL/example-cuda-2.cu deleted file mode 120000 index 13435476b..000000000 --- a/Documentation/Tutorials/BuildWithTNL/example-cuda-2.cu +++ /dev/null @@ -1 +0,0 @@ -example-cuda-2.cpp \ No newline at end of file diff --git a/Documentation/Tutorials/BuildWithTNL/example-cuda-2.h b/Documentation/Tutorials/BuildWithTNL/example-cuda-2.h deleted file mode 100644 index 1d5606c78..000000000 --- a/Documentation/Tutorials/BuildWithTNL/example-cuda-2.h +++ /dev/null @@ -1,27 +0,0 @@ -#include -#include -#include -#include - -using namespace TNL; -using namespace TNL::Containers; - -int main( int argc, char* argv[] ) -{ - /**** - * Create an array on the host and print it on a console. - */ - Array< int > host_array{ 1, 2, 3 }; - std::cout << "host_array = " << host_array << std::endl; - - /**** - * Create another array on GPU and print it on a console as well. - */ -#ifdef HAVE_CUDA - Array< int, Devices::Cuda > device_array{ 4, 5, 6 }; - std::cout << "device_array = " << device_array << std::endl; -#endif - return EXIT_SUCCESS; -} - - diff --git a/Documentation/Tutorials/BuildWithTNL/example-cuda.cpp b/Documentation/Tutorials/BuildWithTNL/example-cuda.cpp deleted file mode 100644 index 83ac8ca6c..000000000 --- a/Documentation/Tutorials/BuildWithTNL/example-cuda.cpp +++ /dev/null @@ -1,25 +0,0 @@ -#include -#include -#include -#include - -using namespace TNL; -using namespace TNL::Containers; - -int main( int argc, char* argv[] ) -{ - /**** - * Create an array on the host and print it on a console. - */ - Array< int > host_array{ 1, 2, 3 }; - std::cout << "host_array = " << host_array << std::endl; - - /**** - * Create another array on GPU and print it on a console as well. - */ - Array< int, Devices::Cuda > device_array{ 4, 5, 6 }; - std::cout << "device_array = " << device_array << std::endl; - return EXIT_SUCCESS; -} - - diff --git a/Documentation/Tutorials/BuildWithTNL/example-cuda.cu b/Documentation/Tutorials/BuildWithTNL/example-cuda.cu deleted file mode 120000 index 24b9f5933..000000000 --- a/Documentation/Tutorials/BuildWithTNL/example-cuda.cu +++ /dev/null @@ -1 +0,0 @@ -example-cuda.cpp \ No newline at end of file diff --git a/Documentation/Tutorials/BuildWithTNL/example-host.cpp b/Documentation/Tutorials/BuildWithTNL/example-host.cpp deleted file mode 100644 index 1d5d356fd..000000000 --- a/Documentation/Tutorials/BuildWithTNL/example-host.cpp +++ /dev/null @@ -1,19 +0,0 @@ -#include -#include -#include - -using namespace TNL; -using namespace TNL::Containers; - -int main( int argc, char* argv[] ) -{ - /**** - * Create an array on the host and print it on a console. - */ - Array< int > host_array{ 1, 2, 3 }; - std::cout << "host_array = " << host_array << std::endl; - - return EXIT_SUCCESS; -} - - diff --git a/Documentation/Tutorials/BuildWithTNL/tnl-make-example-cuda.cu b/Documentation/Tutorials/BuildWithTNL/tnl-make-example-cuda.cu deleted file mode 120000 index 13435476b..000000000 --- a/Documentation/Tutorials/BuildWithTNL/tnl-make-example-cuda.cu +++ /dev/null @@ -1 +0,0 @@ -example-cuda-2.cpp \ No newline at end of file diff --git a/Documentation/Tutorials/BuildWithTNL/tnl-make-example.cpp b/Documentation/Tutorials/BuildWithTNL/tnl-make-example.cpp deleted file mode 120000 index 13435476b..000000000 --- a/Documentation/Tutorials/BuildWithTNL/tnl-make-example.cpp +++ /dev/null @@ -1 +0,0 @@ -example-cuda-2.cpp \ No newline at end of file diff --git a/Documentation/Tutorials/BuildWithTNL/tutorial_building_applications_with_tnl.md b/Documentation/Tutorials/BuildWithTNL/tutorial_building_applications_with_tnl.md deleted file mode 100644 index ad123b699..000000000 --- a/Documentation/Tutorials/BuildWithTNL/tutorial_building_applications_with_tnl.md +++ /dev/null @@ -1,111 +0,0 @@ -\page tutorial_building_applications_with_tnl Building Applications with TNL - -## Introduction - -One may find usefull to read this tutorial before any other to learn how to compile the examples. Here we explain how to build applications with TNL and we provide templates of Makefiles which can help the user when starting developing programs with TNL. Since TNL is header-only library no linker setup is required. - -## Table of Contents -1. [Compilation using command-line](#command_line) - 1. [Compilation with `g++`](#command_line_gcc) - 2. [Compilation with `nvcc` for CUDA](#command_line_nvcc) -2. [Build with Makefile](#makefile) -3. [Build with Cmake](#cmake) - -## Compilation using command-line - -This section mainly explains how to compile with and without support of CUDA using different compilers. We start with the following simple example: - -\include example-host.cpp - -This short program just create new array, initiate it with values 1, 2 and 3 and print it on a console. - -### Compilation with `g++` - -We assume that the code above is saved in a file `example-host.cpp.` With GNU g++compiler, the program can be compiled as follows: - -``` -g++ -std=c++14 -I${HOME}/.local/include/tnl example-host.cpp -o example-host -``` - -TNL requires standard C++14 which we enforce with the first parameter `-std=c++14`. Next, we need to tell the compiler the folder with TNL headers. This is done with the flag `-I`. By default, TNL installs into `${HOME}/.local/include/tnl`. You may also replace it just with the path where you have downloaded TNL. TNL is header only library and so it does not require any instalation. Finaly, we just past the source code file `example-host.cpp` using the command-line parameter `-c`. - -**For the best performance we recommend to add parameters `-DNDEBUG -O3 -funroll-loops`. The source code of TNL contains a lot of assertions which significantly decrease the performance. The parameter `-DNDEBUG` deactivates them.** - -### Compilation with `nvcc` for CUDA - -If you want to profit from the great performance of GPUs using CUDA you need to have the CUDA compiler `nvcc`. It can be obtained with the [CUDA toolkit](https://developer.nvidia.com/cuda-downloads). We first modify our program as follows: - -\include example-cuda.cpp - -We need to include the header `TNL/Devices/Cuda.h` and declare the new `device_array` using a template parameter `Devices::Cuda`. For more details see [the arrays tutorial](tutorial_01_arrays.html). To compile the code above invoke the following command: - -``` -nvcc -I${HOME}/.local/include/tnl example-cuda.cu -o example-cuda -``` - -After executing the binary `example-cuda` we get error message surprisingly: - -``` -host_array = [ 1, 2, 3 ] -terminate called after throwing an instance of 'TNL::Exceptions::CudaSupportMissing' - what(): CUDA support is missing, but the program called a function which needs it. Please recompile the program with CUDA support. -Aborted (core dumped) -``` - -The reason is that each piece of CUDA code in TNL is guarded by a macro `HAVE_CUDA`. Therefore we need to pass `-DHAVE_CUDA` to the compiler. The following command will make it: - -``` -nvcc -DHAVE_CUDA -I${HOME}/.local/include/tnl example-cuda.cu -o example-cuda -``` - -Unfortunately, `nvcc` compiler generates a lot of warnings. When used with TNL, the amount of code processed by `nvcc` is rather large and so you can get really a lot of warnings. Some of them are treated as errors by default. For this reason we recommend to add the following flags to `nvcc`: - -``` --Wno-deprecated-gpu-targets --expt-relaxed-constexpr --expt-extended-lambda -``` - -The overall command looks as: - -``` -nvcc -Wno-deprecated-gpu-targets --expt-relaxed-constexpr --expt-extended-lambda -DHAVE_CUDA -I${HOME}/.local/include/tnl example-cuda.cu -o example-cuda -``` - -We sugest to guard the CUDA code by the macro HAVE_CUDA even in your projects. Our simple example then turns into the following: - -\include example-cuda-2.h - -The best way is store this code into a header file `example-cuda-2.h` for example. Include this header in files `example-cuda-2.cpp` and `example-cuda-2.cu` like this: - -\include example-cuda-2.cpp - -It allows you to compile with CUDA like this: - -``` -nvcc -Wno-deprecated-gpu-targets --expt-relaxed-constexpr --expt-extended-lambda -DHAVE_CUDA -I${HOME}/.local/include/tnl example-cuda-2.cu -o example-cuda-2 -``` - -Or may compile it withou CUDA like this: - -``` -g++ -std=c++14 -I${HOME}/.local/include/tnl example-cuda-2.cpp -o example-cuda-2 -``` - -Thus you have one code which you may easily compile with or without CUDA depending on your needs. - -## Build with Makefile - -Larger projects needs to be managed by Makefile tool. In this section we propose a Makefile template which might help you to create more complex applications with TNL. The basic setup is stored in [Makefile.inc](../../BuildWithTNL/Makefile.inc) file: - -\include Makefile.inc - -In this file, you may define a name of your project (`PROJECT_NAME`), set the path to TNL headers (`TNL_HEADERS`), set the installation directory (`INSTALL_DIR`), turn on and off support of CUDA (`WITH_CUDA`), OpenMP (`WITH_OPEMP`) or debug mode (`WITH_DEBUG`). If you compile with CUDA you may set the CUDA architecture of your system. - -The main [Makefile](../../BuildWithTNL/Makefile) looks as follows: - -\include Makefile - -If your project source codes are splitted into several subdirectories you may specify them in variable `SUBDIRS`. Next, in variables `HEADERS` and `SOURCES` you should tell all source files in the current folder. The same holds for `CUDA_SOURCES` which are all .cu files in the current folder. `TARGETS` and `CUDA_TRGETS` tell the names of binaries to be build in the current folder. - -## Build with Cmake - - diff --git a/Documentation/Tutorials/CMakeLists.txt b/Documentation/Tutorials/CMakeLists.txt index 56fbb202c..7f6aea702 100644 --- a/Documentation/Tutorials/CMakeLists.txt +++ b/Documentation/Tutorials/CMakeLists.txt @@ -1,4 +1,3 @@ -add_subdirectory( BuildWithTNL ) add_subdirectory( Arrays ) add_subdirectory( Vectors ) add_subdirectory( ReductionAndScan ) diff --git a/Documentation/Tutorials/index.md b/Documentation/Tutorials/index.md index 0dd60716f..132f30799 100644 --- a/Documentation/Tutorials/index.md +++ b/Documentation/Tutorials/index.md @@ -2,9 +2,8 @@ ## Tutorials -1. [Building applications with TNL](tutorial_building_applications_with_tnl.html) -2. [Arrays](tutorial_Arrays.html) -3. [Vectors](tutorial_Vectors.html) -4. [Flexible parallel reduction and scan](tutorial_ReductionAndScan.html) -5. [For loops](tutorial_ForLoops.html) -6. [Cross-device pointers](tutorial_Pointers.html) +1. [Arrays](tutorial_Arrays.html) +2. [Vectors](tutorial_Vectors.html) +3. [Flexible parallel reduction and scan](tutorial_ReductionAndScan.html) +4. [For loops](tutorial_ForLoops.html) +5. [Cross-device pointers](tutorial_Pointers.html) -- GitLab