From 0aea7c9fbe07ada58e10c2aa9699c20e7e45055e Mon Sep 17 00:00:00 2001 From: Daniele Tartarini Date: Sat, 8 May 2021 21:23:51 +0100 Subject: [PATCH 1/8] Added pip requirements --- doc/requirements.txt | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 doc/requirements.txt diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..6b5759b --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,37 @@ +alabaster==0.7.12 +attrs==21.2.0 +Babel==2.9.1 +breathe==4.30.0 +certifi==2020.12.5 +chardet==4.0.0 +docutils==0.16 +httplib2==0.19.1 +idna==2.10 +imagesize==1.2.0 +Jinja2==2.11.3 +markdown-it-py==1.1.0 +MarkupSafe==1.1.1 +mdit-py-plugins==0.2.8 +myst-parser==0.14.0 +packaging==20.9 +plantuml==0.3.0 +Pygments==2.9.0 +pyparsing==2.4.7 +python-json-logger==2.0.1 +pytz==2021.1 +PyYAML==5.4.1 +requests==2.25.1 +snowballstemmer==2.1.0 +Sphinx==3.5.4 +sphinx-autorun==1.1.1 +sphinx-rtd-theme==0.5.2 +sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==1.0.3 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.4 +sphynx==0.0.3 +structlog==21.1.0 +typing-extensions==3.10.0.0 +urllib3==1.26.4 From 1afc8e0e6a4067ccc3bf8e5cbc34868fa3659477 Mon Sep 17 00:00:00 2001 From: Daniele Tartarini Date: Sat, 8 May 2021 22:31:58 +0100 Subject: [PATCH 2/8] add Readme --- doc/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 doc/README.md diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..81b0137 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,16 @@ + +Create Python virtual environment and install Sphinx dependencies: + + +``` +python3.7 -m venv + +# Activate python environment + +source venv/bin/activate + +pip install sphynx + +``` + + From fc1cb0e50a4de005b97ec0a8d55fbf07b21dde2d Mon Sep 17 00:00:00 2001 From: Daniele Tartarini Date: Tue, 11 May 2021 23:01:17 +0100 Subject: [PATCH 3/8] enable markdown extension. disabled breathe for #91 --- doc/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index cb53f62..f4a3d49 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -58,8 +58,8 @@ # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ['.rst', '.md'] +#source_suffix = '.rst' # The master toctree document. master_doc = 'docs' @@ -182,6 +182,6 @@ # -- Options for breathe extension ------------------------------------------- # Set doxygen xml location(s) -breathe_projects = {"pFIRE_sources" : "../doxygen/xml/"} +# breathe_projects = {"pFIRE_sources" : "../doxygen/xml/"} -breathe_default_project = "pFIRE_sources" +# breathe_default_project = "pFIRE_sources" From 9ed14312aababdc137b53da0ac2be950983c09f0 Mon Sep 17 00:00:00 2001 From: Daniele Tartarini Date: Wed, 12 May 2021 10:34:57 +0100 Subject: [PATCH 4/8] adding docker documentation --- doc/getting_started/docker.rst | 31 +++++++++++++++++ doc/getting_started/docker_hub.md | 57 +++++++++++++++++++++++++++++++ doc/getting_started/index.rst | 3 ++ 3 files changed, 91 insertions(+) create mode 100644 doc/getting_started/docker.rst create mode 100644 doc/getting_started/docker_hub.md diff --git a/doc/getting_started/docker.rst b/doc/getting_started/docker.rst new file mode 100644 index 0000000..31008a3 --- /dev/null +++ b/doc/getting_started/docker.rst @@ -0,0 +1,31 @@ +=================================== +Using pFIRE in Docker +=================================== + +Docker is a software that creates a package (called image) containing an application, its library dependencies and a minimal execution environment (e.g. a minimal Ubuntu distribution). These images can be distributed and run by any Docker software installed on the user machine. In the following are provided the instructions to execute pFIRE on a user machine with Docker. It as been tested on *nix, OsX machines and on Windows10 throught the Windows Linux Subsystem. + + +There two ways to use pFIRE in a docker: + * download a ready made image from pfire dockerhub channel + * build the docker image from the source code + + +Download a container image ready made from Dockerhub +-------------------------------------------------------- + +On the Dockerhub portal are hosted some versions of pFIRE already packaged in a Docker image. +Follow the instructions on the web page to download and use: + + + + +Build yourself from dockerfile +--------------------------------- +If you have installed Docker with command line support you can generate the docker image from the source docker container file. +Instructions and docker files organised by destination platform are available here: + +.. _pFIRE docker container source code: https://github.com/insigneo-pfire/docker-pfire + + + + diff --git a/doc/getting_started/docker_hub.md b/doc/getting_started/docker_hub.md new file mode 100644 index 0000000..4ca9051 --- /dev/null +++ b/doc/getting_started/docker_hub.md @@ -0,0 +1,57 @@ +# pFIRE on Dockerhub # + +Docker is a software that creates a package (called image) containing an application, its library dependencies and a minimal execution environment (e.g. a minimal Ubuntu distribution). These images can be distributed and run by any Docker software installed on the user machine. +In the following are provided the instructions to execute pFIRE on a user machine with Docker. It as been tested on *nix and OsX machines and Windows10 through Windows Linux Subsystem and (Powerwshell). + + +### Installation procedure +* install Docker following instructions: +https://www.docker.com/products/docker-desktop + +* Download docker image + +```bash +docker pull insigneopfire/pfire:v0.4.0 + +# rename image +docker image tag insigneopfire/pfire:v0.4.0 pfire_image + +``` + +### Usage instruction binding a local data folder + + + +Create a folder test_docker containing the input images to be registered (fixed.png, moved.png). + +Create a textual file (pfire.cfg) containing the pFIRE execution parameters as below + +``` +fixed = fixed.png +moved = moved.png +nodespacing = 10 + +``` + +Now you can run pFire using Docker: + +```bash + + docker run -d -it --name dockerised_pfire -v "$(pwd)"/test_docker:/test_docker pfire_image + + docker exec -it -w /test_docker dockerised_pfire pfire pfire.cfg + +``` + +pFIRE should show its running output and results are available in you local test_docker folder. + +```bash +fixed.png +moved.png +pfire.cfg +map.xdmf +map.xdmf.h5 +registered.xdmf +registered.xdmf.h5 +``` + diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst index 748ecc5..b985a45 100644 --- a/doc/getting_started/index.rst +++ b/doc/getting_started/index.rst @@ -10,3 +10,6 @@ using it to register images. install cli_quickstart tutorial + docker + docker_hub + From 38669501ea35ead84d0776776f68096be609ec2f Mon Sep 17 00:00:00 2001 From: Daniele Tartarini Date: Wed, 12 May 2021 21:27:55 +0100 Subject: [PATCH 5/8] Added initial documentation generation instructions --- doc/README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 51 insertions(+), 4 deletions(-) diff --git a/doc/README.md b/doc/README.md index 81b0137..b6ef4bf 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,16 +1,63 @@ +# pFIRE documentation + +### In code documentation +This project is mainly writte in C++. In code documentation is generated using +Doxygen documentation that can be generated running: -Create Python virtual environment and install Sphinx dependencies: +``` +# In pFIRE source folder run +doxygen ``` -python3.7 -m venv -# Activate python environment +Doxygen is a tool to generate in code documentatation: [doxygen](https://www.doxygen.nl) + +### User and developer documentation + +All the remaining documentation is located in the `/doc` subfoldeer and is +written using simple text files in Markdown and Restructured text format. +[Sphinx](https://www.sphinx-doc.org/en/master/) with Readthedocs template are used +to generate documentation both in HTML and PDF format. + +Documentation here provided is automatically generated and made available at: + +Create Python virtual environment and install Sphinx dependencies: + + + +``` +# Create and Activate python environment +python -m venv venv_folder source venv/bin/activate -pip install sphynx +# Install required python software + +pip install -r requirements.txt + +# Generated html documentation +sphinx-build -b html . build + +# Generated pdf documentation +sphinx-build -b pdf . build + +# When finished deactivate the Python environment +deactivate ``` +Documentation is available in `doc/build/html` + +### Online Documentation + +pFire documentation is available at the following locations: + +(Main read the docs documentation)[https://insigneo.github.io/pFIRE/docs.html] +or + +(Insigneo pFIRE github documentation)[https://insigneo.github.io/pFIRE/docs.html#] + + + From 4c430e4f97a6a3808663217663a2583d956c2a58 Mon Sep 17 00:00:00 2001 From: Daniele Tartarini Date: Tue, 17 Aug 2021 19:21:21 +0100 Subject: [PATCH 6/8] Add more documentation --- .gitignore | 1 + doc/getting_started/docker.rst | 9 +++++++-- doc/getting_started/docker_hub.md | 5 +++-- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 0a78929..7a35dd2 100644 --- a/.gitignore +++ b/.gitignore @@ -80,3 +80,4 @@ MANIFEST *.exe *.out *.app +/.ptp-sync/ diff --git a/doc/getting_started/docker.rst b/doc/getting_started/docker.rst index 31008a3..dbb7874 100644 --- a/doc/getting_started/docker.rst +++ b/doc/getting_started/docker.rst @@ -16,7 +16,7 @@ Download a container image ready made from Dockerhub On the Dockerhub portal are hosted some versions of pFIRE already packaged in a Docker image. Follow the instructions on the web page to download and use: - +_PETSc test Build yourself from dockerfile @@ -24,7 +24,12 @@ Build yourself from dockerfile If you have installed Docker with command line support you can generate the docker image from the source docker container file. Instructions and docker files organised by destination platform are available here: -.. _pFIRE docker container source code: https://github.com/insigneo-pfire/docker-pfire +.. _PETSc: https://www.mcs.anl.gov/petsc/ + +.. `_pFIRE: docker container source code`: + https://github.com/insigneo-pfire/docker-pfire + + diff --git a/doc/getting_started/docker_hub.md b/doc/getting_started/docker_hub.md index 4ca9051..3719b1b 100644 --- a/doc/getting_started/docker_hub.md +++ b/doc/getting_started/docker_hub.md @@ -1,7 +1,8 @@ -# pFIRE on Dockerhub # +# pFIRE on Dockerhub Docker is a software that creates a package (called image) containing an application, its library dependencies and a minimal execution environment (e.g. a minimal Ubuntu distribution). These images can be distributed and run by any Docker software installed on the user machine. -In the following are provided the instructions to execute pFIRE on a user machine with Docker. It as been tested on *nix and OsX machines and Windows10 through Windows Linux Subsystem and (Powerwshell). +In the following are provided the instructions to execute pFIRE on a user machine with Docker. +It as been tested on *nix and OsX machines and Windows10 through Windows Linux Subsystem and (PowerShell). ### Installation procedure From 862b19c0ee100ebd462291aba82903afb9109b32 Mon Sep 17 00:00:00 2001 From: Daniele Tartarini Date: Thu, 25 Nov 2021 14:03:33 +0000 Subject: [PATCH 7/8] Fix typos --- doc/user_docs/algorithm.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_docs/algorithm.rst b/doc/user_docs/algorithm.rst index 1cabf1a..e0c1215 100644 --- a/doc/user_docs/algorithm.rst +++ b/doc/user_docs/algorithm.rst @@ -131,7 +131,7 @@ of the gradient information, :math:`\mathbf{{\phi}}` is the same submatrix for e map. The matrix :math:`T` is defined here as the product of the matrices :math:`\mathbf{{G}}` and -:math:`\mathbf{{\Phi}}`, and it is, in general, non-square. We therefore create a soluable matrix +:math:`\mathbf{{\Phi}}`, and it is, in general, non-square. We therefore create a solvable matrix equation from this by multiplying both sides by the transpose :math:`\mathbf{{T}}^t`, .. math:: @@ -142,7 +142,7 @@ yielding an equation with square matrix :math:`\mathbf{{T}}^t\mathbf{{T}}` which standard numerical methods. Unfortunately :math:`\mathbf{{T}}^t\mathbf{{T}}` is typically singular and so we must apply some -kind of regularisation to make the problem soluable. In this case we use the method of Tikhonov +kind of regularisation to make the problem solvable. In this case we use the method of Tikhonov regularisation, which includes an additional smoothing term in the problem. In this case the Laplacian matrix is chosen, adding minimization of the second derivative of the map as the extra constraint (:math:`\mathbf{{L}}\bar{A} = 0` and the problem becomes, From d3e1ad862bd82f5af8d1377cdc5fffdd28fb01da Mon Sep 17 00:00:00 2001 From: Daniele Tartarini Date: Fri, 26 Nov 2021 10:11:23 +0000 Subject: [PATCH 8/8] Fix Typos --- doc/user_docs/algorithm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_docs/algorithm.rst b/doc/user_docs/algorithm.rst index e0c1215..c72330a 100644 --- a/doc/user_docs/algorithm.rst +++ b/doc/user_docs/algorithm.rst @@ -219,7 +219,7 @@ Because of this, pFIRE computes the matrix :math:`\mathbf{{T}}^t\mathbf{{T}}` an :math:`\mathbf{{T}}^t(\bar{F} - \bar{M})` directly. The structure of the final matrix and vector are distributed between the various ranks such that each rank computes an equal number of components of the final data structure. For each matrix or vector element, the location of all the -required image or gradient pixels is determiend and then required values that are not local to the +required image or gradient pixels is determined and then required values that are not local to the rank are communicated using MPI_Alltoall with all ranks communicating at once. Implementation of the computation can be made more efficient by understanding the structure of the