Skip to content

Commit 21c73a7

Browse files
coding4Acausecoding4Acause
committed
Initial commit
1 parent 3121be1 commit 21c73a7

File tree

1 file changed

+185
-0
lines changed

1 file changed

+185
-0
lines changed

‎contributing.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Contributing to PANKH
2+
3+
First off, thank you for considering contributing to **PANKH**!
4+
Your contributions—whether in the form of code, documentation, bug reports, feature requests, or testing—are all highly appreciated.
5+
6+
> If you're not ready to contribute code but want to support the project:
7+
> - Star the repository
8+
> - Share it with others in your field
9+
> - Cite it in your academic work
10+
> - Use it in your classroom or lab
11+
12+
---
13+
14+
## Table of Contents
15+
16+
- [Code of Conduct](#code-of-conduct)
17+
- [How to Contribute](#how-to-contribute)
18+
- [Reporting Bugs](#reporting-bugs)
19+
- [Suggesting Features](#suggesting-features)
20+
- [Adding New Code or Examples](#adding-new-code-or-examples)
21+
- [Improving Documentation](#improving-documentation)
22+
- [Style Guide](#style-guide)
23+
- [Commit Messages](#commit-messages)
24+
- [Setting Up Locally](#setting-up-locally)
25+
- [Running Tests](#running-tests)
26+
- [Project Vision and Contribution Opportunities](#project-vision-and-contribution-opportunities)
27+
28+
29+
30+
---
31+
32+
## Code of Conduct
33+
34+
Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing. By participating in this project, you agree to follow its terms.
35+
36+
---
37+
38+
## How to Contribute
39+
40+
### Reporting Bugs
41+
42+
If you encounter a bug:
43+
44+
- Check if it’s already reported in [Issues](https://github.com/coding4Acause/PANKH/issues)
45+
- If not, [open a new issue](https://github.com/coding4Acause/PANKH/issues/new)
46+
- Include:
47+
- What you expected to happen
48+
- What actually happened
49+
- Steps to reproduce it
50+
- System info: OS, compiler version, etc.
51+
- Input files, if possible
52+
53+
### Suggesting Features
54+
55+
If you have an idea for a feature:
56+
57+
- First, check [existing issues](https://github.com/coding4Acause/PANKH/issues)
58+
- If it's not there, open a new issue with a clear title and description
59+
- Explain why it would be useful, and any ideas on implementation
60+
61+
62+
### Adding New Code or Examples
63+
64+
If you're submitting new code (e.g. motion modules, solvers, visualization):
65+
66+
- Fork the repository
67+
- Create a new branch (`feature/your-feature-name`)
68+
- Keep functions modular and avoid hardcoding
69+
- If you're adding examples (e.g. sudden acceleration, pitch–plunge):
70+
- Place input files in `examples/your_case/`
71+
- Write a short README for the new example
72+
- Make sure it runs with `./PANKH_solver input.json`
73+
74+
### Improving Documentation
75+
76+
You can improve:
77+
78+
- The `README.md` (installation, usage, references)
79+
- The `examples/` documentation
80+
- The input JSON format explanation
81+
- Add doc comments in the code
82+
83+
---
84+
85+
## Style Guide
86+
87+
- Use **C++11 or newer**
88+
- No classes/structs (for now) – keep procedural
89+
- Maintain consistent formatting:
90+
- 4-space indentation
91+
- `snake_case` for variable names
92+
- Use `Eigen::VectorXd`, `Eigen::MatrixXd`, etc. when applicable
93+
- Keep the `main.cpp` clean – parse input in a separate file
94+
- Place `.h` files in `includes/`, `.cpp` in `src/`
95+
96+
---
97+
98+
## Commit Messages
99+
100+
Please follow this format:
101+
102+
```
103+
<type>: <short summary>
104+
105+
<body - optional, wrap at 72 chars>
106+
```
107+
108+
Example:
109+
110+
```
111+
fix: correct vortex strength update in unsteady solver
112+
113+
The Kutta condition wasn’t enforced properly for high reduced frequencies.
114+
```
115+
116+
Types: `fix`, `feat`, `docs`, `refactor`, `test`, `chore`
117+
118+
---
119+
120+
## Setting Up Locally
121+
122+
```bash
123+
git clone https://github.com/coding4Acause/PANKH.git
124+
cd PANKH
125+
g++ -o PANKH_solver src/*.cpp -Iincludes -std=c++11
126+
```
127+
128+
Input files are in JSON format and passed to the solver like:
129+
130+
```bash
131+
./PANKH_solver input.json
132+
```
133+
134+
---
135+
136+
## Running Tests
137+
138+
We use basic `test.cpp` files to check solver outputs against reference data.
139+
140+
```bash
141+
g++ -o test_solver test.cpp -std=c++11
142+
./test_solver
143+
```
144+
145+
The test compares `Cl` values against `*_ref.dat` files within a defined tolerance.
146+
147+
> GitHub Actions CI runs these tests automatically on every push.
148+
149+
---
150+
151+
## Project Vision and Contribution Opportunities
152+
153+
PANKH is an open-source C++ framework for unsteady aerodynamic simulations using the unsteady vortex panel method. It aims to be **lightweight**, **modular**, and **research-friendly**—serving as a platform for both educational purposes and high-fidelity aerodynamic investigations.
154+
155+
We welcome contributions from researchers, students, developers, and enthusiasts who are passionate about unsteady flow simulations and numerical methods in fluid dynamics.
156+
157+
### Contribution Opportunities
158+
159+
Here are several ways you can contribute to the development of PANKH:
160+
161+
- **Fix bugs**: Help identify, report, and resolve bugs to improve the robustness of the codebase.
162+
- **Improve documentation**: Contribute to better usage instructions, inline documentation, or example cases.
163+
- **Suggest or implement enhancements**: Propose new features or optimization techniques to improve performance and usability.
164+
- **Cross-platform support**: Ensure smooth compilation and execution across different operating systems (Linux, Windows, macOS).
165+
- **Add tests**: Contribute unit tests or regression tests to ensure correctness and stability.
166+
- **Performance tuning**: Optimize computational efficiency, solver speed, or memory usage.
167+
- **New modules or algorithms**: Add aerodynamic models, improve numerical stability, or include other simulation features.
168+
- **Example simulations**: Submit useful cases in the `examples/` directory along with proper documentation and expected results.
169+
- **Geometry module improvements**: Help extend the current airfoil module to support arbitrary airfoil shapes via `.dat` files and automate panel generation.
170+
171+
### Special Areas of Interest
172+
173+
The PANKH core team is actively seeking contributors in the following areas:
174+
175+
- **Development of a GUI or CLI**: We welcome contributors to build a graphical user interface or an interactive command-line tool similar to *XFOIL*, allowing users to control simulation parameters and view flow visualizations more intuitively.
176+
- **Improved airfoil support**: Extend the geometry module to handle *arbitrary airfoil geometries*, including NACA or imported `.dat` formats, and automatically generate surface panels with smooth curvature handling.
177+
- **Fluid–Structure Interaction (FSI)**: We are working on incorporating structural flexibility into the solver for *2-way FSI* simulations with deformable airfoils.
178+
- *3D extension*: The roadmap includes extending PANKH from 2D unsteady panel methods to full *3D vortex-lattice-based simulations* in the near future.
179+
180+
If any of these areas interest you, please reach out or open a discussion—we’d love to collaborate!
181+
182+
You can check the [Issues](https://github.com/your_username/PANKH/issues) page to find tasks labeled `good first issue` or `help wanted`, or suggest new ideas of your own.
183+
184+
Thank you for helping make **PANKH** better!
185+
— *The Maintainers*

0 commit comments

Comments
 (0)