diff --git a/README.md b/README.md index 2e597702..ff041c6b 100644 --- a/README.md +++ b/README.md @@ -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)) diff --git a/doc/mdDocs/codingStyle.md b/doc/mdDocs/codingStyle.md new file mode 100644 index 00000000..2808fe54 --- /dev/null +++ b/doc/mdDocs/codingStyle.md @@ -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_; +} +```