From d31a4173dc6a1dd31ca6055434a19b930ef9c3c4 Mon Sep 17 00:00:00 2001 From: Agustina Date: Thu, 22 Jul 2021 06:38:26 -0300 Subject: [PATCH] Improve README file (#10) * Fix items in the installation file * Fix typo in the documentation readme * Add the van Keken example in the installation file * Add the documentation link in the readme * Replace the repository readme for the documentation readme Because it is easier to have just one readme to modify --- README.md | 140 ---------------------------- docs/files/readme.rst => README.rst | 4 +- docs/files/installation.rst | 36 ++++++- docs/index.rst | 2 +- 4 files changed, 38 insertions(+), 144 deletions(-) delete mode 100644 README.md rename docs/files/readme.rst => README.rst (89%) diff --git a/README.md b/README.md deleted file mode 100644 index f935f86..0000000 --- a/README.md +++ /dev/null @@ -1,140 +0,0 @@ -# MANDYOC - -MANtle DYnamics simulatOr Code - -## Installation - -Before installing MANDYOC, we need to _install its dependencies_: - -- [PETSc](https://www.mcs.anl.gov/petsc/) -- `gcc` -- `make` -- `git` - -Optional dependencies: - -- `gfortran` - -### Building and installing PETSc - -First, _download_ the latest release of PETSc [from their -[website](https://www.mcs.anl.gov/petsc/download/index.html) or clone their -repository: - -``` -git clone -b release https://gitlab.com/petsc/petsc.git $HOME/petsc -``` - -By default, we will download/clone in `~/petsc`. - -Second, _configure the PETSc build_ and set up the installation directory. -By default, we will install PETSc in `~/petsc`. - -``` -cd $HOME/petsc -./configure \ - PETSC_DIR=$HOME/petsc \ - PETSC_ARCH=arch-label-optimized \ - --with-debugging=0 \ - --with-cc=gcc \ - --with-cxx=g++ \ - --download-fblaslapack \ - --download-mpich \ - --download-hdf5 \ - --download-superlu_dist \ - --download-metis \ - --download-parmetis \ - --download-mumps \ - --download-scalapack \ - --download-cmake \ - COPTFLAGS='-O3 -march=native -mtune=native' \ - CXXOPTFLAGS='-O3 -march=native -mtune=native' -``` - -> Note: If using `gfortran` optional dependency add the options -> `--with-fc=gfortran` and `FOPTFLAGS='-O3 -march=native -mtune=native'` -> to the PETSc build configuration above. - -> Note: If you are build a development version of MANDYOC you can build -> a debug version of PETSc by setting `--with-debugging=1` and removing the -> COPTFLAGS, CXXOPTFLAGS (and FOPTFLAGS) flags. -> In this case, you may set `PETSC_ARCH=arch-label-debug`. - -_Check_ the installation with: - -``` -make all check -``` - -### Build and install MANDYOC - -Build and install MANDYOC by running: - -``` -make all -``` - -> Note: To print MANDYOC runtime options, run mandyoc with `-flags` command line argument. - -## Examples - -### Steps to run the van Keken et al. (1997) example - -- From the `src/` folder, copy the executable to the `examples/vanKeken1997/` - folder: - - ``` - cp mandyoc ../examples/vanKeken1997/ - ``` - - ``` - cd ../examples/vanKeken1997/ - ``` - -- Modify the path of the `mpirun` in `run.sh`. - -- Run the `run.sh` script: - - ``` - sh run.sh - ``` - -- To visualize the evolution of the density structure, run: - - ``` - ipython rho_imshow.py - ``` - -## Contributing - -### Code of conduct - -Please note that this project is released with a -[Contributor Code of Conduct](https://github.com/ggciag/mandyoc/blob/main/CODE_OF_CONDUCT.md). -By participating in this project you agree to abide by its terms. - -### Contributing Guidelines - -**Contributions to MANDYOC are welcome**. -If you have an issue, a bug, a code contribution or a documentation -contribution, _thanks for helping to improve MANDYOC!_ -Check out our -[Contributing guide](https://github.com/ggciag/mandyoc/blob/main/CONTRIBUTING.md). - -## How to visualize the results using Xarray - -You can easily load all output files produced by MANDYOC in Python through -[tapIOca](https://github.com/aguspesce/tapioca). -It organize all output data into a single -[xarray.Dataset](https://xarray.pydata.org/en/stable/), which makes much easier -to manage, inspect and visualize the results. - -You can find installation instructions and examples at the -[tapIOca website](https://github.com/aguspesce/tapioca). - -## License - -This is free software, you can redistribute it and/or modify it under the terms -of the **BSD 3-clause License**. -A copy of this license is provided in -[LICENSE](https://github.com/ggciag/mandyoc/blob/main/LICENSE). diff --git a/docs/files/readme.rst b/README.rst similarity index 89% rename from docs/files/readme.rst rename to README.rst index b5038c6..6135ee5 100644 --- a/docs/files/readme.rst +++ b/README.rst @@ -8,13 +8,13 @@ About ----------- -MANDYOC is a finite element code written written on top of the `PETSc`_ library to simulate thermo-chemical convection of the Earth's mantle. +MANDYOC is a finite element code written on top of the `PETSc`_ library to simulate thermo-chemical convection of the Earth's mantle. Different linear and non-linear rheologies can be adopted, appropriately simulating the strain and stress pattern in the Earth's crust and mantle, both in extensional or collisional tectonics. Documentation ---------------------------- -On the `Documentation page `__, you will be able to find relevant information on how the code works, how it was implemented, how to install it, the description of the parameters and input files, some applications and some useful examples. +On the `Documentation page `__, you will be able to find relevant information on how the code works, how it was implemented, how to install it, the description of the parameters and input files, some applications and some useful examples. Need any help? ------------------------ diff --git a/docs/files/installation.rst b/docs/files/installation.rst index 799d826..9c81b52 100644 --- a/docs/files/installation.rst +++ b/docs/files/installation.rst @@ -12,11 +12,14 @@ Dependencies ------------ * PETSc_ + * gcc + * make + * git -*Optional* dependencies: +**Optional** dependencies: * `gfortran` @@ -100,6 +103,37 @@ Next, **build and install** MANDYOC by running:: To print MANDYOC runtime options, run mandyoc with `-flags` command line argument. +Examples +--------------- + +Steps to run the van Keken et al. (1997) +++++++++++++++++++++++++++++++++++ + +#. From the `src/` folder, copy the executable to the `examples/vanKeken1997/` folder: + + .. code-block:: bash + + cp mandyoc ../examples/vanKeken1997/ + +#. Go to the example folder: + + .. code-block:: bash + + cd ../examples/vanKeken1997/ + +#. Modify the path of the `mpirun` in `run.sh`. + +#. Run the `run.sh` script: + + .. code-block:: bash + + sh run.sh + +#. To visualize the evolution of the density structure, run: + + .. code-block:: bash + + ipython rho_imshow.py .. _PETSc: https://www.mcs.anl.gov/petsc/ diff --git a/docs/index.rst b/docs/index.rst index 171f56c..8f23e07 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ contain the root `toctree` directive. -.. include:: files/readme.rst +.. include:: ../README.rst .. toctree:: :hidden: