1010
1111Phase field crystal (PFC) is a semi-atomistic technique, containing atomic
1212resolution 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
1515co-evolution of microstructural defects such as dislocations and stacking
1616faults, voids, defect formation in epitaxial growth, displacive phase
1717transitions, and electromigration.
1818
1919The image above shows a simulation of a rapidly solidifying tungsten block
2020approximately 50 x 100 x 200 nm in size, using MovingBC boundary conditions. The
2121rightmost 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
2323provides a transparent view of the surface, revealing the lattice defects that
2424formed during the simulation. This visualization aids in understanding the
2525atomic arrangement, surface features, and internal defects of the tungsten
2626block.
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
3131simulations. 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
3636Transform with time complexity of O(N log N), and there are no known limiting
3737bottlenecks, 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
9898Typically in clusters, these are already installed and can be loaded with an
9999on-liner
@@ -103,18 +103,18 @@ module load gcc openmpi fftw
103103```
104104
105105For 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
109109sudo 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
113113simulations. 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
118118is not found, the library is downloaded from GitHub during the configuration.
119119
120120The last and most important dependency to use OpenPFC is
@@ -132,49 +132,49 @@ cmake --build heffte-2.4.0-build
132132cmake --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
136136when 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
142142export CMAKE_PREFIX_PATH=$HOME /opt/heffte/2.3:$CMAKE_PREFIX_PATH
143143```
144144
145145During 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
148148with OpenPFC. In general, however, it is better to build and install programs
149149one at a time. So, make sure you have HeFFTe installed and working on your
150150system 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,
153153the 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
161161git clone https://github.com/VTT-ProperTune/OpenPFC.git
162162# git clone [email protected] :VTT-ProperTune/OpenPFC.git # if you prefer ssh instead163163cd 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
168168sure to use ` Release ` as it turns on compiler optimizations.
169169
170170``` bash
171171cmake -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
176176variable ` 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
178178environment 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
189189finishes, 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
191191done with ` cmake --install build ` .
192192
193193## Structure of the application
@@ -219,7 +219,7 @@ framework developers themselves.
219219Next, we have classes such as ` Model ` , ` FieldModifier ` , and ` ResultsWriter ` . The
220220` Model ` class is of particular interest as it describes the physics of the
221221model, 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.
223223Currently, users are free to choose whichever time integration method they are
224224comfortable with. However, in the future, we may abstract the time integration
225225method 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
229229implies – it modifies these fields. In more detail, initial and boundary
230230conditions serve as field modifiers and are often also of interest, although
231231some 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
234234format, but nothing is preventing us from implementing, for example, the storage
235235of results in hdf5 format, which is currently under planning.
236236
@@ -280,7 +280,7 @@ add_executable(main main.cpp)
280280target_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
284284straightforward:
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
467467following error message:
468468
469469```text
@@ -473,37 +473,37 @@ asked CMake to find a package configuration file provided by "OpenPFC", but
473473CMake 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
479479find_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
485485Ubuntu, one of these locations is ` /usr/lib/cmake ` , where the files are
486486installed 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
488488installations, 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
492492The first way is to set up an environment variable indicating any extra
493493locations for the files. One option is to use ` CMAKE_PREFIX_PATH ` environment
494494variable, 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)
516516target_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
523523There might be various reasons why the simulation returns NaNs. Despite the
524524reason, 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
526526check that simulation parameters are valid. Thus, it is possible to give invalid
527527parameters 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
529529division 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
548548add_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
554554cmake -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