Skip to content

Commit 2940eaa

Browse files
DEV: GitHub copilot instructions (#831)
* DEV: add GitHub Copilot instructions for codebase consistency and development practices * Final adjustments instructions
1 parent 71e2b3a commit 2940eaa

File tree

1 file changed

+221
-0
lines changed

1 file changed

+221
-0
lines changed

.github/copilot-instructions.md

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# GitHub Copilot Instructions for RocketPy
2+
3+
This file provides instructions for GitHub Copilot when working on the RocketPy codebase.
4+
These guidelines help ensure consistency with the project's coding standards and development practices.
5+
6+
## Project Overview
7+
8+
RocketPy is a Python library for 6-DOF rocket trajectory simulation.
9+
It's designed for high-power rocketry applications with focus on accuracy, performance, and ease of use.
10+
11+
## Coding Standards
12+
13+
### Naming Conventions
14+
- **Use `snake_case` for all new code** - variables, functions, methods, and modules
15+
- **Use descriptive names** - prefer `angle_of_attack` over `a` or `alpha`
16+
- **Class names use PascalCase** - e.g., `SolidMotor`, `Environment`, `Flight`
17+
- **Constants use UPPER_SNAKE_CASE** - e.g., `DEFAULT_GRAVITY`, `EARTH_RADIUS`
18+
19+
### Code Style
20+
- Follow **PEP 8** guidelines
21+
- Line length: **88 characters** (Black's default)
22+
- Organize imports with **isort**
23+
- Our official formatter is the **ruff frmat**
24+
25+
### Documentation
26+
- **All public classes, methods, and functions must have docstrings**
27+
- Use **NumPy style docstrings**
28+
- Include **Parameters**, **Returns**, and **Examples** sections
29+
- Document **units** for physical quantities (e.g., "in meters", "in radians")
30+
31+
### Testing
32+
- Write **unit tests** for all new features using pytest
33+
- Follow **AAA pattern** (Arrange, Act, Assert)
34+
- Use descriptive test names following: `test_methodname_expectedbehaviour`
35+
- Include test docstrings explaining expected behavior
36+
- Use **parameterization** for testing multiple scenarios
37+
- Create pytest fixtures to avoid code repetition
38+
39+
## Domain-Specific Guidelines
40+
41+
### Physical Units and Conventions
42+
- **SI units by default** - meters, kilograms, seconds, radians
43+
- **Document coordinate systems** clearly (e.g., "tail_to_nose", "nozzle_to_combustion_chamber")
44+
- **Position parameters** are critical - always document reference points
45+
- Use **descriptive variable names** for physical quantities
46+
47+
### Rocket Components
48+
- **Motors**: SolidMotor, HybridMotor and LiquidMotor classes are children classes of the Motor class
49+
- **Aerodynamic Surfaces**: They have Drag curves and lift coefficients
50+
- **Parachutes**: Trigger functions, deployment conditions
51+
- **Environment**: Atmospheric models, weather data, wind profiles
52+
53+
### Mathematical Operations
54+
- Use **numpy arrays** for vectorized operations (this improves performance)
55+
- Prefer **scipy functions** for numerical integration and optimization
56+
- **Handle edge cases** in calculations (division by zero, sqrt of negative numbers)
57+
- **Validate input ranges** for physical parameters
58+
- Monte Carlo simulations: sample from `numpy.random` for random number generation and creates several iterations to assess uncertainty in simulations.
59+
60+
## File Structure and Organization
61+
62+
### Source Code Organization
63+
64+
Reminds that `rocketpy` is a Python package served as a library, and its source code is organized into several modules to facilitate maintainability and clarity. The following structure is recommended:
65+
66+
```
67+
rocketpy/
68+
├── core/ # Core simulation classes
69+
├── motors/ # Motor implementations
70+
├── environment/ # Atmospheric and environmental models
71+
├── plots/ # Plotting and visualization
72+
├── tools/ # Utility functions
73+
└── mathutils/ # Mathematical utilities
74+
```
75+
76+
Please refer to popular Python packages like `scipy`, `numpy`, and `matplotlib` for inspiration on module organization.
77+
78+
### Test Organization
79+
```
80+
tests/
81+
├── unit/ # Unit tests
82+
├── integration/ # Integration tests
83+
├── acceptance/ # Acceptance tests
84+
└── fixtures/ # Test fixtures organized by component
85+
```
86+
87+
### Documentation Structure
88+
```
89+
docs/
90+
├── user/ # User guides and tutorials
91+
├── development/ # Development documentation
92+
├── reference/ # API reference
93+
├── examples/ # Flight examples and notebooks
94+
└── technical/ # Technical documentation
95+
```
96+
97+
## Common Patterns and Practices
98+
99+
### Error Handling
100+
- Use **descriptive error messages** with context
101+
- **Validate inputs** at class initialization and method entry
102+
- Raise **appropriate exception types** (ValueError, TypeError, etc.)
103+
- Include **suggestions for fixes** in error messages
104+
105+
### Performance Considerations
106+
- Use **vectorized operations** where possible
107+
- **Cache expensive computations** when appropriate (we frequently use `cached_property`)
108+
- Keep in mind that RocketPy must be fast!
109+
110+
### Backward Compatibility
111+
- **Avoid breaking changes** in public APIs
112+
- Use **deprecation warnings** before removing features
113+
- **Document code changes** in docstrings and CHANGELOG
114+
115+
## AI Assistant Guidelines
116+
117+
### Code Generation
118+
- **Always include docstrings** for new functions and classes
119+
- **Follow existing patterns** in the codebase
120+
- **Consider edge cases** and error conditions
121+
122+
### Code Review and Suggestions
123+
- **Check for consistency** with existing code style
124+
- **Verify physical units** and coordinate systems
125+
- **Ensure proper error handling** and input validation
126+
- **Suggest performance improvements** when applicable
127+
- **Recommend additional tests** for new functionality
128+
129+
### Documentation Assistance
130+
- **Use NumPy docstring format** consistently
131+
- **Include practical examples** in docstrings
132+
- **Document physical meanings** of parameters
133+
- **Cross-reference related functions** and classes
134+
135+
## Testing Guidelines
136+
137+
### Unit Tests
138+
- **Test individual methods** in isolation
139+
- **Use fixtures** from the appropriate test fixture modules
140+
- **Mock external dependencies** when necessary
141+
- **Test both happy path and error conditions**
142+
143+
### Integration Tests
144+
- **Test interactions** between components
145+
- **Verify end-to-end workflows** (Environment → Motor → Rocket → Flight)
146+
147+
### Test Data
148+
- **Use realistic parameters** for rocket simulations
149+
- **Include edge cases** (very small/large rockets, extreme conditions)
150+
- **Test with different coordinate systems** and orientations
151+
152+
## Project-Specific Considerations
153+
154+
### User Experience
155+
- **Provide helpful error messages** with context and suggestions
156+
- **Include examples** in docstrings and documentation
157+
- **Support common use cases** with reasonable defaults
158+
159+
## Examples of Good Practices
160+
161+
### Function Definition
162+
```python
163+
def calculate_drag_force(
164+
velocity,
165+
air_density,
166+
drag_coefficient,
167+
reference_area
168+
):
169+
"""Calculate drag force using the standard drag equation.
170+
171+
Parameters
172+
----------
173+
velocity : float
174+
Velocity magnitude in m/s.
175+
air_density : float
176+
Air density in kg/m³.
177+
drag_coefficient : float
178+
Dimensionless drag coefficient.
179+
reference_area : float
180+
Reference area in m².
181+
182+
Returns
183+
-------
184+
float
185+
Drag force in N.
186+
187+
Examples
188+
--------
189+
>>> drag_force = calculate_drag_force(100, 1.225, 0.5, 0.01)
190+
>>> print(f"Drag force: {drag_force:.2f} N")
191+
"""
192+
if velocity < 0:
193+
raise ValueError("Velocity must be non-negative")
194+
if air_density <= 0:
195+
raise ValueError("Air density must be positive")
196+
if reference_area <= 0:
197+
raise ValueError("Reference area must be positive")
198+
199+
return 0.5 * air_density * velocity**2 * drag_coefficient * reference_area
200+
```
201+
202+
### Test Example
203+
```python
204+
def test_calculate_drag_force_returns_correct_value():
205+
"""Test drag force calculation with known inputs."""
206+
# Arrange
207+
velocity = 100.0 # m/s
208+
air_density = 1.225 # kg/m³
209+
drag_coefficient = 0.5
210+
reference_area = 0.01 #
211+
expected_force = 30.625 # N
212+
213+
# Act
214+
result = calculate_drag_force(velocity, air_density, drag_coefficient, reference_area)
215+
216+
# Assert
217+
assert abs(result - expected_force) < 1e-6
218+
```
219+
220+
221+
Remember: RocketPy prioritizes accuracy, performance, and usability. Always consider the physical meaning of calculations and provide clear, well-documented interfaces for users.

0 commit comments

Comments
 (0)