Update Readme and related documentation

johnnonweiler · johnnonweiler · commit 0c84f473ab89 · 2020-10-22T15:19:53.000+01:00
This commit makes no significant changes to contents, but rewords
a lot of the English, moves some bits around (including moving the
installation guide into a separate file), and tidies up some of
the formatting.
diff --git a/Readme.md b/Readme.md
@@ -1,109 +1,80 @@
 
-
 ![Ubuntu and MacOS CI](https://github.com/ukaea/parallel-preprocessor/workflows/ubuntu-macos/badge.svg)
 ![Fedora CI](https://github.com/ukaea/parallel-preprocessor/workflows/fedora-debian/badge.svg)
 
-**Parallel-preprocessor: a prototype of parallel CAE geometry preprocessing framework**
+# Parallel-preprocessor (PPP)
+
+A prototype parallel CAE geometry preprocessing framework
 
-by Qingfeng Xia  
-Research Software Engineering Group of UKAEA  
-License: LGPL v2.1  
-Copyright UKAEA, 2019~2020  
+by Qingfeng Xia, UKAEA
 
+Copyright 2019-2020 UKAEA
 
-[**Documentation pages (including this Readme)**](https://ukaea.github.io/parallel-preprocessor/site/doxygen-docs.html)
+License: LGPL v2.1
 
+## Documentation
+
+For more information, please see the
+[**documentation website**](https://ukaea.github.io/parallel-preprocessor/site/doxygen-docs.html) (which includes the contents of this Readme file).
 
 ## Feature overview
 
-Currently, this software provides multi-threading geometry imprint and collision check, via command line user interface. This software has demonstrated faster and more controllable geometry **collision-detection, imprinting** on **large geometry assemblies (10k+ parts)** that is not possible on most existing CAD tools.
+This software provides multi-threaded geometry **collision detection and imprinting** via a command line interface. It has faster and more controllable performance on **large geometry assemblies (with 10k+ parts)** than is possible with most existing CAD tools.
 
-This software aims to be a framework for more CAE/CAE **preprocessing operatons** for large geometry assemblies upto 1 million parts, such as fusion reactor, aeroplane, aero-engine as a whole, using high performance computation  infrastructure like Exa-scale super-computer. Eventually, automatical and intelligent engineering design will be enabled through this framework and other software tools.  see more [Technical Overview](./wiki/TechOverview.md) on why a parallel preprocessor is needed in the era of E-scale (10^18 FLops) computation.
+The following screenshot shows the software making good use of multiple CPUs, with high CPU usage across 64 threads on a 32-core CPU.  (Source: Dr Andrew Davis)
 
 ![CPU usage of parallel-preprocessor using 64 threads on a 32-core CPU](./wiki/assets/ppp_multithreading_cpu_usage.png)
 
-Screenshot for the CPU usage of parallel-preprocessor using 64 threads on a 32-core CPU (Source: Dr Andy Davis)
+## Getting started
 
+A quick start guide for using PPP can be found in [wiki/GetStarted.md](wiki/GetStarted.md).
 
-## Get started (tutorial)
+## Future plans
 
-[wiki/GetStarted.md](wiki/GetStarted.md): quick started guide to use geometry processing pipeline
+This software aims to be a framework for more CAE preprocessing operations for large geometry assemblies with up to 1 million parts, such as fusion reactors, aeroplanes and aero engines, using high performance computing infrastructure in exascale supercomputers. Eventually, automatic and intelligent engineering design will be enabled through this framework and other software tools.
 
-## Future plan
+[wiki/TechOverview.md](./wiki/TechOverview.md) explains more about why a parallel preprocessor is needed in the era of exascale computing.
 
-[wiki/Roadmap.md](wiki/Roadmap.md): lists short-term and long-term plan, depends on funding status. Partially sponsoring this project is welcomed to enhance existing modules or develop new modules.
+[wiki/Roadmap.md](wiki/Roadmap.md) lists short-term and long-term plans which depend on funding status. Additional funding for enhancing existing modules or developing new modules would be very welcome.
 
 ## Disclaimer
 
-This is **NOT** a production quality software, but a prototype to demonstrate the potential of accelereating CAE preprocessing by massive-parallel on HPC. We would like to apply more good practice in research software engineering, once resource is available.
+This is **not** yet production quality software, but is a prototype which demonstrates the potential of accelerating CAE preprocessing on HPC systems. We hope to improve the software and apply better software engineering practices in future.
 
-According to the open source [license](./LICENSE),  **there is no warranty for this free library**
+**There is no warranty for this free library.**
 
 ## Platforms supported
 
-This project has been designed to be cross-platform, but only Linux is supported as the baseline platform.
+This project has been designed to be cross-platform, and currently a number of Linux distributions are supported:
 
-+ Ubuntu latest LTS as the primary/baseline development platform, with deb binary package generated 
-    - Debian package should be achievable, since OpenCASCADE are available in official repository
++ The latest LTS version of Ubuntu is the primary development platform, and a Debian package is generated by the CI build.
 
-+ Fedora 30+  with OpenCascade 7.x package available from official repository, have rpm binary package generated.
++ Fedora 30+ with OpenCascade 7.x package available from official repository, with an RPM binary package generated.
 
-+ Compiling from source code for other Linux platforms is straight-forward,  driven by cmake and cpack, guidance provided. 
-    - Centos8 should work without much effort, but OpenCASCADE must be compiled from source at first.
-    - Centos7 software stack is outdated for compiler and cmake , using docker/singularity instead.
++ MacOS compiling and packaging is done via homebrew, with a DragNDrop binary package generated.
 
-+ Windows 10 users are encouraged to use WSL with one of the supported Linux distributions, while guide to compile on Windows natively has been added.
++ Windows 10 users are encouraged to use WSL with one of the supported Linux distributions. (A guide to native compilation on Windows has been added, but this build is experimental.)
 
-+ MacOS compiling and packaging is done via homebrew, DragNDrop binary package is available.
++ Versions can be built from the source code for other Linux platforms (using CMake and CPack).  Centos8 should work without much effort (with OpenCascade compiled from source). The build tools in the Centos7 software stack are too old, so Docker/Singularity should be used for Centos7 support.
 
-Conda package and Linux native package for Ubuntu LTS may be available in the future, see [packaging.md](wiki/Packaging.md)
+Conda packages may be available in the future. See [wiki/Packaging.md](wiki/Packaging.md).
 
 ## Installation guide
 
-**Note: user must install runtime dependencies (TBB, OpenCASCADE, etc, see Compile guide wiki pages for each platform) then install the downloaded binary package. Hint: if user have freecad installed, then all dependencies should have installed**
-
-
-### Download (x86_64 architecture) binary packages
-Ubuntu deb package and fedora 30+ rpm package, conda packages for windows, it should be available to download on **github Release** for this public github. The unstable package build from the latest code on the main branch can be downloaded here <https://github.com/ukaea/parallel-preprocessor/releases/tag/dev>
-
-**Note: choose the correct operation system, and the package is targeting at system-wide python3**
-
-The package file has the name pattern: `parallel-preprocessor-<this_software_version>-dev_<OS name>-<OS version>.<package_suffix>` If your OS is not supported, you need to compile it by yourself,  there is documentation for installation dependency and build for all major platforms.
-
-All the latest binary packages (built on each push/merge of the main branch) can be downloaded from
-https://github.com/ukaea/parallel-preprocessor/releases
-
-For Ubuntu and Debian: 
-remove the older version by `sudo apt remove parallel-preprocessor`, and install the downloaded
-`sudo dpkg -i parallel-preprocessor*.deb`
-
-For Fedora:
-remove the older version by `sudo dnf remove parallel-preprocessor`
-`sudo rpm -ivh parallel-preprocessor*.rpm` or double click to bring up package installer.
-
-Coming soon: parallel-preprocessor dmg package for MacOS 10.15
-
-Coming later: conda package for Windows 10.
-
-### Test the installation
-
-[wiki/Testing.md](wiki/Testing.md): unit test and integration tests written in Python. User can validate the software building and installation by run some of the test cases.
-
----
+There are instructions for installation in [wiki/Installation.md](wiki/Installation.md).  Runtime dependencies must be installed before PPP release packages (and the easiest way to do this is probably by installing FreeCAD).
 
-## [Developer document and guide] (./DeveloperGuide.md)
+## Developer guide
 
-+ compiling and packaging on Linux, MacOS, Windows
-+ archicture, parallel, user interface, API, documentation design
+Information for developers, such as a guide for building from source, and documentation about the software design and implementation, can be found in [wiki/DeveloperGuide.md](wiki/DeveloperGuide.md).
 
----
+## Contributions
 
-## Contribution
+Please submit GitHub issues and pull requests!
 
-Please submit issue on gihtub issues, and send in your fix by PR, see more details in [workflow for contribution](./wiki/Contribution.md)
+See more about the workflow for contributions in [wiki/Contribution.md](wiki/Contribution.md).
 
-## Acknowledgement
+## Acknowledgements
 
-Funding from August 2019 ~ April 2020: STEP project in UKAEA <http://www.ccfe.ac.uk/step.aspx>
+Funding from August 2019 - April 2020 was provided by the [STEP project in UKAEA](http://www.ccfe.ac.uk/step.aspx).
 
-Dr Andrew Davis of UKAEA, has contributed his technical insight,  test geometries and other support to this software project. Also thank to my colleagues Dr John Nonweiler, Dr Jonathon Shimwell, etc.  for testing and reviewing this software.
+Dr Andrew Davis of UKAEA, has contributed his technical insight,  test geometries and other support to this software project. Also thanks to other colleagues, including John Nonweiler and Dr Jonathon Shimwell, for testing and reviewing this software.
diff --git a/wiki/GetStarted.md b/wiki/GetStarted.md
@@ -1,10 +1,19 @@
-## Get Started
+# Get Started
 
-### Command line interface
+## Command line interface
 
-Geometry pipeline can be started in a terminal. `geomPipeline.py` takes 2 positional arguments, the first is the action, and the second is the input file path. For example,  `geomPipeline.py imprint your_geometry_file_path` ,  just replace *your_geometry_file_path* by your geometry. 
+Following installation (see [wiki/Installation.md](wiki/Installation.md)), the starting point for users is the command line:
+
+```bash
+geomPipeline.py imprint your_geometry_file_path
+```
+
+(with *your_geometry_file_path* replaced by the path to your geometry.)
+
+This starts the geometry pipeline. `geomPipeline.py` takes 2 positional arguments, the first is the action, and the second is the input file path.
+
+Optional arguments for all pipelines:
 
-Optional arguments for all pipelines, it is expected other pipelines also follow this convention.
 ```
   -h, --help            show this help message and exit
   -o OUTPUT_FILE, --output-file OUTPUT_FILE
@@ -22,7 +31,8 @@ Optional arguments for all pipelines, it is expected other pipelines also follow
                         verbosity: for console or terminal: DEBUG, PROGRESS, INFO, WARNING, ERROR
 ```
 
-optional arguments for geometry pipeline
+Optional arguments for the geometry pipeline:
+
 ```
   --metadata METADATA   input metadata file, only for brep input geometry
   --tolerance TOLERANCE
@@ -33,7 +43,7 @@ optional arguments for geometry pipeline
 
 Always run `geomPipeline.py -h` to get the latest arguments.  
 
-### Geometry preprocessing features
+## Geometry preprocessing features
 
 Implemented geometry processing actions are: `check,detect,merge,imprint,search`, some other planned actions `tessellate, fix, decompose` can be found in [Roadmap.md](Roadmap.md)
 
@@ -48,31 +58,31 @@ Usage of other actions such as `search, check, detect, decompose`
 `geomPipeline.py check geometry_file` will check for errors, e.g. volume too small, invalid geometry, etc
 `geomPipeline.py detect geometry_file` will detect collision between solid shapes, see more shape spatial relationship types defined in the type `Geom::CollisionType`
 
-### Input geometry format supported
+## Input geometry format supported
 
 + FreeCAD native format, *.FCStd
-+ Step geometry exchange format, *.step/*.step
-+ OpenCASCADE native format, *.brep/*.brp, may combined with `*.metadata.json` (parallel-processor output meta data format)
++ Step geometry exchange format, *.step
++ OpenCASCADE native format, \*.brep/\*.brp, may combined with `*.metadata.json` (PPP output meta data format)
 + a json manifest file: a list of dict (geometry file path + material name)
-  ```json
+
+```json
     [{"material": "Copper",  "filename": "path_to_geometry_file1" },
-     {"material": "Steel",  "filename": "path_to_geometry_file2" },
-    ]
-  ```
-  see doxygen generate document for this class for most updated information <>
+     {"material": "Steel",  "filename": "path_to_geometry_file2" }]
+```
 
+  see doxygen generate document for this class for most updated information <>
 
-### Debug your installation
+## Debug your installation
 
 `which geomPipeline` on Unix-like system, or `where geomPipeline` on Windows to see if executable has been installed on PATH. 
 
 NOTE:  if installed using deb/rpm on ubuntu and fedora, while user has anaconda activated, then user will not be able to use c-extension module `ppp`. For example, on Ubuntu the ppp module `ppp.cpython-36m-x86_64-linux-gnu.so` is installed to `/usr/lib/python3/dist-packages/`. In that case, `python3 /usr/bin/geomPipeline.py manifest.json` will start an external process by python to run pipeline without using `ppp` module.
 
 On windows, a batch file calling may be generated to run python script "geomPipeline.py" without "python path_to/geomePipeline.py".
 
+## Advanced usage (adjust pipeline parameters)
 
-### Advanced usage (adjust pipeline parameters)
-####  Pipeline configuration generation (python script)
+### Pipeline configuration generation (python script)
 
 `geomPipeline.py` will generate a json configuration based on user input (by default `config.json` in the current folder),  then starts the geometry preprocessing pipeline. For example, the imprint action will be organized into a pipeline of several GeometryProcessors, with default parameters written into the `config.json`. 
 
@@ -81,6 +91,6 @@ If the output is not ideal, users can edit parameters in the generated `config.j
 Actually, all the processing computation is done by `pppGeomPipeline` which is an executable compiled from C++ code. This executable only accepts a json configuration file, e.g. `pppGeomPipeline path_to_json_config.json`.  
 
 The split of high-level user-oriented python script and lower-level C++ program has the benefits:
+
 + to ease the debugging of mixed python and C++ programming
 + to ease the parallel programming, since Python has the GIL problem
-
diff --git a/wiki/Installation.md b/wiki/Installation.md
@@ -0,0 +1,31 @@
+# Installing PPP
+
+## Install runtime dependencies
+
+Runtime dependencies (TBB, OpenCascade, etc. - see the compilation guides for each platform) must be installed before PPP binary packages.  Note: If FreeCAD is installed, then this includes the dependencies required by PPP.
+
+## Download (x86_64 architecture) binary packages
+
+Debian packages for Ubuntu and RPM packages for Fedora 30+ are available to download from <https://github.com/ukaea/parallel-preprocessor/releases>.  (These are built automatically when PRs are merged on the main branch.)  For other operating systems, please compile from source.
+
+Package file names follow this pattern: `parallel-preprocessor-<this_software_version>-dev_<OS name>-<OS version>.<package_suffix>`.
+
+**Note: Packages use system-wide python3.**
+
+For Ubuntu and Debian:
+
+- Remove old versions: `sudo apt remove parallel-preprocessor`
+- Then install: `sudo dpkg -i parallel-preprocessor*.deb`
+
+For Fedora:
+
+- Remove old versions: `sudo dnf remove parallel-preprocessor`
+- Then install: `sudo rpm -ivh parallel-preprocessor*.rpm`
+
+Coming soon: DMG package for MacOS 10.15
+
+Coming later: Conda package for Windows 10
+
+## Test the installation
+
+Please run the Python tests described in [wiki/Testing.md](wiki/Testing.md) to test your installation.
