Skip to content

Commit 51d6b0b

Browse files
authored
Update README.md
Fixed grammar mistakes.
1 parent 3032ed6 commit 51d6b0b

File tree

1 file changed

+69
-69
lines changed

1 file changed

+69
-69
lines changed

README.md

Lines changed: 69 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -10,29 +10,29 @@
1010

1111
Phase field crystal (PFC) is a semi-atomistic technique, containing atomic
1212
resolution information of crystalline structures while operating on diffusive
13-
time scales. PFC has an ability to simulate solidification and elastic-plastic
14-
material response, coupled to a wide range of phenomena, including formation and
13+
time scales. PFC can simulate solidification and elastic-plastic material
14+
response, coupled with a wide range of phenomena, including formation and
1515
co-evolution of microstructural defects such as dislocations and stacking
1616
faults, voids, defect formation in epitaxial growth, displacive phase
1717
transitions, and electromigration.
1818

1919
The image above shows a simulation of a rapidly solidifying tungsten block
2020
approximately 50 x 100 x 200 nm in size, using MovingBC boundary conditions. The
2121
rightmost section depicts the pure atomic structure of the tungsten, the middle
22-
section highlights the surface of the entire object, and the leftmost section
22+
section highlights the surface of the entire object and the leftmost section
2323
provides a transparent view of the surface, revealing the lattice defects that
2424
formed during the simulation. This visualization aids in understanding the
2525
atomic arrangement, surface features, and internal defects of the tungsten
2626
block.
2727

2828
## Scalability and Performance
2929

30-
OpenPFC is an open-source framework for high performance 3D phase field crystal
30+
OpenPFC is an open-source framework for high-performance 3D phase field crystal
3131
simulations. It is designed to scale up from a single laptop to exascale class
32-
supercomputers. OpenPFC has succesfully used to simulate domain of size 8192 x
33-
8192 x 4096 on CSC Mahti. 200 computing nodes were used, where each node
34-
contains 128 cores, thus total 25600 cores were used. During the simulation, 25
35-
TB of memory was utilized. The central part of the solver is Fast Fourier
32+
supercomputers. OpenPFC has successfully been used to simulate a domain of size
33+
8192 x 8192 x 4096 on CSC Mahti. 200 computing nodes were used, where each node
34+
contained 128 cores, thus total of 25600 cores were used. During the simulation,
35+
25 TB of memory was utilized. The central part of the solver is the Fast Fourier
3636
Transform with time complexity of O(N log N), and there are no known limiting
3737
bottlenecks, why larger models could not be calculated as well.
3838

@@ -65,7 +65,7 @@ The project documentation can be found from
6565
## Features
6666

6767
- scales up to tens of thousands of cores, demonstrably
68-
- modern c++17 header only framework, easy to use
68+
- modern c++17 header-only framework, easy to use
6969

7070
## Installing
7171

