xfygogo
/
phasicFlow
mirror of https://github.com/PhasicFlow/phasicFlow.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'PhasicFlow:main' into benchmarks

This commit is contained in:
Wenxuan XU 2025-04-07 11:30:52 +08:00 committed by GitHub
parent 7b534a9e91 c78ab398f6
commit 671b929f52
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 249 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -17,27 +17,36 @@ Ongoing development includes the integration of MPI-based parallelization with d
5. **Hybrid Parallelism:** MPI + OpenMP.
6. **Multi-GPU Parallelism:** MPI + CUDA.
# **Build and Installation**
## **Build and Installation**
PhasicFlow can be compiled for both CPU and GPU execution.
* **Current Development (v-1.0):** Comprehensive build instructions are available [here](https://github.com/PhasicFlow/phasicFlow/wiki/How-to-build-PhasicFlow%E2%80%90v%E2%80%901.0).
* **Latest Release (v-0.1):** Detailed build instructions are available [here](https://github.com/PhasicFlow/phasicFlow/wiki/How-to-Build-PhasicFlow).
# **Comprehensive Documentation**
## **Comprehensive Documentation**
In-depth documentation, including code structure, features, and usage guidelines, is accessible via the [online documentation portal](https://phasicflow.github.io/phasicFlow/).
## **Tutorials and Examples**
### **Tutorials and Examples**
Practical examples and simulation setups are provided in the [tutorials directory](./tutorials). For detailed explanations and step-by-step guides, please refer to the [tutorial section on the PhasicFlow Wiki](https://github.com/PhasicFlow/phasicFlow/wiki/Tutorials).
# **PhasicFlowPlus: Coupled CFD-DEM Simulations**
## Contributing to PhasicFlow
We welcome contributions to PhasicFlow! Whether you're a developer or a new user, there are many ways to get involved. Here's how you can help:
1. Bug Reports
2. Suggestions for better user experience
3. Feature request and algorithm improvements
4. Tutorials, Simulation Case Setups and documentation
5. Direct Code Contributions
For more details on how you can contribute to PhasicFlow see [this page](https://github.com/PhasicFlow/phasicFlow/wiki/How-to-contribute-to-PhasicFlow).
## **PhasicFlowPlus: Coupled CFD-DEM Simulations**
PhasicFlowPlus is an extension of PhasicFlow that facilitates the simulation of particle-fluid systems using resolved and unresolved CFD-DEM methods. The repository for PhasicFlowPlus can be found [here](https://github.com/PhasicFlow/PhasicFlowPlus).
# How to cite PhasicFlow?
## How to cite PhasicFlow?
If you are using PhasicFlow in your research or industrial work, cite the following [article](https://www.sciencedirect.com/science/article/pii/S0010465523001662):
@ -58,9 +67,10 @@ If you are using PhasicFlow in your research or industrial work, cite the follow
}
```
# **Dependencies**
## **Dependencies**
PhasicFlow relies on the following external libraries:
* **Kokkos:** A performance portability ecosystem developed by National Technology & Engineering Solutions of Sandia, LLC (NTESS). ([https://github.com/kokkos/kokkos](https://github.com/kokkos/kokkos))
* **Kokkos:** A community-led performance portability ecosystem within the Linux Foundation's High-Performance Software Foundation (HPSF). ([https://github.com/kokkos/kokkos](https://github.com/kokkos/kokkos))
* **CLI11 1.8:** A command-line interface parser developed by the University of Cincinnati. ([https://github.com/CLIUtils/CLI11](https://github.com/CLIUtils/CLI11))

231
doc/mdDocs/codingStyle.md Normal file
View File

@ -0,0 +1,231 @@
# PhasicFlow Coding Style Guidelines
This document outlines the coding style guidelines for the PhasicFlow codebase.
Adhering to these guidelines ensures consistency, readability, and maintainability of the project.
## 1. FormattingIndentation:
* Use 4 spaces for every logical level and block.
* Line Spacing: Leave two empty lines between sections (e.g., between functions in a .cpp file, between class members).
## 2. Naming ConventionsGeneral Naming:
* All names should start with lowercase letters, except for special names (e.g., Ergun, Hertz).
* Macro names start with Upper case or all the letters are in UPPER case.
* Compound Names: For compound names, the first word starts with a lowercase letter, and subsequent words start with an uppercase letter (e.g., boundaryBase, motionModel).
## 3. File Structure
* Header Files: Use the .hpp extension for header files.
* Source Files: Use the .cpp extension for source files.
* Header and Source File Headers: All header and source files must include a standardized header that describes the project's intention and licensing information.
* File Naming: Header and source file names should correspond to the class they contain. Aim for one class per file.
* Inline Functions: Place inline functions in a separate classNameI.hpp file to avoid cluttering the main header file.
## 4. Class DesignClass Member Order:
* Private members and methods
* Private static members and methods
* Public methods
* Public static methods
* Enumerations and Nested Classes: Declare enumerations and nested classes before all class members and methods.
* Special Functions: Each class must explicitly define all special functions:Constructor, Copy constructor and assignment operator, Move constructor and assignment operator
* Destructor: Each class must have an explicit destructor declaration:`~className() = default`; or `~className();`
* Interface classes or classes with virtual methods must have a virtual destructor.
* Virtual Method Overrides: When implementing a `virtual` method from a base class in a derived class, use the `override` keyword. The same applies to derived class destructors.
## 5. NamespacesOfficial Namespace:
The official namespace for the codebase is pFlow. All entities should be defined within this namespace.
### Example File Structure
```
src/
├── componentName1/
│ ├── componentName1.hpp
│ ├── componentName1.cpp
│ ├── componentName1I.hpp
│ └── ...
└── componentName2/
├── componentName2.hpp
├── componentName2.cpp
└── ...
```
### Example Class Structure
```C++
namespace pFlow
{
class MyClass
{
public:
enum class MyEnum
{
Value1,
Value2
};
class NestedClass
{
// ...
};
private:
int privateMember_;
void privateMethod();
static int privateStaticMember_;
static void privateStaticMethod();
public:
MyClass();
MyClass(const MyClass& other);
MyClass(MyClass&& other);
MyClass& operator=(const MyClass& other);
MyClass& operator=(MyClass&& other);
~MyClass();
void publicMethod();
static void publicStaticMethod();
};
// assuming base class has virtual methods
class DerivedClass
:
public BaseClass
{
public:
...
~DerivedClass() override;
void virtualMethod() override;
};
} // namespace pFlow
```
## 6. Doxygen Documentation
### 6.1. Ruls
provide the documentations in the header files only. In rare cases where you are generating documentations for executables, the doxygen documentation can be supplied in the .cpp file.
* **General Doxygen Style:**
* Use `///` for short documentations for methods and members.
* Use `/** */` for classes and main methods which play a significant role in the class or code.
* Place Doxygen comments *before* the declaration of the entity being documented (e.g., class, function, variable).
* Use `@param` to document function parameters, `@return` for return values, `@brief` for a short description, and `@details` for a more in-depth explanation.
* Use Markdown syntax within Doxygen comments for formatting.
* **File Headers:** Each file should contain a Doxygen comment at the top, including:
* `@file` : The name of the file.
* `@brief`: A brief description of the file's purpose.
* `@author`: The author(s) of the file.
* `@date` : The date of creation or last modification.
* **Class Documentation:**
* Use `/** */` for class documentation.
* Provide a `@brief` description of the class.
* Use `@tparam` to document template parameters.
* Document the purpose of the class, its invariants, and how it should be used.
* **Function/Method Documentation:**
* Use `///` for short documentations.
* Use `/** */` for main methods which play a significant role.
* Provide a `@brief` description of the function.
* Use `@param` to describe each parameter, including its purpose and whether it is an input, output, or input/output parameter.
* Use `@return` to describe the return value, including its meaning and possible values.
* Use `@pre` to document any preconditions that must be met before calling the function.
* Use `@post` to document any postconditions that will be true after the function returns.
* Use `@throws` to document any exceptions that the function may throw.
* Use `@details` for a more detailed explanation of the function's behavior, algorithms, or any other relevant information.
* **Variable Documentation:**
* Use `///<` for single-line documentation of variables.
### 6.2. Doxygen Documentation Examples
* **Class example**
```cpp
/**
* @brief Represents a particle in the simulation.
* @details This class stores the position, velocity, and other physical
* properties of a particle.
*/
class Particle
{
private:
Point position_; ///< The current position of the particle.
Vector velocity_; ///< The current velocity of the particle.
double mass_; ///< The mass of the particle.
public:
/// Constructs a particle with default values.
Particle();
/**
* @brief Updates the position of the particle based on its velocity
* and the given time step.
* @param deltaTime The time elapsed since the last update, in seconds.
*/
void updatePosition(const timeInfo& ti );
/// Gets the current position of the particle.
Point getPosition() const;
};
```
* **Function Example**
```cpp
/**
* @brief Calculates the distance between two points.
* @param p1 The first point.
* @param p2 The second point.
* @return The distance between the two points.
*/
double calculateDistance(const Point& p1, const Point& p2)
{
// Implementation
return 0.0;
}
/// Returns the velocity of the particle.
Vector getVelocity() const
{
return velocity_;
}
```