@@ -80,20 +80,20 @@ Requirements:
8080
- Compiler supporting C++17 standard. C++17 features [are
8181
available](https://gcc.gnu.org/projects/cxx-status.html) since GCC 5. Check
8282
your version number with `g++ --version`. The default compiler might be
83-
relatively old, and more recent version needs to be loaded with `module load
83+
relatively old, and a more recent version needs to be loaded with `module load
8484
gcc`. Do not try to compile with GCC 4.8.5. It will not work. At least GCC
8585
versions 9.4.0 (coming with Ubuntu 20.04) and 11.2 are working.
8686
- [OpenMPI](https://www.open-mpi.org/). All recent versions should work. Tested
87-
with OpenMPI version 2.1.3. Again, you might need to load proper OpenMPI
88-
version with `module load openmpi/2.1.3`, for instance. Additionally, if cmake
87+
with OpenMPI version 2.1.3. Again, you might need to load the proper OpenMPI
88+
version with `module load openmpi/2.1.3`, for instance. Additionally, if CMake
8989
is not able to find proper OpenMPI installation, assistance might be needed by
9090
setting `MPI_ROOT`, e.g. `export MPI_ROOT=/share/apps/OpenMPI/2.1.3`.
9191
- FFTW. Probably all versions will work. Tested with FFTW versions 3.3.2 and
92-
3.3.10. Again, cmake might need some assistance to find the libraries, which
93-
can be controlled with environment variable `FFTW_ROOT`. Depending how FFTW is
94-
installed to system, it might be in non-standard location and `module load
95-
fftw` is needed. You can use commands like `whereis fftw` or `ldconfig -p |
96-
grep fftw` to locate your FFTW installation, if needed.
92+
3.3.10. Again, CMake might need some assistance to find the libraries, which
93+
can be controlled with the environment variable `FFTW_ROOT`. Depending on how
94+
FFTW is installed in the system, it might be in a non-standard location, and
95+
`module load fftw` is needed. You can use commands like `whereis fftw` or
96+
`ldconfig -p | grep fftw` to locate your FFTW installation, if needed.
9797

9898
Typically in clusters, these are already installed and can be loaded with an
9999
on-liner
@@ -103,18 +103,18 @@ module load gcc openmpi fftw
103103
```
104104

105105
For local Linux machines (or WSL2), packages usually can be installed from
106-
repositories, e.g. in case of Ubuntu, the following should work:
106+
repositories, e.g. in the case of Ubuntu, the following should work:
107107

108108
```bash
109109
sudo apt-get install -y gcc openmpi fftw
110110
```
111111

112-
Some OpenPFC applications uses json files to provide initial data for
112+
Some OpenPFC applications use JSON files to provide initial data for
113113
simulations. In principle, applications can also be built to receive initial
114-
data in other ways, but as a widely known file format, we recommend to use json.
115-
The choice for json package is [JSON for Modern C++](https://json.nlohmann.me/).
116-
There exists packages for certain Linux distributions (`nlohmann-json3-dev` for
117-
Ubuntu, `json-devel` for Centos) for easy install. If the system-wide installation
114+
data in other ways, but as a widely known file format, we recommend using JSON.
115+
The choice for the JSON package is [JSON for Modern C++](https://json.nlohmann.me/).
116+
There exist packages for certain Linux distributions (`nlohmann-json3-dev` for
117+
Ubuntu, `json-devel` for Centos) for easy installation. If the system-wide installation
118118
is not found, the library is downloaded from GitHub during the configuration.
119119

120120
The last and most important dependency to use OpenPFC is
@@ -132,49 +132,49 @@ cmake --build heffte-2.4.0-build
132132
cmake --install heffte-2.4.0-build
133133
```
134134

135-
If HeFFTe is installed to some non-standard location, cmake is unable to find it
135+
If HeFFTe is installed in some non-standard location, CMake is unable to find it
136136
when configuring OpenPFC. To overcome this problem, the install path of HeFFTe
137-
can be set into environment variable `CMAKE_PREFIX_PATH`. For example, if HeFFe
138-
is installed to `$HOME/opt/heffte/2.3`, the following is making cmake to find
139-
HeFFTe succesfully:
137+
can be set into the environment variable `CMAKE_PREFIX_PATH`. For example, if HeFFe
138+
is installed to `$HOME/opt/heffte/2.3`, the following is making CMake to find
139+
HeFFTe successfully:
140140

141141
```bash
142142
export CMAKE_PREFIX_PATH=$HOME/opt/heffte/2.3:$CMAKE_PREFIX_PATH
143143
```
144144

145145
During the configuration, OpenPFC prefers local installations, thus if HeFFTe is
146-
already installed and founded, it will be used. For convenience, there is a
147-
fallback method to fetch HeFFTe sources from internet and build it concurrently
146+
already installed and found, it will be used. For convenience, there is a
147+
fallback method to fetch HeFFTe sources from the internet and build it concurrently
148148
with OpenPFC. In general, however, it is better to build and install programs
149149
one at a time. So, make sure you have HeFFTe installed and working on your
150150
system before continuing.
151151

152-
OpenPFC uses [cmake](https://cmake.org/) to automate software building. First
152+
OpenPFC uses [cmake](https://cmake.org/) to automate software building. First,
153153
the source code must be downloaded to some appropriate place. Head to the
154154
[releases](https://github.com/VTT-ProperTune/OpenPFC/releases) page and pick the
155-
newest release and unzip is somewhere. Alternatively, if you are planning to
156-
develop the project itself of are just interested about the bleeding edge
157-
features, you might be interested to clone the repository to your local machine.
158-
GitHub account is needed to clone the project.
155+
newest release and unzip it somewhere. Alternatively, if you are planning to
156+
develop the project itself or are just interested in the bleeding-edge
157+
features, you might be interested in cloning the repository to your local machine.
158+
A GitHub account is needed to clone the project.
159159

160160
```bash
161161
git clone https://github.com/VTT-ProperTune/OpenPFC.git
162162
# git clone [email protected]:VTT-ProperTune/OpenPFC.git # if you prefer ssh instead
163163
cd OpenPFC
164164
```
165165

166-
Next step is to configure project. One might consider at least setting option
167-
`CMAKE_BUILD_TYPE` to `Debug` or `Release`. For large scale simulations, make
166+
The next step is to configure the project. One might consider at least setting an option
167+
`CMAKE_BUILD_TYPE` to `Debug` or `Release`. For large-scale simulations, make
168168
sure to use `Release` as it turns on compiler optimizations.
169169

170170
```bash
171171
cmake -DCMAKE_BUILD_TYPE=Release -S . -B build
172172
```
173173

174-
Keep on mind, that configuration will download HeFFTe if the local installation
175-
is not found. To use local installation instead, add HeFFTe path to environment
174+
Keep in mind, that the configuration will download HeFFTe if the local installation
175+
is not found. To use local installation instead, add HeFFTe path to the environment
176176
variable `CMAKE_PREFIX_PATH` or add `Heffte_DIR` option to point where HeFFTe
177-
configuration files are installed. Typical configuration command in cluster
177+
configuration files are installed. A typical configuration command in a cluster
178178
environment is something like
179179

180180
```bash
@@ -185,9 +185,9 @@ cmake -DCMAKE_BUILD_TYPE=Release \
185185
-S . -B build
186186
```
187187

188-
Then, building can be done with command `cmake --build build`. After build
188+
Then, building can be done with the command `cmake --build build`. After the build
189189
finishes, one should find example codes from `./build/examples` and apps from
190-
`./build/apps`. Installation to path defined by `CMAKE_INSTALL_PREFIX` can be
190+
`./build/apps`. Installation to a path defined by `CMAKE_INSTALL_PREFIX` can be
191191
done with `cmake --install build`.
192192

193193
## Structure of the application
@@ -219,7 +219,7 @@ framework developers themselves.
219219
Next, we have classes such as `Model`, `FieldModifier`, and `ResultsWriter`. The
220220
`Model` class is of particular interest as it describes the physics of the
221221
model, including the partial differential equation (PDE) itself. Inside the
222-
`Model` class, there is a function called `step` which needs to be overridden.
222+
`Model` class, there is a function called `step` that needs to be overridden.
223223
Currently, users are free to choose whichever time integration method they are
224224
comfortable with. However, in the future, we may abstract the time integration
225225
method away from the model and create a separate class to approach the problem
@@ -229,8 +229,8 @@ during time stepping. The `FieldModifier` class does exactly what the name
229229
implies – it modifies these fields. In more detail, initial and boundary
230230
conditions serve as field modifiers and are often also of interest, although
231231
some already implemented ones exist. Lastly, we should mention the
232-
`ResultsWriter`, which implements a way to store results during certain periods
233-
of time. We have some existing implementations such as raw binary format and vti
232+
`ResultsWriter`, which implements a way to store results during certain periods.
233+
We have some existing implementations such as raw binary format and vti
234234
format, but nothing is preventing us from implementing, for example, the storage
235235
of results in hdf5 format, which is currently under planning.
236236

@@ -280,7 +280,7 @@ add_executable(main main.cpp)
280280
target_link_libraries(main OpenPFC)
281281
```
282282

283-
With the help of `CMakeLists.txt`, build and compilation of application is
283+
With the help of `CMakeLists.txt`, build and compilation of the application is
284284
straightforward:
285285

286286
```bash
@@ -289,8 +289,8 @@ cmake --build build
289289
./build/main
290290
```
291291

292-
There is also some examples in [examples][examples-url] directory, which can be
293-
used as a base for your own codes.
292+
There are also some examples in [examples][examples-url] directory, which can be
293+
used as a base for your codes.
294294

295295
## Example: Cahill-Hilliard equation
296296

@@ -459,11 +459,11 @@ The full code can be found from [examples](/examples/12_cahn_hilliard.cpp).
459459
460460
## Troubleshooting and debugging
461461
462-
Here's some common problems and their solutions.
462+
Here are some common problems and their solutions.
463463
464464
### FindOpenPFC.cmake not found
465465
466-
During the configuration step (`cmake -S. -B build`), you might end up to the
466+
During the configuration step (`cmake -S. -B build`), you might end up with the
467467
following error message:
468468
469469
```text
@@ -473,37 +473,37 @@ asked CMake to find a package configuration file provided by "OpenPFC", but
473473
CMake did not find one.
474474
```
475475

476-
The error message is trying to say command in `CMakeLists.txt` (line 3) fails:
476+
The error message is trying to say the command in `CMakeLists.txt` (line 3) fails:
477477

478478
```cmake
479479
find_package(OpenPFC REQUIRED) # <-- this is failing
480480
```
481481

482-
The reason why this happens is that cmake is not able to find the package. By
483-
default, cmake finds packages by looking a file which is called
484-
`Find<package_name>.cmake` from couple of standard locations. For example, in
482+
The reason why this happens is that CMake is not able to find the package. By
483+
default, CMake finds packages by looking at a file which is called
484+
`Find<package_name>.cmake` from a couple of standard locations. For example, in
485485
Ubuntu, one of these locations is `/usr/lib/cmake`, where the files are
486486
installed when doing a global install of some package with root rights. When
487-
working with supercomputers, users in general doesn't have rights to make global
487+
working with supercomputers, users, in general, don't have rights to make global
488488
installations, thus packages are almost always installed to some non-default
489-
locations. Thus, one needs to give some hints to cmake where the file could be
490-
found. This can be done (at least) two different ways.
489+
locations. Thus, one needs to give some hints to CMake where the file could be
490+
found. This can be done (at least) in two different ways.
491491

492492
The first way is to set up an environment variable indicating any extra
493493
locations for the files. One option is to use `CMAKE_PREFIX_PATH` environment
494494
variable, like before. For example, if `OpenPFC` is installed to `/opt/OpenPFC`,
495-
one can give that information before starting configuration:
495+
one can give that information before starting the configuration:
496496

497497
```bash
498498
export CMAKE_PREFIX_PATH=/opt/OpenPFC:$CMAKE_PREFIX_PATH
499499
cmake -S . -B build
500500
# rest of the things ...
501501
```
502502

503-
Another option is to hard code the choise inside the `CMakeLists.txt` file
503+
Another option is to hardcode the choice inside the `CMakeLists.txt` file
504504
directly. Just keep in mind, that this option is not very portable as users
505505
tends to install software to several different locations and there is no any
506-
general rule how it should be done. So, instead of defining `CMAKE_PREFIX_PATH`
506+
general rule on how it should be done. So, instead of defining `CMAKE_PREFIX_PATH`
507507
before doing configuration, the following change in `CMakeLists.txt` is
508508
equivalent:
509509

@@ -516,20 +516,20 @@ add_executable(main main.cpp)
516516
target_link_libraries(main OpenPFC)
517517
```
518518

519-
This way, cmake know to search necessary files from the path given above.
519+
This way, CMake knows to search for necessary files from the path given above.
520520

521521
### NaNs in the simulation
522522

523523
There might be various reasons why the simulation returns NaNs. Despite the
524524
reason, it usually makes sense to stop simulation as it doesn't do anything
525-
useful. OpenPFC does not currently have built-in json validator, which would
525+
useful. OpenPFC does not currently have a built-in JSON validator, which would
526526
check that simulation parameters are valid. Thus, it is possible to give invalid
527527
parameters to the simulation, which might lead to NaNs. If some model parameters
528-
which should be defined are undefined and thus zero, there might be zero
528+
that should be defined are undefined and thus zero, there might be a zero
529529
division problem.
530530

531-
There is schema file for the input file, which can be used to validate the json
532-
file using external validator like `check-jsonchema`:
531+
There is a schema file for the input file, which can be used to validate the JSON
532+
file using an external validator like `check-jsonchema`:
533533

534534
```bash
535535
check-jsonschema --schemafile apps/schema.json input.json
@@ -548,7 +548,7 @@ Another way to enable NaN check is to use compile option `NAN_CHECK_ENABLED`. In
548548
add_compile_definitions(NAN_CHECK_ENABLED)
549549
```
550550

551-
Or, when configuring project with cmake, the following is equivalent:
551+
Or, when configuring a project with CMake, the following is equivalent:
552552

553553
```bash
554554
cmake -DNAN_CHECK_ENABLED=ON -S . -B build
@@ -561,11 +561,11 @@ source file:
561561
#define NAN_CHECK_ENABLED
562562
```
563563

564-
Then, in code level, there's a macro `CHECK_AND_ABORT_IF_NANS`, which can be
565-
used to check if there's any NaNs in the simulation. The macro is defined in
564+
Then, at the code level, there's a macro `CHECK_AND_ABORT_IF_NANS`, which can be
565+
used to check if there are any NaNs in the simulation. The macro is defined in
566566
`openpfc/utils/nancheck.hpp`. This is a zero overhead when compiling with
567-
release build type. At the moment, user must explicitly call the macro, but in
568-
the future it might be called automatically in some situations. Example usage is
567+
release build type. At the moment, a user must explicitly call the macro, but in
568+
the future, it might be called automatically in some situations. Example usage is
569569
(see also [this][tungsten-nan-check] example):
570570

571571
```cpp

0 commit comments

Comments
 (0)