Trajectories
This commit is contained in:
308
docs/ARCHITECTURE.md
Normal file
308
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# RocketTools Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
RocketTools is a single-page application (SPA) built with **React + Vite**, organized into logical layers:
|
||||
|
||||
1. **Pages** — Route-level components
|
||||
2. **Components** — Reusable UI elements
|
||||
3. **Hooks** — State management & business logic
|
||||
4. **Engine** — Core calculations & algorithms
|
||||
5. **App.jsx** — Router configuration
|
||||
|
||||
## Layer Responsibilities
|
||||
|
||||
### Pages (`src/pages/`)
|
||||
|
||||
Each page is a route-level component that:
|
||||
- Uses one or more custom hooks for state
|
||||
- Composes domain-specific components
|
||||
- Manages local UI state (modals, tabs, etc.)
|
||||
|
||||
**Pages:**
|
||||
- `Home.jsx` — Landing page with feature overview
|
||||
- `Solver.jsx` — Equation solver workspace
|
||||
- `EnginePage.jsx` — Engine design tools
|
||||
- `RocketPage.jsx` — Vehicle design tools
|
||||
- `TrajectoryPage.jsx` — Flight simulation
|
||||
- `DocsPage.jsx` — In-app documentation
|
||||
- `KnowledgebaseEquationsPage.jsx` — Equation reference
|
||||
- `KnowledgebaseFuelsPage.jsx` — Propellant database
|
||||
- `KnowledgebaseAblativesPage.jsx` — Ablative materials
|
||||
|
||||
### Components (`src/components/`)
|
||||
|
||||
Pure, composable UI elements that accept props and render JSX.
|
||||
|
||||
**Solver Components:**
|
||||
- `Workspace.jsx` — Drop zone for constraint cards
|
||||
- `VariablePalette.jsx` — Draggable variable list
|
||||
- `VariableCard.jsx` — Input field with unit conversion
|
||||
- `ResultsPanel.jsx` — Results table display
|
||||
|
||||
**Engine/Rocket Components:**
|
||||
- `rocket/RocketModel3D.jsx` — Three.js 3D scene
|
||||
- `trajectory/TrajectoryPlot.jsx` — Canvas flight path chart
|
||||
- `trajectory/TimelineBar.jsx` — Playback controls
|
||||
|
||||
### Hooks (`src/hooks/`)
|
||||
|
||||
Custom React hooks encapsulate domain state & logic.
|
||||
|
||||
**State Hooks:**
|
||||
```
|
||||
useSolver()
|
||||
├─ variables: Map<id, value>
|
||||
├─ constraints: Map<id, constraint>
|
||||
├─ dispatch(action)
|
||||
└─ results: Map<id, solvedValue>
|
||||
|
||||
useEngineDesign()
|
||||
├─ engineInputs: {chamberPressure, fuels, ...}
|
||||
├─ engineResults: {thrust, isp, ...}
|
||||
├─ setEngineInputs()
|
||||
└─ structureResults: {wallThickness, mass, ...}
|
||||
|
||||
useRocketDesign()
|
||||
├─ rocketInputs: {outerRadius, tankConfig, ...}
|
||||
├─ rocketResults: {totalMass, twr, ...}
|
||||
└─ setRocketInputs()
|
||||
|
||||
useTrajectory()
|
||||
├─ config: {vehicle, engine, atmosphere, ...}
|
||||
├─ playback: {time, speed, isPlaying}
|
||||
├─ events: [{type, time, data}]
|
||||
└─ runSimulation()
|
||||
```
|
||||
|
||||
### Engine (`src/engine/`)
|
||||
|
||||
Pure JavaScript modules with **zero React dependencies**. These can be:
|
||||
- Unit tested independently
|
||||
- Reused in Node.js or other environments
|
||||
- Debugged without UI overhead
|
||||
|
||||
**Module Breakdown:**
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `variables.js` | Variable catalog (name, unit, type) |
|
||||
| `equations.js` | Equation definitions + solvers |
|
||||
| `solver.js` | Constraint propagation algorithm |
|
||||
| `numerics.js` | Math utilities (bisection, Mach) |
|
||||
| `engineDesignCalcs.js` | Combustion, ablation, structure |
|
||||
| `rocketDesignCalcs.js` | Tank geometry, mass budget |
|
||||
| `trajectoryCalcs.js` | RK4 integrator, event detection |
|
||||
| `knowledgebaseData.js` | Material & fuel databases |
|
||||
|
||||
## Data Flow Patterns
|
||||
|
||||
### Solver Workflow
|
||||
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
[VariableCard updates constraint]
|
||||
↓
|
||||
dispatch(setConstraint) → useSolver
|
||||
↓
|
||||
solver.solve() → [greedy propagation]
|
||||
↓
|
||||
useSolver state updates
|
||||
↓
|
||||
[VariableCard/ResultsPanel re-render]
|
||||
```
|
||||
|
||||
### Engine Design Workflow
|
||||
|
||||
```
|
||||
User Input (EnginePage)
|
||||
↓
|
||||
useEngineDesign.setEngineInputs()
|
||||
↓
|
||||
engineDesignCalcs.calcCombustion()
|
||||
+ engineDesignCalcs.calcCooling()
|
||||
+ engineDesignCalcs.calcStructure()
|
||||
↓
|
||||
useSolver state updates (memoized)
|
||||
↓
|
||||
[EnginePage, RocketPage re-render]
|
||||
```
|
||||
|
||||
### Rocket Design Workflow
|
||||
|
||||
```
|
||||
User Input (RocketPage)
|
||||
↓
|
||||
useRocketDesign.setRocketInputs()
|
||||
↓
|
||||
rocketDesignCalcs.calcTankGeometry()
|
||||
+ rocketDesignCalcs.calcMassBudget()
|
||||
+ rocketDesignCalcs.noseConeProfile()
|
||||
↓
|
||||
useRocketDesign state updates (memoized)
|
||||
↓
|
||||
[RocketModel3D, RocketPage re-render]
|
||||
```
|
||||
|
||||
### Trajectory Simulation Workflow
|
||||
|
||||
```
|
||||
User Config (TrajectoryPage)
|
||||
↓
|
||||
useTrajectory.runSimulation()
|
||||
↓
|
||||
trajectoryCalcs.runSimulation()
|
||||
[RK4 integrator loop]
|
||||
[Event detection]
|
||||
↓
|
||||
states[] + events[] returned
|
||||
↓
|
||||
useTrajectory state updates
|
||||
↓
|
||||
[TrajectoryPlot, TimelineBar re-render]
|
||||
```
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
### 1. Separation of Concerns
|
||||
- **Engine layer**: Pure math, no React
|
||||
- **Hooks layer**: State management, memoization, side effects
|
||||
- **Component layer**: UI rendering only
|
||||
- **Page layer**: Route composition, layout
|
||||
|
||||
**Benefit**: Engine code is testable, reusable, and maintainable independently of React.
|
||||
|
||||
### 2. Constraint Solver as Core
|
||||
The solver uses **greedy constraint propagation**:
|
||||
- User sets constraint on a variable
|
||||
- Solver finds equations referencing that variable
|
||||
- Solves for unknowns using math or bisection
|
||||
- Propagates newly-computed values (recursive)
|
||||
|
||||
**Benefit**: Intuitive UI (users see automatic computation), flexible equation network.
|
||||
|
||||
### 3. Three.js via React Three Fiber
|
||||
Rather than direct Three.js imperative API:
|
||||
- Use `<Canvas>`, `<Mesh>`, etc. as React components
|
||||
- Hooks like `useFrame()` for animations
|
||||
- Drei helpers for common geometries
|
||||
|
||||
**Benefit**: Declarative, composable, integrates with React state.
|
||||
|
||||
### 4. Canvas for Trajectory Plotting
|
||||
HTML5 Canvas instead of SVG:
|
||||
- Handles 1000s of points efficiently
|
||||
- Responsive to window resize
|
||||
- Custom click/hover interactions
|
||||
|
||||
**Benefit**: Performance, flexibility.
|
||||
|
||||
## Memoization Strategy
|
||||
|
||||
Use `useMemo()` to avoid re-computation:
|
||||
|
||||
```javascript
|
||||
// Hook definition
|
||||
const engineResults = useMemo(() => {
|
||||
return calcCombustion(engineInputs) // only runs when engineInputs changes
|
||||
}, [engineInputs])
|
||||
```
|
||||
|
||||
**Rule**: Memoize expensive calculations; skip for cheap operations.
|
||||
|
||||
## State Management (No Redux)
|
||||
|
||||
React hooks provide sufficient state management for this app:
|
||||
- `useState()` for local UI state
|
||||
- Custom hooks + `useCallback()` for complex logic
|
||||
- `useMemo()` for expensive computations
|
||||
- Props drilling is acceptable for this size
|
||||
|
||||
**Alternative**: Could migrate to Redux/Zustand if app grows significantly.
|
||||
|
||||
## 3D Rendering Pipeline
|
||||
|
||||
```
|
||||
RocketModel3D.jsx (R3F Canvas)
|
||||
↓
|
||||
[useRocketDesign hook provides geometry]
|
||||
↓
|
||||
TankSection, NoseCone components
|
||||
↓
|
||||
THREE.CylinderGeometry, SphereGeometry, LatheGeometry
|
||||
↓
|
||||
Material (MeshStandardMaterial)
|
||||
↓
|
||||
Lighting, OrbitControls
|
||||
↓
|
||||
Canvas rendered to DOM
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
No tests currently, but recommended:
|
||||
|
||||
**Unit Tests** (Jest):
|
||||
```javascript
|
||||
// src/engine/__tests__/solver.test.js
|
||||
import { solve } from '../solver.js'
|
||||
test('solves linear equation', () => {
|
||||
const eqs = [{var: 'x', fn: (x) => 2*x - 5}]
|
||||
const result = solve(eqs, {y: 10})
|
||||
expect(result.x).toBeCloseTo(2.5)
|
||||
})
|
||||
```
|
||||
|
||||
**Integration Tests** (React Testing Library):
|
||||
```javascript
|
||||
// src/pages/__tests__/Solver.test.jsx
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import Solver from '../Solver'
|
||||
test('Solver page renders', () => {
|
||||
render(<Solver />)
|
||||
expect(screen.getByText(/Equation Solver/i)).toBeInTheDocument()
|
||||
})
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
1. **Memoization** — Expensive calculations in `useMemo()`
|
||||
2. **Lazy Loading** — Routes loaded on-demand (React Router)
|
||||
3. **Canvas Rendering** — 60 FPS for trajectory animation
|
||||
4. **Variable Updates** — Solver propagation is greedy (stops early)
|
||||
|
||||
**Potential Bottlenecks:**
|
||||
- Large variable networks (100+ equations)
|
||||
- Complex 3D geometries (reduce polygon count)
|
||||
- Trajectory with 1000s of timesteps (reduce accuracy or cache)
|
||||
|
||||
## File Organization Best Practices
|
||||
|
||||
- **One component per file** (except tiny helpers)
|
||||
- **Colocate tests** with source (`__tests__` subfolder)
|
||||
- **Group by domain** (rocket, trajectory, solver) not by type
|
||||
- **Keep hooks small** (< 50 lines of logic)
|
||||
- **Engine code** has zero dependencies on React or UI
|
||||
|
||||
## Extension Points
|
||||
|
||||
### Adding a New Page
|
||||
1. Create `src/pages/NewPage.jsx`
|
||||
2. Add route in `App.jsx`
|
||||
3. Add NavLink if needed
|
||||
|
||||
### Adding a New Feature Module
|
||||
1. Create hook: `src/hooks/useNewFeature.js`
|
||||
2. Create components: `src/components/NewFeature*.jsx`
|
||||
3. Add calculations to `src/engine/` if needed
|
||||
4. Create page: `src/pages/NewFeaturePage.jsx`
|
||||
|
||||
### Adding Material Properties
|
||||
1. Edit `src/engine/knowledgebaseData.js`
|
||||
2. Add to `FUELS`, `ABLATIVES`, or `STRUCTURAL_MATERIALS` array
|
||||
3. Auto-appears in UI
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-02 | **Status**: Current (v3)
|
||||
496
docs/CONTRIBUTING.md
Normal file
496
docs/CONTRIBUTING.md
Normal file
@@ -0,0 +1,496 @@
|
||||
# Contributing Guide
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
- Node.js 18+
|
||||
- npm or yarn
|
||||
- Basic understanding of React, JavaScript
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Clone/navigate to project
|
||||
cd rocketry
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start dev server
|
||||
npm run dev
|
||||
|
||||
# Open browser
|
||||
# http://localhost:5173
|
||||
```
|
||||
|
||||
### Project Structure Overview
|
||||
|
||||
```
|
||||
src/
|
||||
├── engine/ # Pure math, zero React deps
|
||||
├── hooks/ # State management
|
||||
├── components/ # UI components
|
||||
├── pages/ # Route pages
|
||||
└── App.jsx # Router
|
||||
```
|
||||
|
||||
See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed breakdown.
|
||||
|
||||
---
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding a New Equation
|
||||
|
||||
**File**: `src/engine/equations.js`
|
||||
|
||||
1. **Check if variables exist** in `variables.js`
|
||||
- If not, add them with `id`, `name`, `unit`, `category`, `type`
|
||||
|
||||
2. **Add equation object**:
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: 'myEquation',
|
||||
name: 'My Equation Name',
|
||||
variables: ['var1', 'var2', 'var3'],
|
||||
equation: 'var1 = var2 * var3', // for reference
|
||||
solvers: {
|
||||
var1: (inputs) => inputs.var2 * inputs.var3,
|
||||
var2: (inputs) => inputs.var1 / inputs.var3,
|
||||
var3: (inputs) => inputs.var1 / inputs.var2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Test manually**
|
||||
- Go to Solver page
|
||||
- Drag variables onto workspace
|
||||
- Set constraints, verify solver computes correct values
|
||||
|
||||
### For Transcendental Equations (Bisection)
|
||||
|
||||
```javascript
|
||||
import { bisection } from '../numerics.js'
|
||||
|
||||
{
|
||||
id: 'machEquation',
|
||||
solvers: {
|
||||
machNumber: (inputs) => {
|
||||
const fn = (M) => isentropicAreaRatio(M, inputs.gamma) - inputs.areaRatio
|
||||
return bisection(fn, 0.1, 10, 1e-6)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adding a Material to Knowledgebase
|
||||
|
||||
**File**: `src/engine/knowledgebaseData.js`
|
||||
|
||||
**For fuels/oxidizers:**
|
||||
```javascript
|
||||
FUELS.push({
|
||||
id: 'newFuel',
|
||||
name: 'New Fuel',
|
||||
formula: 'C8H18', // typical hydrocarbon
|
||||
density: 800, // kg/m³
|
||||
molecularWeight: 114,
|
||||
properties: {
|
||||
combustionTemp: 3500,
|
||||
gamma: 1.25,
|
||||
charVelocity: 1500 // m/s
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
**For ablatives:**
|
||||
```javascript
|
||||
ABLATIVES.push({
|
||||
id: 'newAblative',
|
||||
name: 'New Ablative',
|
||||
density: 1400,
|
||||
erosionRate: 0.020, // inch/s @ 300 psi
|
||||
pressureExponent: 0.35, // power-law exponent
|
||||
tempLimit: 2100, // K
|
||||
notes: 'Best for chamber walls'
|
||||
})
|
||||
```
|
||||
|
||||
**For structural materials:**
|
||||
```javascript
|
||||
STRUCTURAL_MATERIALS.push({
|
||||
id: 'newMaterial',
|
||||
name: 'New Material',
|
||||
density: 4500, // kg/m³
|
||||
yieldStrength: 900, // MPa
|
||||
youngModulus: 200, // GPa
|
||||
meltingPoint: 1800, // K
|
||||
cte: 12e-6, // 1/K
|
||||
notes: 'Good for hot sections'
|
||||
})
|
||||
```
|
||||
|
||||
Changes auto-appear in UI (hot reload).
|
||||
|
||||
### Adding a New Page
|
||||
|
||||
1. **Create page component** (`src/pages/NewPage.jsx`):
|
||||
|
||||
```javascript
|
||||
import { useState } from 'react'
|
||||
|
||||
export default function NewPage() {
|
||||
return (
|
||||
<div className="flex-1 overflow-auto p-6">
|
||||
<h1 className="text-3xl font-bold mb-4">New Feature</h1>
|
||||
{/* Your content */}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
2. **Add route** in `src/App.jsx`:
|
||||
|
||||
```javascript
|
||||
import NewPage from './pages/NewPage.jsx'
|
||||
|
||||
// In Routes:
|
||||
<Route path="/new-feature" element={<NewPage />} />
|
||||
```
|
||||
|
||||
3. **Add navigation link** in header if needed:
|
||||
|
||||
```javascript
|
||||
<NavLink
|
||||
to="/new-feature"
|
||||
className={/* classes */}
|
||||
>
|
||||
New Feature
|
||||
</NavLink>
|
||||
```
|
||||
|
||||
### Adding a 3D Component
|
||||
|
||||
**File**: `src/components/new3d/NewComponent.jsx`
|
||||
|
||||
Use React Three Fiber (`@react-three/fiber`):
|
||||
|
||||
```javascript
|
||||
import { Canvas } from '@react-three/fiber'
|
||||
import { OrbitControls } from '@react-three/drei'
|
||||
|
||||
export default function NewComponent() {
|
||||
return (
|
||||
<Canvas>
|
||||
<ambientLight intensity={0.6} />
|
||||
<directionalLight position={[5, 5, 5]} />
|
||||
<mesh>
|
||||
<boxGeometry args={[1, 1, 1]} />
|
||||
<meshStandardMaterial color="red" />
|
||||
</mesh>
|
||||
<OrbitControls />
|
||||
</Canvas>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Style & Conventions
|
||||
|
||||
### Naming
|
||||
|
||||
- **Components**: PascalCase (`VariableCard.jsx`)
|
||||
- **Files**: match component name or use kebab-case for utilities
|
||||
- **Variables/functions**: camelCase
|
||||
- **Constants**: UPPER_SNAKE_CASE
|
||||
- **React hooks**: `useFeatureName`
|
||||
|
||||
### File Organization
|
||||
|
||||
```javascript
|
||||
// 1. Imports (grouped)
|
||||
import React, { useState, useMemo } from 'react'
|
||||
import { helper } from '../utils'
|
||||
import './styles.css'
|
||||
|
||||
// 2. Types/Constants
|
||||
const DEFAULT_VALUE = 10
|
||||
|
||||
// 3. Component
|
||||
export default function MyComponent({ prop1, prop2 }) {
|
||||
// Hooks
|
||||
const [state, setState] = useState(0)
|
||||
|
||||
// Computed values
|
||||
const memoized = useMemo(() => {
|
||||
return expensiveCalculation()
|
||||
}, [deps])
|
||||
|
||||
// Event handlers
|
||||
const handleClick = () => { /* ... */ }
|
||||
|
||||
// JSX
|
||||
return <div>...</div>
|
||||
}
|
||||
```
|
||||
|
||||
### Styling
|
||||
|
||||
- Use **Tailwind CSS** classes
|
||||
- Keep dark theme (slate-950 background)
|
||||
- Responsive: mobile-first, use Tailwind breakpoints
|
||||
|
||||
```javascript
|
||||
<div className="px-4 py-2 rounded-md bg-slate-800 hover:bg-slate-700 transition-colors">
|
||||
Click me
|
||||
</div>
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
- Add only for **why**, not **what**
|
||||
- Keep code self-documenting
|
||||
- Avoid comments for obvious logic
|
||||
|
||||
```javascript
|
||||
// ✅ Good: explains intent
|
||||
// Pressure correction for temperature variation
|
||||
const correctedRate = baseRate * Math.pow(temp / refTemp, exponent)
|
||||
|
||||
// ❌ Bad: obvious from code
|
||||
const x = x + 1 // increment x
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
Currently no test suite. Recommended additions:
|
||||
|
||||
### Unit Tests (Jest)
|
||||
|
||||
```javascript
|
||||
// src/engine/__tests__/solver.test.js
|
||||
import { solve } from '../solver'
|
||||
|
||||
test('solves linear equation', () => {
|
||||
const eqs = [{
|
||||
id: 'eq1',
|
||||
variables: ['x', 'y'],
|
||||
solvers: {
|
||||
x: (inputs) => inputs.y * 2
|
||||
}
|
||||
}]
|
||||
const result = solve(eqs, { y: 5 })
|
||||
expect(result.x).toBe(10)
|
||||
})
|
||||
```
|
||||
|
||||
### Component Tests (React Testing Library)
|
||||
|
||||
```javascript
|
||||
// src/components/__tests__/VariableCard.test.jsx
|
||||
import { render, screen, fireEvent } from '@testing-library/react'
|
||||
import VariableCard from '../VariableCard'
|
||||
|
||||
test('renders input field', () => {
|
||||
render(<VariableCard variable={{name: 'thrust'}} />)
|
||||
expect(screen.getByDisplayValue('0')).toBeInTheDocument()
|
||||
})
|
||||
|
||||
test('updates on input change', () => {
|
||||
const { getByDisplayValue } = render(<VariableCard />)
|
||||
fireEvent.change(getByDisplayValue('0'), {target: {value: '100'}})
|
||||
expect(getByDisplayValue('100')).toBeInTheDocument()
|
||||
})
|
||||
```
|
||||
|
||||
### Manual Testing Checklist
|
||||
|
||||
- [ ] Solver computes correct values
|
||||
- [ ] Engine design produces reasonable thrust/Isp
|
||||
- [ ] Rocket design mass budget is sensible
|
||||
- [ ] Trajectory plot shows reasonable path
|
||||
- [ ] 3D models render without errors
|
||||
- [ ] UI is responsive on mobile
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Memoization
|
||||
|
||||
Use `useMemo()` for expensive calculations:
|
||||
|
||||
```javascript
|
||||
const results = useMemo(() => {
|
||||
return engineDesignCalcs.calcCombustion(inputs) // expensive
|
||||
}, [inputs])
|
||||
```
|
||||
|
||||
### Avoid Unnecessary Re-renders
|
||||
|
||||
- Lift state up only when needed
|
||||
- Use `useCallback()` for event handlers passed to children
|
||||
- Consider `React.memo()` for pure components
|
||||
|
||||
```javascript
|
||||
const VariableCard = React.memo(({ variable, onChange }) => {
|
||||
// Component only re-renders if variable or onChange changes
|
||||
return <input onChange={onChange} />
|
||||
})
|
||||
```
|
||||
|
||||
### Canvas Performance
|
||||
|
||||
- Limit trajectory states to ~5000 points
|
||||
- Use fixed timestep (don't go below 0.01 s)
|
||||
- Reduce Three.js geometry complexity if needed
|
||||
|
||||
---
|
||||
|
||||
## Git Workflow
|
||||
|
||||
### Branching
|
||||
|
||||
- `main` — production-ready code
|
||||
- `feature/*` — new features
|
||||
- `fix/*` — bug fixes
|
||||
- `docs/*` — documentation updates
|
||||
|
||||
### Commits
|
||||
|
||||
Keep commits atomic and well-described:
|
||||
|
||||
```bash
|
||||
git commit -m "Add pressure-corrected ablation model
|
||||
|
||||
- Implement power-law pressure exponent for erosion rate
|
||||
- Add pressure factor display in Engine page
|
||||
- Update knowledgebase with exponent values
|
||||
- Update docs with pressure correction formula"
|
||||
```
|
||||
|
||||
### Pull Requests
|
||||
|
||||
Include:
|
||||
- What changed and why
|
||||
- How to test
|
||||
- Any breaking changes
|
||||
- Related issues
|
||||
|
||||
---
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### Browser DevTools
|
||||
|
||||
**Console:**
|
||||
```javascript
|
||||
// Log solver state
|
||||
console.log('Constraints:', solverState.constraints)
|
||||
console.log('Results:', solverState.results)
|
||||
```
|
||||
|
||||
**React DevTools Extension:**
|
||||
- Inspect component props/state
|
||||
- Profile render performance
|
||||
- Trace updates
|
||||
|
||||
### Hot Reload
|
||||
|
||||
Changes to `src/` automatically reload (Vite).
|
||||
- Engine modules reload: refresh browser
|
||||
- Components/pages: usually hot reload instantly
|
||||
|
||||
### Performance Profiling
|
||||
|
||||
```javascript
|
||||
// In React component
|
||||
console.time('calculation')
|
||||
const result = expensiveFunction()
|
||||
console.timeEnd('calculation') // logs elapsed time
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### ❌ Don't: Mutate state directly
|
||||
```javascript
|
||||
state.value = 100 // Wrong!
|
||||
setState({...state, value: 100}) // Correct
|
||||
```
|
||||
|
||||
### ❌ Don't: Create objects in dependencies
|
||||
```javascript
|
||||
const obj = {x: 1}
|
||||
useMemo(() => calc(obj), [obj]) // Runs every render!
|
||||
```
|
||||
|
||||
### ✅ Do: Memoize dependencies
|
||||
```javascript
|
||||
const obj = useMemo(() => ({x: 1}), [])
|
||||
useMemo(() => calc(obj), [obj]) // Stable
|
||||
```
|
||||
|
||||
### ❌ Don't: Forget dependencies
|
||||
```javascript
|
||||
useEffect(() => {
|
||||
doSomething(dep)
|
||||
}, []) // Missing 'dep'!
|
||||
```
|
||||
|
||||
### ✅ Do: Include all dependencies
|
||||
```javascript
|
||||
useEffect(() => {
|
||||
doSomething(dep)
|
||||
}, [dep])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Asking for Help
|
||||
|
||||
**Before asking:**
|
||||
1. Check existing documentation
|
||||
2. Search similar equations/features
|
||||
3. Review console for errors
|
||||
4. Try simplifying the problem
|
||||
|
||||
**When asking:**
|
||||
- Include error message
|
||||
- Describe what you tried
|
||||
- Provide minimal reproducible example
|
||||
|
||||
---
|
||||
|
||||
## Roadmap Ideas
|
||||
|
||||
Potential future features:
|
||||
|
||||
- **Multi-stage rockets** — sequential stage design
|
||||
- **Thrust vector control** — pitch/yaw steering
|
||||
- **Grid fin aerodynamics** — drag & control surfaces
|
||||
- **Solid rocket motors** — grain geometry, regression
|
||||
- **Regenerative cooling** — thermal analysis
|
||||
- **Uncertainty analysis** — Monte Carlo simulations
|
||||
- **Optimization** — automated mass/performance optimization
|
||||
- **Data export** — CAD, simulation formats (GMAT, Basilisk)
|
||||
- **Multiplayer** — collaborative design sessions
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- [React Docs](https://react.dev)
|
||||
- [Tailwind CSS](https://tailwindcss.com)
|
||||
- [Three.js Docs](https://threejs.org/docs)
|
||||
- [React Three Fiber](https://docs.pmnd.rs/react-three-fiber)
|
||||
- [Vite Docs](https://vitejs.dev)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-02 | **Status**: Current
|
||||
394
docs/ENGINE_DESIGN.md
Normal file
394
docs/ENGINE_DESIGN.md
Normal file
@@ -0,0 +1,394 @@
|
||||
# Engine Design Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The **Engine Design** tool calculates rocket engine performance, material erosion, and structural requirements. It integrates combustion thermodynamics, ablative material degradation, and hoop stress analysis into a unified interface.
|
||||
|
||||
## Main Sections
|
||||
|
||||
### Combustion Design
|
||||
Configure chamber, nozzle, and propellant properties to predict thrust, Isp, and exit conditions.
|
||||
|
||||
### Ablative Erosion
|
||||
Model chamber liner erosion based on pressure-dependent rates and propellant choice.
|
||||
|
||||
### Structural Sizing
|
||||
Calculate wall thicknesses and component masses using hoop stress formula.
|
||||
|
||||
---
|
||||
|
||||
## Combustion Design
|
||||
|
||||
### Inputs
|
||||
|
||||
**Chamber:**
|
||||
- `chamberPressure` (MPa) — combustion chamber pressure
|
||||
- `nozzleDiameter` (mm) — nozzle throat diameter
|
||||
- `expansionRatio` — nozzle exit / throat area ratio
|
||||
- `divergenceAngle` (°) — nozzle divergence cone angle
|
||||
|
||||
**Propellant Selection:**
|
||||
- `fuelType` — dropdown (RP1, Methane, Hydrogen, etc.)
|
||||
- `oxidiserType` — dropdown (LOX, N2O4, etc.)
|
||||
- **Note**: Propellant properties come from knowledgebase (T0, gamma, Mw, etc.)
|
||||
|
||||
**Design Options:**
|
||||
- `injectorType` — impingement, shower-head, multi-element
|
||||
- `coolingMethod` — none, regenerative (future)
|
||||
- `nozzleShape` — conical (15-20°), bell curve (optional)
|
||||
|
||||
### Outputs (Computed)
|
||||
|
||||
**Performance:**
|
||||
- `thrustVacuum` (kN) — vacuum thrust (accounting for exit pressure)
|
||||
- `thrustSeaLevel` (kN) — sea level thrust (accounting for ambient pressure)
|
||||
- `specificImpulseVacuum` (s) — Isp in vacuum
|
||||
- `specificImpulseSeaLevel` (s) — Isp at sea level
|
||||
- `characteristicVelocity` (m/s) — c* = P0·At / ṁ
|
||||
|
||||
**Combustion Conditions:**
|
||||
- `chamberTemperature` (K) — adiabatic flame temperature
|
||||
- `exitTemperature` (K) — nozzle exit temperature
|
||||
- `machNumber` — exit Mach number (computed via bisection)
|
||||
- `exitPressure` (MPa) — nozzle exit pressure
|
||||
- `exitDensity` (kg/m³) — exhaust density at exit
|
||||
|
||||
**Nozzle Geometry:**
|
||||
- `throatDiameter` (mm) — computed from chamber P, thrust, mass flow
|
||||
- `exitDiameter` (mm) — exit diameter = throat × √(expansionRatio)
|
||||
- `nozzleLength` (mm) — divergence section length
|
||||
- `thrustCoefficient` — CF (thrust coefficient for flow)
|
||||
|
||||
**Flow Properties:**
|
||||
- `massFlowRate` (kg/s) — propellant mass flow rate
|
||||
- `exitVelocity` (m/s) — effective exhaust velocity
|
||||
- `burnRate` (mm/s) — for propellant grain design
|
||||
|
||||
### Key Equations
|
||||
|
||||
**Thrust (from area and pressure):**
|
||||
```
|
||||
F = P0·At·CF + (Pe - P_ambient)·Ae
|
||||
```
|
||||
Where CF is thrust coefficient from isentropic relations.
|
||||
|
||||
**Specific Impulse:**
|
||||
```
|
||||
Isp = Ve / g0
|
||||
Isp_sl = (Ve - (Pe - P_atm) / ṁ · Ae) / g0
|
||||
```
|
||||
|
||||
**Exit Temperature (isentropic flow):**
|
||||
```
|
||||
Te = T0 · (Pe / P0)^((γ-1)/γ)
|
||||
```
|
||||
|
||||
**Mass Flow Rate (from energy balance):**
|
||||
```
|
||||
ṁ = P0 · At / c*
|
||||
c* = √(2·(γ+1)/(γ-1) · R·T0) for ideal nozzle
|
||||
```
|
||||
|
||||
**Characteristic Velocity:**
|
||||
```
|
||||
c* = √(2·(γ+1)/(γ-1) · R·T0 · (2/(γ+1))^((γ+1)/(γ-1)))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ablative Erosion (v2)
|
||||
|
||||
### Material Properties
|
||||
|
||||
Each ablative material in the knowledgebase has:
|
||||
- **Density** (kg/m³) — ablator material density
|
||||
- **Base Erosion Rate** (inch/s) — reference erosion at standard pressure (typically 300 psi)
|
||||
- **Pressure Exponent** (n) — power-law sensitivity to pressure
|
||||
|
||||
### Pressure-Corrected Erosion
|
||||
|
||||
The key innovation of v2 is **pressure-dependent erosion rates**:
|
||||
|
||||
```
|
||||
erosion_rate(P) = base_rate · (P / P_ref)^n
|
||||
```
|
||||
|
||||
Where:
|
||||
- `base_rate` — from material database (inch/s @ 300 psi)
|
||||
- `P` — chamber pressure (Pa)
|
||||
- `P_ref` — reference pressure (300 psi = 2.068 MPa)
|
||||
- `n` — pressure exponent (material-specific)
|
||||
|
||||
### Pressure Exponents by Material Class
|
||||
|
||||
**Composites:**
|
||||
- PAXS (polyester/glass): n = 0.38
|
||||
- KFSI (silica/phenolic): n = 0.35
|
||||
- Carbon phenolic: n = 0.32
|
||||
|
||||
**Elastomers:**
|
||||
- ZIRCONIA (zirconia/silicone): n = 0.48
|
||||
- Butyl rubber: n = 0.50
|
||||
|
||||
**Theory**: Lower n = less pressure-sensitive (better for high-P engines)
|
||||
|
||||
### Example Calculation
|
||||
|
||||
**Material:** PAXS, base_rate = 0.025 in/s, n = 0.38
|
||||
|
||||
**At different pressures:**
|
||||
- 300 psi: rate = 0.025 × (300/300)^0.38 = 0.025 in/s
|
||||
- 500 psi: rate = 0.025 × (500/300)^0.38 = 0.032 in/s
|
||||
- 1000 psi: rate = 0.025 × (1000/300)^0.38 = 0.042 in/s
|
||||
- 1500 psi: rate = 0.025 × (1500/300)^0.38 = 0.050 in/s
|
||||
|
||||
### Erosion Calculation
|
||||
|
||||
**Inputs:**
|
||||
- Chamber pressure (Pa)
|
||||
- Burn time (s)
|
||||
- Ablative material (from dropdown)
|
||||
- Initial liner thickness (mm)
|
||||
|
||||
**Process:**
|
||||
1. Look up material properties (base_rate, n)
|
||||
2. Calculate pressure factor: `(P / P_ref)^n`
|
||||
3. Apply correction: `effective_rate = base_rate × factor`
|
||||
4. Erosion depth: `erosion = effective_rate × burn_time`
|
||||
5. Remaining thickness: `remaining = initial - erosion`
|
||||
|
||||
**Display:**
|
||||
- Pressure factor (if not 1.0)
|
||||
- Corrected erosion rate (inch/s)
|
||||
- Erosion depth (inch)
|
||||
- Remaining thickness (inch)
|
||||
- **Warning** if remaining < 0.5 inch
|
||||
|
||||
### Thermal Analysis (Future)
|
||||
|
||||
Currently, erosion is purely mechanical. Future versions could include:
|
||||
- Heat flux calculation
|
||||
- Material melting/sublimation
|
||||
- Thermal diffusion into structure
|
||||
- Combined mechanical + thermal erosion
|
||||
|
||||
---
|
||||
|
||||
## Structural Sizing
|
||||
|
||||
### Material Selection
|
||||
|
||||
Choose from STRUCTURAL_MATERIALS array:
|
||||
- **Aluminum 6061-T6**: Low density, corrosion-resistant
|
||||
- **Stainless Steel 304**: High temp, corrosion-resistant
|
||||
- **Inconel 718**: High strength at elevated T
|
||||
- **Titanium 6-4**: Light, strong, expensive
|
||||
- **CFRP (Carbon Fiber)**: Highest strength-to-weight
|
||||
|
||||
Each has: density (kg/m³), yield strength (MPa), Young's modulus, CTE, limits
|
||||
|
||||
### Hoop Stress Formula
|
||||
|
||||
For thin-walled cylinders:
|
||||
```
|
||||
σ_hoop = (P × r) / t
|
||||
```
|
||||
|
||||
Solving for wall thickness with safety factor:
|
||||
```
|
||||
t = (P × r) / (σ_yield / SF)
|
||||
```
|
||||
|
||||
Where:
|
||||
- `P` — internal pressure (Pa)
|
||||
- `r` — radius (m)
|
||||
- `σ_yield` — material yield strength (Pa)
|
||||
- `SF` — safety factor (typical: 2.0–4.0)
|
||||
|
||||
### Component Sizing
|
||||
|
||||
**Chamber:**
|
||||
- Pressure: P0 (combustion pressure)
|
||||
- Radius: determined by geometry
|
||||
- Thickness: `t_chamber = (P0 × r) / (σ_y / SF)`
|
||||
|
||||
**Convergent Section (nozzle entrance):**
|
||||
- Pressure: P0 (full chamber pressure)
|
||||
- Radius: smaller than chamber (converging)
|
||||
- Thickness: similar to chamber
|
||||
|
||||
**Throat (narrowest point):**
|
||||
- Pressure: ~P0 (highest local stress)
|
||||
- Radius: throat_radius (smallest)
|
||||
- **Result**: highest stress → thickest wall
|
||||
- Thickness: `t_throat = (P0 × r_throat) / (σ_y / SF)`
|
||||
|
||||
**Divergent Section (nozzle expansion):**
|
||||
- Pressure: decreases from P0 to Pe
|
||||
- Radius: increasing
|
||||
- Thickness: typically uses Pe ≈ 0.1·P0 for design
|
||||
- Lower thickness than chamber
|
||||
|
||||
**Exit (atmospheric nozzle):**
|
||||
- Pressure: near ambient
|
||||
- Thickness: minimal (can be thin-walled)
|
||||
|
||||
### Mass Calculation
|
||||
|
||||
**Cylindrical section:**
|
||||
```
|
||||
m = 2π·r·t·L·ρ
|
||||
```
|
||||
|
||||
**Hemispherical dome (for tanks):**
|
||||
```
|
||||
m = 4π·r²·t·ρ
|
||||
```
|
||||
|
||||
**Frustum (truncated cone):**
|
||||
```
|
||||
m ≈ π·(r1·L + r2·L)·t·ρ (simplified)
|
||||
```
|
||||
|
||||
**Total engine dry mass:**
|
||||
```
|
||||
m_dry = m_chamber + m_convergent + m_nozzle + m_injector_plate + m_misc
|
||||
```
|
||||
|
||||
### UI Layout
|
||||
|
||||
**Left Panel (Inputs):**
|
||||
- Material dropdown
|
||||
- Safety factor slider
|
||||
- Pressure specifications (chamber, ambient)
|
||||
|
||||
**Right Panel (Results):**
|
||||
- Wall thickness breakdown (chamber, throat, exit)
|
||||
- Mass breakdown (chamber, convergent, divergent, injector, **total**)
|
||||
- Material properties (yield, density, limit temp)
|
||||
- Stress utilization (if known)
|
||||
|
||||
---
|
||||
|
||||
## Workflow Example: Design LOX/RP1 Engine
|
||||
|
||||
### Step 1: Set Combustion Conditions
|
||||
1. Select `fuelType = RP1`
|
||||
2. Select `oxidiserType = LOX`
|
||||
3. Set `chamberPressure = 200 bar`
|
||||
4. Set `nozzleDiameter = 50 mm`
|
||||
5. Set `expansionRatio = 8`
|
||||
→ **Result**: Thrust ≈ 150 kN, Isp ≈ 310 s
|
||||
|
||||
### Step 2: Design Ablation
|
||||
1. Select `ablativeMaterial = PAXS`
|
||||
2. Set `initialLinertThickness = 10 mm`
|
||||
3. Set `burnTime = 60 s`
|
||||
→ **Result**: Erosion ≈ 1.5 mm, Remaining ≈ 8.5 mm (OK)
|
||||
|
||||
### Step 3: Size Structure
|
||||
1. Select `structuralMaterial = Inconel718`
|
||||
2. Set `safetyFactor = 3.0`
|
||||
→ **Result**:
|
||||
- Chamber wall: 2.1 mm
|
||||
- Throat wall: 2.8 mm
|
||||
- Divergent: 1.5 mm
|
||||
- **Total dry mass**: 2.3 kg
|
||||
|
||||
### Step 4: Export
|
||||
- **Export as JSON**: Download engine specs
|
||||
- Import into rocket design tool
|
||||
- Calculate vehicle TWR, delta-v, etc.
|
||||
|
||||
---
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Regenerative Cooling
|
||||
|
||||
Not yet implemented, but conceptually:
|
||||
- Propellant flows through cooling jackets before injection
|
||||
- Removes heat from chamber walls
|
||||
- Allows higher chamber pressure or thinner walls
|
||||
- Adds complexity (adds ~0.5 kg per engine)
|
||||
|
||||
Implementation would add:
|
||||
- Cooling jacket dimensions
|
||||
- Heat transfer correlation (Dittus-Boelert, etc.)
|
||||
- Pressure drop calculation
|
||||
- Temperature rise of propellant
|
||||
|
||||
### Ablator Recession Modeling
|
||||
|
||||
Current model assumes uniform erosion. Advanced model would include:
|
||||
- **Surface recession rate** (different from bulk erosion)
|
||||
- **Spallation** (chunks breaking off at high pressure)
|
||||
- **Chemical reaction** (oxidation, decomposition)
|
||||
- **Thermal gradient** (erosion depends on depth)
|
||||
|
||||
This requires:
|
||||
- Heat conduction equation (PDE)
|
||||
- Boundary conditions (heat flux from combustion)
|
||||
- Material properties (k, cp, melt point)
|
||||
- Solver (e.g., finite difference)
|
||||
|
||||
### Combustion Instability
|
||||
|
||||
Not modeled currently, but factors affecting it:
|
||||
- **Injector design** (pattern, element size, momentum ratio)
|
||||
- **Chamber L* (characteristic length)** = V / At
|
||||
- Higher L* = more residence time = higher c*
|
||||
- Typical range: 30–60 inches
|
||||
- **Baffle plates** (reduce acoustic resonance)
|
||||
|
||||
---
|
||||
|
||||
## Knowledgebase Integration
|
||||
|
||||
### Accessing Propellant Data
|
||||
- Knowledgebase → Fuels / Oxidisers
|
||||
- View all available propellants
|
||||
- Copy properties into engine design
|
||||
|
||||
### Accessing Material Data
|
||||
- Knowledgebase → Structural Materials
|
||||
- Compare yield strengths, densities, costs
|
||||
- Select best for your application
|
||||
|
||||
### Ablative Materials
|
||||
- Knowledgebase → Ablative Materials
|
||||
- View pressure exponents
|
||||
- Notes on applications (chamber, nozzle, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Chamber pressure seems too high / low?
|
||||
- Check propellant selection (wrong fuel/oxidizer?)
|
||||
- Verify chamber geometry (radius, length)
|
||||
- Check for typos in input values
|
||||
|
||||
### Erosion warning?
|
||||
- Select ablator with lower pressure exponent (more stable)
|
||||
- Reduce chamber pressure if possible
|
||||
- Increase initial liner thickness
|
||||
- Shorten burn time
|
||||
|
||||
### Structural mass too heavy?
|
||||
- Switch to lighter material (Ti-6-4 vs SS)
|
||||
- Reduce safety factor (if acceptable for design)
|
||||
- Increase chamber pressure radius (less stress)
|
||||
- Use thinner walls for non-critical sections
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- Huzel, D. K., & Huang, D. H. (1992). Modern engineering for design of liquid-propellant rocket engines. AIAA.
|
||||
- NASA SP-273: Liquid Rocket Engine Combustion Instability. ([PDF](https://ntrs.nasa.gov/api/citations/19700006920/downloads/19700006920.pdf))
|
||||
- Crespo, A., & Liñán, A. (1975). Asymptotic analysis of unsteady flame oscillations in liquid propellant rocket motors. SIAM Journal on Applied Mathematics, 29(3), 521–533.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-02 | **Status**: Current (v2 — Pressure-Corrected Ablation)
|
||||
465
docs/KNOWLEDGEBASE.md
Normal file
465
docs/KNOWLEDGEBASE.md
Normal file
@@ -0,0 +1,465 @@
|
||||
# Knowledgebase Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The **Knowledgebase** is a reference library of propellants, materials, and engineering equations. It provides the properties needed for calculations in the Solver, Engine Designer, and Rocket Designer.
|
||||
|
||||
## Structure
|
||||
|
||||
The knowledgebase is organized into four categories:
|
||||
|
||||
1. **Fuels & Oxidizers** — Propellant properties
|
||||
2. **Ablative Materials** — Thermal protection
|
||||
3. **Structural Materials** — Engine & tank construction
|
||||
4. **Equations** — Mathematical references
|
||||
|
||||
---
|
||||
|
||||
## Fuels & Oxidizers
|
||||
|
||||
### What are They?
|
||||
|
||||
**Fuel**: Hydrocarbon or hydrogen source
|
||||
- Examples: RP-1 (kerosene), methane, hydrogen
|
||||
|
||||
**Oxidizer**: Oxygen source
|
||||
- Examples: Liquid oxygen (LOX), nitrogen tetroxide (N2O4)
|
||||
|
||||
### Key Properties
|
||||
|
||||
Each propellant entry contains:
|
||||
|
||||
**Chemical Properties:**
|
||||
- Molecular formula (e.g., O₂ for oxygen)
|
||||
- Molecular weight (g/mol)
|
||||
- Density (kg/m³)
|
||||
|
||||
**Combustion Properties:**
|
||||
- **Adiabatic flame temperature (Tc)** — peak temperature of combustion (K)
|
||||
- Higher Tc = higher Isp
|
||||
- Example: LOX/RP-1 ≈ 3750 K, LOX/LH2 ≈ 3900 K
|
||||
|
||||
- **Expansion ratio (gamma, γ)** — specific heat ratio
|
||||
- γ = Cp / Cv
|
||||
- Affects nozzle performance
|
||||
- LOX/RP-1: γ ≈ 1.25, LOX/LH2: γ ≈ 1.26
|
||||
|
||||
- **Characteristic velocity (c*)** — ideal nozzle exit velocity
|
||||
- Fundamental property of propellant
|
||||
- Used to estimate Isp
|
||||
|
||||
**Performance Metrics:**
|
||||
- **Specific impulse (vacuum, Isp_vac)** — seconds
|
||||
- Higher = better
|
||||
- Example: LOX/RP-1 ≈ 310–320 s, LOX/LH2 ≈ 450 s
|
||||
|
||||
- **Specific impulse (sea level, Isp_sl)** — reduced due to ambient pressure
|
||||
- Lower than vacuum value
|
||||
- Example: LOX/RP-1 ≈ 260 s at sea level
|
||||
|
||||
**Mixture Ratio:**
|
||||
- **O/F ratio** — oxidizer mass per fuel mass
|
||||
- Example: LOX/RP-1 optimal ≈ 2.5–2.8
|
||||
- Higher ratio = more oxygen = higher T but lower mass fraction
|
||||
- Lower ratio = more fuel = lower T but better mass fraction
|
||||
|
||||
### Common Propellant Pairs
|
||||
|
||||
| Fuel | Oxidizer | Isp (s) | Tc (K) | γ | Notes |
|
||||
|------|----------|---------|-------|-------|-------|
|
||||
| RP-1 | LOX | 310 | 3750 | 1.25 | Space-proven, storable |
|
||||
| Methane | LOX | 330 | 3900 | 1.24 | Better impulse than RP-1 |
|
||||
| Hydrogen | LOX | 450 | 3900 | 1.26 | Best impulse, cryogenic, low density |
|
||||
| MMH | N2O4 | 290 | 3400 | 1.20 | Storable, hypergolic (ignites on contact) |
|
||||
| Hydrazine | N2O4 | 310 | 3700 | 1.24 | Toxic but storable, high density |
|
||||
|
||||
### Storage Types
|
||||
|
||||
**Cryogenic:**
|
||||
- Requires refrigeration
|
||||
- LOX, LH2, LN2, LCH4
|
||||
- Higher energy density
|
||||
- Complex ground support needed
|
||||
|
||||
**Storable (Room Temperature):**
|
||||
- RP-1, Methane (marginally), MMH, Hydrazine
|
||||
- No cryogenic handling needed
|
||||
- Lower energy density than cryo
|
||||
- Easier integration
|
||||
|
||||
**Hypergolic:**
|
||||
- Ignites spontaneously on contact (fuel + oxidizer)
|
||||
- No ignition system needed
|
||||
- Toxic, corrosive, more expensive
|
||||
- Examples: MMH/N2O4, Hydrazine/N2O4
|
||||
|
||||
### Selection Criteria
|
||||
|
||||
**High Performance** → LOX/LH2 (Isp 450 s, but cryogenic complexity)
|
||||
**Best Balance** → LOX/RP-1 (Isp 310 s, storable, proven)
|
||||
**Storable Only** → MMH/N2O4 (Isp 290 s, no cryo needed)
|
||||
**Simple & Solid** → RP-1/LOX or Methane/LOX
|
||||
|
||||
---
|
||||
|
||||
## Ablative Materials
|
||||
|
||||
### Purpose
|
||||
|
||||
Ablative materials line the rocket engine chamber to withstand:
|
||||
- **High temperature** (combustion products: 3500+ K)
|
||||
- **High pressure** (200+ bar)
|
||||
- **Erosion** from hot gas flow
|
||||
|
||||
### Key Properties
|
||||
|
||||
Each ablative material entry contains:
|
||||
|
||||
**Mechanical Properties:**
|
||||
- Density (kg/m³)
|
||||
- Tensile strength (MPa)
|
||||
- Compressive strength (MPa)
|
||||
|
||||
**Thermal Properties:**
|
||||
- Specific heat (J/kg·K)
|
||||
- Thermal conductivity (W/m·K)
|
||||
- Melting point (K)
|
||||
|
||||
**Erosion Properties:**
|
||||
- **Base erosion rate** (inch/s @ 300 psi reference pressure)
|
||||
- Ablative material mass removed per unit time
|
||||
- Higher rate = thicker liner needed
|
||||
- Example: PAXS ≈ 0.025 in/s
|
||||
|
||||
- **Pressure exponent (n)** — power-law sensitivity to pressure
|
||||
- `rate(P) = base_rate × (P / P_ref)^n`
|
||||
- Lower n = less pressure-sensitive (better for high P)
|
||||
- Example: PAXS n = 0.38, KFSI n = 0.35
|
||||
|
||||
**Application Notes:**
|
||||
- Where used: chamber, nozzle, injector
|
||||
- Temperature limits
|
||||
- Compatibility with propellants
|
||||
|
||||
### Material Classes
|
||||
|
||||
**Composites (Rigid):**
|
||||
- PAXS (polyester + glass) — n = 0.38
|
||||
- Common, cost-effective
|
||||
- Moderate erosion rate
|
||||
- Max temp ~2000 K
|
||||
|
||||
- KFSI (silica + phenolic) — n = 0.35
|
||||
- Better than PAXS
|
||||
- Lower erosion rate
|
||||
- Higher temp capability
|
||||
- More expensive
|
||||
|
||||
- Carbon-Phenolic — n = 0.32
|
||||
- Excellent thermal performance
|
||||
- Very low erosion rate
|
||||
- Very expensive
|
||||
- Used on high-end engines
|
||||
|
||||
**Elastomers (Flexible):**
|
||||
- ZIRCONIA (zirconia + silicone) — n = 0.48
|
||||
- Flexible (less brittle)
|
||||
- Higher erosion rate
|
||||
- Absorbs vibration
|
||||
- Lower cost than phenolics
|
||||
|
||||
- Butyl Rubber — n = 0.50
|
||||
- Very flexible
|
||||
- High erosion rate
|
||||
- Used for low-pressure applications
|
||||
|
||||
### Pressure Exponent Explanation
|
||||
|
||||
The power law `rate ∝ P^n` comes from **regression rate burning**:
|
||||
|
||||
- Composites: n ≈ 0.3–0.4
|
||||
- Erosion driven by thermal decomposition
|
||||
- Less pressure-dependent
|
||||
- Preferred for high-pressure engines
|
||||
|
||||
- Elastomers: n ≈ 0.4–0.5
|
||||
- Erosion driven by shear stress
|
||||
- More pressure-dependent
|
||||
- OK for moderate pressures
|
||||
|
||||
**High Pressure (>1000 psi):** Use composite with low n
|
||||
**Moderate Pressure (500 psi):** Elastomer acceptable
|
||||
**Low Pressure (<300 psi):** Elastomer preferred (lower cost)
|
||||
|
||||
### Selection Guidance
|
||||
|
||||
| Application | Material | Reason |
|
||||
|-------------|----------|--------|
|
||||
| High-perf liquid rocket | KFSI or Carbon-Phenolic | Low erosion rate, high pressure capable |
|
||||
| Medium-perf liquid | PAXS | Good balance, cost-effective |
|
||||
| Hybrid rocket | KFSI (fuel grain liner) | Low ablation to preserve geometry |
|
||||
| Solid rocket | Composite | Erosion from particles & hot gas |
|
||||
| Low-cost experiment | Butyl or PAXS | Adequate performance, lowest cost |
|
||||
|
||||
---
|
||||
|
||||
## Structural Materials
|
||||
|
||||
### Purpose
|
||||
|
||||
Structural materials form the engine chamber and rocket tanks. They must:
|
||||
- Withstand internal pressure (hoop stress)
|
||||
- Resist corrosion from propellants
|
||||
- Perform at operating temperature
|
||||
- Balance weight vs. strength
|
||||
|
||||
### Key Properties
|
||||
|
||||
Each structural material entry contains:
|
||||
|
||||
**Mechanical Properties:**
|
||||
- **Yield strength** (MPa) — stress at which permanent deformation begins
|
||||
- Higher = thinner walls possible = lighter
|
||||
- Example: Aluminum 6061-T6: 275 MPa, Inconel 718: 1240 MPa
|
||||
|
||||
- **Young's modulus** (GPa) — stiffness
|
||||
- Higher = less deflection (stronger)
|
||||
|
||||
- **Density** (kg/m³) — weight per volume
|
||||
- Lower = lighter vehicle
|
||||
- Example: Al: 2700, Ti: 4430, SS: 8000
|
||||
|
||||
**Thermal Properties:**
|
||||
- Melting point (K) — temperature limit
|
||||
- Coefficient of thermal expansion (CTE)
|
||||
- Thermal conductivity
|
||||
|
||||
**Other:**
|
||||
- Cost (relative)
|
||||
- Machinability
|
||||
- Availability
|
||||
|
||||
### Material Comparison
|
||||
|
||||
| Material | Density | Yield | T_melt | Cost | Best For |
|
||||
|----------|---------|-------|--------|------|----------|
|
||||
| Al 6061-T6 | 2700 | 275 | 933 | 1× | Prototype, pressure-fed |
|
||||
| SS 304 | 8000 | 215 | 1726 | 3× | Corrosion resistance |
|
||||
| Inconel 718 | 8190 | 1240 | 1600 | 10× | High-performance engines |
|
||||
| Ti-6-4 | 4430 | 880 | 1941 | 15× | Lightweight, space |
|
||||
| CFRP | 1600 | 600+ | 700 | 20× | Lowest weight |
|
||||
|
||||
### Hoop Stress Calculation
|
||||
|
||||
For cylindrical pressure vessels:
|
||||
```
|
||||
σ_hoop = (P × r) / t
|
||||
```
|
||||
|
||||
Setting equal to yield with safety factor:
|
||||
```
|
||||
t = (P × r) / (σ_yield / SF)
|
||||
```
|
||||
|
||||
Higher yield strength → thinner walls → lighter mass
|
||||
|
||||
### Material Selection
|
||||
|
||||
**Pressure-Fed Engine (200+ bar, chamber):**
|
||||
- **Inconel 718** — withstands high pressure & heat
|
||||
- **Titanium** — lighter alternative
|
||||
- **Aluminum** — cheap but needs cooling design
|
||||
|
||||
**Rocket Tanks (20–50 bar):**
|
||||
- **Aluminum 6061** — standard, proven, affordable
|
||||
- **Titanium** — if weight critical
|
||||
- **CFRP** — lowest weight, highest cost
|
||||
|
||||
**Low-Pressure Systems:**
|
||||
- **Aluminum** — sufficient, cheapest
|
||||
- **Stainless Steel** — if corrosion concern
|
||||
|
||||
---
|
||||
|
||||
## Equations Reference
|
||||
|
||||
### Fundamental Relations
|
||||
|
||||
**Thrust (momentum equation):**
|
||||
```
|
||||
F = ṁ · Ve + (Pe - Pa) · Ae
|
||||
```
|
||||
- ṁ = mass flow rate
|
||||
- Ve = exit velocity
|
||||
- Pe = exit pressure
|
||||
- Pa = ambient pressure
|
||||
- Ae = exit area
|
||||
|
||||
**Specific Impulse:**
|
||||
```
|
||||
Isp = Ve / g0 (vacuum)
|
||||
Isp = (Ve - (Pe - Pa) / ṁ · Ae) / g0 (sea level)
|
||||
```
|
||||
- g0 = 9.81 m/s² (gravitational acceleration)
|
||||
|
||||
**Rocket Equation (Tsiolkovsky):**
|
||||
```
|
||||
ΔV = Isp · g0 · ln(m_initial / m_final)
|
||||
```
|
||||
- ΔV = velocity change (delta-v)
|
||||
- m_initial = wet mass
|
||||
- m_final = dry mass
|
||||
|
||||
### Isentropic Flow (Nozzle Design)
|
||||
|
||||
**Temperature at exit:**
|
||||
```
|
||||
Te / T0 = (Pe / P0)^((γ-1)/γ)
|
||||
```
|
||||
|
||||
**Density at exit:**
|
||||
```
|
||||
ρe / ρ0 = (Pe / P0)^(1/γ)
|
||||
```
|
||||
|
||||
**Mach number from area ratio:**
|
||||
```
|
||||
A / A* = (1/M) · [(2/(γ+1)) · (1 + (γ-1)/2 · M²)]^((γ+1)/(2(γ-1)))
|
||||
```
|
||||
- A* = throat area
|
||||
- A = arbitrary section area
|
||||
- M = Mach number
|
||||
- (requires numerical inversion via bisection)
|
||||
|
||||
**Characteristic velocity:**
|
||||
```
|
||||
c* = √[2 · (γ+1)/(γ-1) · R · T0 · (2/(γ+1))^((γ+1)/(γ-1))]
|
||||
```
|
||||
|
||||
### Thrust Coefficient
|
||||
|
||||
```
|
||||
CF = √[2γ²/(γ-1) · (2/(γ+1))^((γ+1)/(γ-1)) · (1 - (Pe/P0)^((γ-1)/γ))]
|
||||
+ (Pe - Pa)/(P0) · (Ae/At)
|
||||
```
|
||||
|
||||
### Chamber Thermodynamics
|
||||
|
||||
**Energy balance (no losses):**
|
||||
```
|
||||
Cp · (T0 - Te) = Ve² / 2
|
||||
```
|
||||
- Cp = specific heat at constant pressure
|
||||
|
||||
**Chemical equilibrium:**
|
||||
Determine T0, γ from propellant properties and stoichiometry
|
||||
(computed via NASA CEA code or thermodynamic tables)
|
||||
|
||||
### Drag & Atmosphere
|
||||
|
||||
**Drag force:**
|
||||
```
|
||||
Fd = 0.5 · ρ · v² · Cd · A
|
||||
```
|
||||
- ρ = air density (depends on altitude)
|
||||
- v = velocity
|
||||
- Cd = drag coefficient (~0.25 for rockets)
|
||||
- A = reference area
|
||||
|
||||
**US Standard Atmosphere (piecewise):**
|
||||
```
|
||||
T(h) = T0 - L·h (troposphere, 0–11 km)
|
||||
P(h) = P0 · (T(h)/T0)^(-g/(R·L))
|
||||
ρ(h) = ρ0 · (T(h)/T0)^(-(g/(R·L) + 1))
|
||||
```
|
||||
- L = lapse rate ≈ 6.5 K/km
|
||||
- R = gas constant
|
||||
|
||||
### Hoop Stress (Pressure Vessels)
|
||||
|
||||
**Thin-walled cylinder:**
|
||||
```
|
||||
σ_hoop = P·r / t
|
||||
```
|
||||
With safety factor:
|
||||
```
|
||||
t = P·r / (σ_yield / SF)
|
||||
```
|
||||
Mass:
|
||||
```
|
||||
m = 2π · r · t · L · ρ (cylinder)
|
||||
m = 4π · r² · t · ρ (hemispherical dome)
|
||||
```
|
||||
|
||||
### Mass Fraction
|
||||
|
||||
**Payload fraction:**
|
||||
```
|
||||
fp = m_payload / m_wet
|
||||
```
|
||||
|
||||
**Structure fraction:**
|
||||
```
|
||||
fs = m_structure / m_wet
|
||||
```
|
||||
|
||||
**Propellant fraction:**
|
||||
```
|
||||
fp = m_propellant / m_wet
|
||||
```
|
||||
|
||||
Sum: `fp + fs + fpayload = 1`
|
||||
|
||||
Typical rockets: `fs = 0.10–0.20` (10–20%)
|
||||
|
||||
---
|
||||
|
||||
## Using Knowledgebase in Design
|
||||
|
||||
### Importing Propellant Properties
|
||||
|
||||
1. **Solver**: Drag `chamberTemperature`, `expansionGamma` onto workspace
|
||||
2. Check knowledgebase for propellant pair (LOX + RP-1)
|
||||
3. Enter T0 from knowledgebase → solver computes Isp
|
||||
4. Verify with reference Isp in database
|
||||
|
||||
### Cross-Checking Ablation
|
||||
|
||||
1. **Engine Design**: Select PAXS ablative
|
||||
2. **Check Pressure Exponent**: 0.38 (from knowledgebase)
|
||||
3. Verify erosion rate correction is applied
|
||||
4. Compare remaining thickness to safety margin (>0.5 inch)
|
||||
|
||||
### Material Trade-Studies
|
||||
|
||||
1. **Rocket Design**: Compare materials
|
||||
- Aluminum: 1000 kg tanks
|
||||
- Titanium: 600 kg tanks (lighter, more expensive)
|
||||
- CFRP: 350 kg tanks (lightest, most expensive)
|
||||
2. Use mass to compute TWR, delta-v
|
||||
3. Pick best balance for mission
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- **User contributions**: Allow adding new materials/propellants
|
||||
- **Temperature corrections**: Adjust properties with temperature
|
||||
- **Material compatibility**: Show fuel/material interactions
|
||||
- **Cost database**: Include material & propellant costs
|
||||
- **References**: Link to papers & technical data sources
|
||||
- **Lookup plots**: Interactive charts (Isp vs. O/F, etc.)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NASA SP-273: Liquid Rocket Engine Combustion Instability.
|
||||
- Huzel, D. K., & Huang, D. H. (1992). Modern engineering for design of liquid-propellant rocket engines. AIAA.
|
||||
- Rocket Propulsion Elements (8th ed.). Sutton & Biblarz.
|
||||
- US Standard Atmosphere 1976. NASA TM-X-74335.
|
||||
- CEA (Chemical Equilibrium with Applications). NASA Glenn Research Center.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-02 | **Status**: Current
|
||||
243
docs/QUICKSTART.md
Normal file
243
docs/QUICKSTART.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Quick Start Guide
|
||||
|
||||
Get up and running with RocketTools in 5 minutes.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open **http://localhost:5173** in your browser.
|
||||
|
||||
---
|
||||
|
||||
## Your First Rocket Design (10 minutes)
|
||||
|
||||
### Step 1: Design an Engine (3 min)
|
||||
|
||||
1. Click **Design → Engine**
|
||||
2. Select propellants:
|
||||
- Fuel: **RP-1**
|
||||
- Oxidizer: **LOX**
|
||||
3. Set chamber pressure: **200 bar**
|
||||
4. Set nozzle diameter: **50 mm**
|
||||
5. Set expansion ratio: **8**
|
||||
6. **→ Results**: Thrust ~150 kN, Isp ~310 s, burn time 60 s
|
||||
7. **Export as JSON** (save to file)
|
||||
|
||||
### Step 2: Design a Rocket (4 min)
|
||||
|
||||
1. Click **Design → Rocket**
|
||||
2. **Import engine JSON** (from step 1)
|
||||
3. Set tank configuration: **Tandem**
|
||||
4. Set outer radius: **1.0 m**
|
||||
5. Set propellant volume: **5000 L**
|
||||
6. Set payload: **50 kg**
|
||||
7. **→ Results**: Wet mass 1550 kg, dry mass 450 kg, TWR 10
|
||||
8. Adjust nose cone shape: **Von Kármán** (optimal)
|
||||
9. **Export as JSON** (save to file)
|
||||
|
||||
### Step 3: Simulate Flight (3 min)
|
||||
|
||||
1. Click **Design → Trajectory**
|
||||
2. **Import rocket JSON** (from step 2)
|
||||
3. **Import engine JSON** (from step 1)
|
||||
4. Set pitch start altitude: **1000 m**
|
||||
5. **Run Simulation**
|
||||
6. **Watch the animation** (click Play button)
|
||||
7. **Results**: ~5000 m downrange, 50 km apogee
|
||||
|
||||
---
|
||||
|
||||
## Key Pages Overview
|
||||
|
||||
### 🧮 Solver
|
||||
Automatically solve rocket equations.
|
||||
- Drag variables onto workspace
|
||||
- Set constraints
|
||||
- Solver computes unknowns
|
||||
|
||||
**Try this**: Set `thrust = 100000 N`, `massFlowRate = 100 kg/s`
|
||||
→ Solver computes `exitVelocity = 1000 m/s`
|
||||
|
||||
### 🔥 Engine Design
|
||||
Calculate combustion, erosion, and structure.
|
||||
- Propellant selection
|
||||
- Chamber pressure & nozzle geometry
|
||||
- Ablative erosion prediction
|
||||
- Wall thickness & mass
|
||||
|
||||
**Try this**: Increase chamber pressure from 200 → 500 bar
|
||||
→ See thrust increase, wall thickness increase, mass increase
|
||||
|
||||
### 🚀 Rocket Design
|
||||
Vehicle geometry and mass budget.
|
||||
- Tank configuration (tandem/coaxial)
|
||||
- Tank structure (hoop stress)
|
||||
- Nose cone shapes
|
||||
- Complete mass budget
|
||||
- 3D visualization
|
||||
|
||||
**Try this**: Switch nose cone from Conical → Von Kármán
|
||||
→ 3D model updates in real time
|
||||
|
||||
### 📈 Trajectory Simulation
|
||||
Flight path prediction.
|
||||
- RK4 physics integrator
|
||||
- Atmosphere model (US Standard)
|
||||
- Event detection (liftoff, apogee, landing)
|
||||
- Playback controls
|
||||
|
||||
**Try this**: Run simulation, then scrub timeline to different times
|
||||
→ See position, velocity, altitude change
|
||||
|
||||
### 📚 Knowledgebase
|
||||
Material & equation references.
|
||||
- **Fuels / Oxidizers** — propellant properties
|
||||
- **Ablative Materials** — thermal protection specs
|
||||
- **Equations** — physics reference
|
||||
- **Structural Materials** — metal/composite properties
|
||||
|
||||
**Try this**: Look up LOX properties
|
||||
→ Temperature: 3750 K, Isp: 310 s
|
||||
|
||||
---
|
||||
|
||||
## Tips & Tricks
|
||||
|
||||
### Save Your Work
|
||||
- Engine JSON → use for multiple rocket designs
|
||||
- Rocket JSON → use for trajectory simulations
|
||||
- Keep both files for reference
|
||||
|
||||
### Quick Iterations
|
||||
1. Modify one parameter (e.g., chamber pressure)
|
||||
2. Solver/simulator automatically updates
|
||||
3. Check results
|
||||
4. Adjust again
|
||||
|
||||
### Understanding Mass
|
||||
- **Wet mass** = total (with fuel)
|
||||
- **Dry mass** = structure + engine + payload (no fuel)
|
||||
- **Propellant mass** = wet − dry
|
||||
- **TWR** = thrust / weight
|
||||
- > 5 is good for vertical launch
|
||||
- < 2 struggles to lift off
|
||||
|
||||
### Understanding Isp
|
||||
- **Higher Isp = more efficient** (goes farther on same fuel)
|
||||
- Vacuum Isp > Sea-level Isp (less atmospheric pressure at altitude)
|
||||
- LOX/RP-1: ~310 s (workhorse)
|
||||
- LOX/H2: ~450 s (high-perf, but cryogenic)
|
||||
- MMH/N2O4: ~290 s (storable, easier operations)
|
||||
|
||||
### Flight Path Basics
|
||||
- Vehicle accelerates straight up (vertical hold)
|
||||
- At ~1 km altitude, starts gravity turn (follows velocity)
|
||||
- Thrust ends at ~60 s (Main Engine Cutoff)
|
||||
- Coasts up to apogee (~50 km in example)
|
||||
- Falls back down (lands ~5 km downrange)
|
||||
|
||||
---
|
||||
|
||||
## Common Questions
|
||||
|
||||
**Q: How do I get higher apogee?**
|
||||
- Increase fuel volume (larger tank)
|
||||
- Reduce payload mass
|
||||
- Higher Isp propellant (LOX/H2)
|
||||
- More efficient rocket (lighter structure)
|
||||
|
||||
**Q: Why is my rocket too heavy?**
|
||||
- Reduce tank radius (but check volume)
|
||||
- Use stronger material (Al → Ti → CFRP)
|
||||
- Lower safety factor (use 2.0 instead of 3.0)
|
||||
- Reduce payload
|
||||
|
||||
**Q: Can I design multiple stages?**
|
||||
- Not yet — current version is single-stage only
|
||||
- Workaround: design each stage separately, estimate staging losses manually
|
||||
|
||||
**Q: How accurate are the simulations?**
|
||||
- ±5–10% for well-designed vehicles
|
||||
- Assumes no wind, perfect injection
|
||||
- Doesn't include control/guidance errors
|
||||
- Good for feasibility analysis, not flight prediction
|
||||
|
||||
**Q: Can I export to CAD?**
|
||||
- Not yet — export rocket JSON for external processing
|
||||
- 3D model data available in code (tank dimensions, nose cone profile)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
❌ **Too small tank**
|
||||
- 5000 L seems big but isn't for LOX/RP-1 rockets
|
||||
- Try 10,000+ L for real vehicle
|
||||
|
||||
❌ **Forgot engine burn time**
|
||||
- Check engine design was properly simulated
|
||||
- Engine JSON must include burn time
|
||||
|
||||
❌ **Wrong reference area for drag**
|
||||
- Use actual cross-sectional area (πR²)
|
||||
- Not wetted surface or planform area
|
||||
|
||||
❌ **Unrealistic safety factor**
|
||||
- 2.0–3.0 is typical for engines
|
||||
- < 1.5 is dangerous, > 5.0 is wasteful
|
||||
|
||||
❌ **Ignoring pressurant mass**
|
||||
- Pressure-fed system helium adds ~100 kg
|
||||
- Consider pump-fed for heavier vehicles
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Explore knowledgebase** — understand propellants & materials
|
||||
2. **Read equations** — understand the physics
|
||||
3. **Design variants** — try different tank sizes, materials
|
||||
4. **Optimize** — see what makes vehicle lighter/faster
|
||||
5. **Contribute** — add new equations or materials
|
||||
|
||||
---
|
||||
|
||||
## Learning Resources
|
||||
|
||||
- [Rocket Propulsion Elements](https://www.amazon.com/Rocket-Propulsion-Elements-Sutton-Biblarz/dp/0470080728) — textbook
|
||||
- [NASA SP-273: Combustion Instability](https://ntrs.nasa.gov) — free PDF
|
||||
- [Everyday Astronaut](https://www.youtube.com/c/EverydayAstronaut) — video explanations
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Nothing shows up | Refresh browser (Ctrl+F5) |
|
||||
| Numbers look wrong | Check input units (bar vs MPa, mm vs m) |
|
||||
| 3D model doesn't render | WebGL must be enabled in browser |
|
||||
| Solver stuck | Ensure enough constraints set for system |
|
||||
| Simulation runs forever | Reduce timestep or check inputs for infinity |
|
||||
|
||||
---
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| **Space** | Play/pause trajectory |
|
||||
| **→** | Jump forward 10 seconds |
|
||||
| **←** | Jump backward 10 seconds |
|
||||
| **Home** | Jump to start |
|
||||
| **End** | Jump to end |
|
||||
|
||||
---
|
||||
|
||||
**Happy rocket designing! 🚀**
|
||||
|
||||
Next, dive into [SOLVER.md](SOLVER.md) to master the equation solver.
|
||||
509
docs/ROCKET_DESIGN.md
Normal file
509
docs/ROCKET_DESIGN.md
Normal file
@@ -0,0 +1,509 @@
|
||||
# Rocket Design Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The **Rocket Design** tool calculates vehicle mass budget, tank geometry, structural requirements, and generates 3D models. It integrates engine data from the engine designer and computes the complete rocket's performance characteristics.
|
||||
|
||||
## Main Sections
|
||||
|
||||
### Vehicle Geometry
|
||||
Define tank configuration, dimensions, and structural layout.
|
||||
|
||||
### Tank Structure
|
||||
Calculate wall thicknesses, masses, and pressurant requirements.
|
||||
|
||||
### Nose Cone Design
|
||||
Select and visualize nose cone shapes (conical, ogive, Von Kármán).
|
||||
|
||||
### Mass Budget
|
||||
Integrate all components (engines, tanks, payload, structure) to compute total mass and performance metrics.
|
||||
|
||||
### 3D Visualization
|
||||
Interactive three.js model showing tanks, nose cone, and flight orientation.
|
||||
|
||||
---
|
||||
|
||||
## Vehicle Geometry
|
||||
|
||||
### Tank Configuration Options
|
||||
|
||||
**Tandem (Sequential):**
|
||||
- Two cylindrical tanks stacked vertically
|
||||
- Fuel (lower), Oxidizer (upper)
|
||||
- Domes: hemispherical on both ends
|
||||
- **Advantage**: Compact, simpler plumbing
|
||||
- **Disadvantage**: Longer vehicle
|
||||
|
||||
**Coaxial (Concentric):**
|
||||
- Outer tank (fuel) surrounds inner tank (oxidizer)
|
||||
- Reduces diameter
|
||||
- Inner tank: flat bulkheads (simpler)
|
||||
- **Advantage**: Compact, low diameter
|
||||
- **Disadvantage**: More complex, thermal management
|
||||
|
||||
**Single Tank:**
|
||||
- One tank with both propellants mixed
|
||||
- Rarely used for high-performance (lower Isp)
|
||||
|
||||
### Tank Dimensions
|
||||
|
||||
**Inputs:**
|
||||
- `outerRadius` (mm) — outer tank radius
|
||||
- `propellantVolume` (L) — total propellant quantity
|
||||
- `tankConfiguration` — tandem, coaxial, single
|
||||
- `ullagePercent` (%) — pressurant volume as % of propellant
|
||||
|
||||
**Key Relationship:**
|
||||
```
|
||||
Ullage volume = propellant volume × (ullage% / 100)
|
||||
Effective volume = propellant volume × (1 + ullage%)
|
||||
```
|
||||
|
||||
Ullage accommodates:
|
||||
- Thermal expansion of propellant
|
||||
- Gas bubble for pump inlet
|
||||
- Margin for fill level uncertainty
|
||||
|
||||
### Tank Geometry (Tandem Case)
|
||||
|
||||
**Dome Volume (hemispherical):**
|
||||
```
|
||||
V_dome = (2/3) × π × R³ (one hemisphere)
|
||||
V_domes = (4/3) × π × R³ (both domes)
|
||||
```
|
||||
|
||||
**Cylindrical Section:**
|
||||
```
|
||||
L_cyl = (V_eff - V_domes) / (π × R²)
|
||||
```
|
||||
|
||||
**Total Tank Length:**
|
||||
```
|
||||
L_total = L_cyl + 2R (two dome heights)
|
||||
```
|
||||
|
||||
**Example:**
|
||||
- R = 1.5 m, V_prop = 5000 L, ullage = 10%
|
||||
- V_eff = 5000 × 1.1 = 5500 L
|
||||
- V_domes = 4/3 × π × 1.5³ ≈ 14.1 m³ = 14100 L (larger than prop!)
|
||||
- Need smaller R or accept small L_cyl
|
||||
|
||||
**Note**: For smaller rockets, domes dominate volume. Design must account for this.
|
||||
|
||||
---
|
||||
|
||||
## Tank Structure
|
||||
|
||||
### Pressure Sources
|
||||
|
||||
**Pressure-Fed System:**
|
||||
```
|
||||
P_tank = 1.2 × P0_chamber (pressure margin)
|
||||
```
|
||||
Typical: P0 = 200 bar → P_tank = 240 bar
|
||||
|
||||
**Pump-Fed System:**
|
||||
```
|
||||
P_tank = 2 MPa (minimum for turbopump inlet)
|
||||
```
|
||||
Much lower pressure (pump provides most acceleration)
|
||||
|
||||
**Selection affects:**
|
||||
- Wall thicknesses (direct proportionality)
|
||||
- Mass (linear with pressure and wall thickness)
|
||||
- Propellant pump requirements
|
||||
|
||||
### Structural Material Properties
|
||||
|
||||
Available materials from knowledgebase:
|
||||
- **Aluminum 6061-T6**: density 2700 kg/m³, σ_y = 275 MPa
|
||||
- **Stainless Steel 304**: density 8000 kg/m³, σ_y = 215 MPa
|
||||
- **Inconel 718**: density 8190 kg/m³, σ_y = 1240 MPa
|
||||
- **Titanium 6-4**: density 4430 kg/m³, σ_y = 880 MPa
|
||||
- **CFRP (Carbon Fiber)**: density 1600 kg/m³, σ_y = 600 MPa
|
||||
|
||||
**Selection factors:**
|
||||
- Cost (Al < SS < Ti < CFRP)
|
||||
- Weight (CFRP < Ti < Al < SS)
|
||||
- Corrosion (SS, Ti, CFRP better; Al needs coating)
|
||||
- Temperature (Inconel for hot engines; others at T < 150°C)
|
||||
|
||||
### Wall Thickness (Hoop Stress)
|
||||
|
||||
**Hoop stress formula:**
|
||||
```
|
||||
σ_hoop = (P × R) / t
|
||||
```
|
||||
|
||||
**With safety factor:**
|
||||
```
|
||||
t = (P × R) / (σ_yield / SF)
|
||||
```
|
||||
|
||||
**Cylindrical section mass:**
|
||||
```
|
||||
m_cyl = 2π × R × t × L_cyl × ρ_material
|
||||
```
|
||||
|
||||
**Dome mass (two hemispheres):**
|
||||
```
|
||||
m_domes = 4π × R² × t × ρ_material
|
||||
```
|
||||
|
||||
**Total tank mass:**
|
||||
```
|
||||
m_tank = m_cyl + m_domes
|
||||
```
|
||||
|
||||
### Example Calculation
|
||||
|
||||
**Tandem LOX/RP1 Tank:**
|
||||
- Radius: 1.0 m
|
||||
- Pressure: 240 bar = 24 MPa
|
||||
- Material: Aluminum 6061-T6
|
||||
- σ_y = 275 MPa
|
||||
- ρ = 2700 kg/m³
|
||||
- Safety Factor: 2.5
|
||||
|
||||
**Wall Thickness:**
|
||||
```
|
||||
t = (24 MPa × 1.0 m) / (275 MPa / 2.5)
|
||||
= 24 / 110
|
||||
≈ 0.218 m = 2.18 mm
|
||||
```
|
||||
|
||||
**Cylindrical Section (assume L_cyl = 3 m):**
|
||||
```
|
||||
m_cyl = 2π × 1.0 × 0.00218 × 3.0 × 2700
|
||||
≈ 110 kg
|
||||
```
|
||||
|
||||
**Domes:**
|
||||
```
|
||||
m_domes = 4π × 1.0² × 0.00218 × 2700
|
||||
≈ 74 kg
|
||||
```
|
||||
|
||||
**Total tank mass:** ~184 kg
|
||||
|
||||
---
|
||||
|
||||
## Pressurant System (Pressure-Fed Only)
|
||||
|
||||
### Helium Requirements
|
||||
|
||||
For pressure-fed engines, pressurant gas maintains tank pressure throughout burn.
|
||||
|
||||
**Ideal gas law:**
|
||||
```
|
||||
P × V = n × R × T
|
||||
```
|
||||
|
||||
**Helium mass:**
|
||||
```
|
||||
m_He = (P_tank × V_prop) / (R_He × T)
|
||||
```
|
||||
|
||||
Where:
|
||||
- `P_tank` — tank pressure (Pa)
|
||||
- `V_prop` — propellant volume (m³)
|
||||
- `R_He` — helium specific gas constant = 2077 J/kg/K
|
||||
- `T` — temperature (K), typically 293 K (20°C)
|
||||
|
||||
**Example:**
|
||||
- P_tank = 24 MPa = 24×10⁶ Pa
|
||||
- V_prop = 5 m³
|
||||
- T = 293 K
|
||||
|
||||
```
|
||||
m_He = (24×10⁶ × 5) / (2077 × 293)
|
||||
≈ 20 kg
|
||||
```
|
||||
|
||||
### Helium Bottle Mass
|
||||
|
||||
Helium stored in high-pressure bottle. Typical storage pressure: 250 bar.
|
||||
|
||||
**Bottle mass (conservative):**
|
||||
```
|
||||
m_bottle = 4 × m_He
|
||||
```
|
||||
|
||||
Rule of thumb: bottle is 4 times the helium mass. (More sophisticated: use MEOP analysis.)
|
||||
|
||||
**Total pressurant system:**
|
||||
```
|
||||
m_pressurant = m_He + m_bottle
|
||||
```
|
||||
|
||||
Example: 20 kg He → 80 kg bottle → 100 kg pressurant system
|
||||
|
||||
**Note**: This is a major mass penalty for pressure-fed systems. Pump-fed systems avoid this.
|
||||
|
||||
---
|
||||
|
||||
## Nose Cone Design
|
||||
|
||||
### Available Profiles
|
||||
|
||||
Three aerodynamic nose cone shapes, all with L = 2 × R (length = 2 × base radius).
|
||||
|
||||
**Conical:**
|
||||
- Simple linear profile
|
||||
- `r(x) = R × (x / L)`
|
||||
- Sharpest tip, moderate drag
|
||||
|
||||
**Tangent Ogive:**
|
||||
- Smooth circular arc meeting base tangentially
|
||||
- `ρ = (R² + L²) / (2R)` (radius of curvature)
|
||||
- `r(x) = √(ρ² - (L - x)²) - (ρ - R)`
|
||||
- Smooth, less drag than conical
|
||||
- Common in rocketry
|
||||
|
||||
**Von Kármán:**
|
||||
- Power law profile minimizing drag
|
||||
- `θ = acos(1 - 2x/L)`
|
||||
- `r(x) = (R / √π) × √(θ - sin(2θ)/2)`
|
||||
- Theoretically optimal for transonic flight
|
||||
- Used on high-performance rockets
|
||||
|
||||
**Selection Criteria:**
|
||||
- **Conical**: Simplest to manufacture, sharp tip
|
||||
- **Tangent Ogive**: Better aerodynamics, smoother base transition
|
||||
- **Von Kármán**: Best drag coefficient (Cd ≈ 0.15 vs 0.25 conical)
|
||||
|
||||
### 3D Visualization
|
||||
|
||||
Nose cone is rendered using THREE.js `LatheGeometry`:
|
||||
- Profile points sampled from mathematical formula
|
||||
- Rotated around vertical axis to create 3D shape
|
||||
- Interactive rotation/zoom in 3D viewer
|
||||
|
||||
---
|
||||
|
||||
## Mass Budget
|
||||
|
||||
### Components
|
||||
|
||||
**Structure:**
|
||||
- Tank walls and domes: `m_tanks`
|
||||
- Other structure (nosecone, bay, interstage): `m_other`
|
||||
- Engine dry mass (from engine designer): `m_engine`
|
||||
|
||||
**Propellant:**
|
||||
- Fuel + oxidizer: `m_propellant`
|
||||
|
||||
**Pressurant (pressure-fed only):**
|
||||
- Helium + bottle: `m_pressurant`
|
||||
|
||||
**Payload:**
|
||||
- Avionics, recovery system, instruments: `m_payload`
|
||||
|
||||
### Calculation
|
||||
|
||||
**Dry mass (no propellant):**
|
||||
```
|
||||
m_dry = m_tanks + m_other + m_engine + m_pressurant + m_payload
|
||||
```
|
||||
|
||||
**Wet mass (with propellant):**
|
||||
```
|
||||
m_wet = m_dry + m_propellant
|
||||
```
|
||||
|
||||
**Payload fraction:**
|
||||
```
|
||||
fraction_payload = m_payload / m_wet
|
||||
```
|
||||
|
||||
**Structure fraction:**
|
||||
```
|
||||
fraction_structure = m_tanks / m_wet
|
||||
```
|
||||
|
||||
**Thrust-to-weight ratio:**
|
||||
```
|
||||
TWR = F_thrust / (m_wet × g)
|
||||
```
|
||||
|
||||
### Example Mass Budget
|
||||
|
||||
Small LOX/RP1 rocket:
|
||||
|
||||
| Component | Mass (kg) | % |
|
||||
|-----------|-----------|-----|
|
||||
| Tanks (structure) | 200 | 14% |
|
||||
| Engine | 50 | 3.5% |
|
||||
| Pressurant (He + bottle) | 100 | 7% |
|
||||
| Avionics + recovery | 30 | 2% |
|
||||
| **Dry mass** | **380** | **26.5%** |
|
||||
| Propellant (LOX + RP1) | 1050 | 73.5% |
|
||||
| **Wet mass** | **1430** | **100%** |
|
||||
|
||||
**Performance:**
|
||||
- TWR = 150 kN / (1430 kg × 9.81 m/s²) = 10.7
|
||||
- Delta-v (no gravity loss): 310 s × ln(1430/380) ≈ 1300 m/s
|
||||
|
||||
---
|
||||
|
||||
## 3D Model Components
|
||||
|
||||
### Tank Rendering
|
||||
|
||||
**Cylindrical body:**
|
||||
```javascript
|
||||
<TankSection
|
||||
radius={1.0}
|
||||
length={3.0}
|
||||
position={[0, 0, 0]}
|
||||
/>
|
||||
```
|
||||
|
||||
Renders:
|
||||
- Cylinder: `CylinderGeometry`
|
||||
- Top dome: `SphereGeometry` (hemisphere)
|
||||
- Bottom dome: `SphereGeometry` (hemisphere)
|
||||
|
||||
**Material:** MeshStandardMaterial with color (red = fuel, blue = oxidizer)
|
||||
|
||||
### Nose Cone Rendering
|
||||
|
||||
**LatheGeometry:**
|
||||
- Takes profile curve (array of points)
|
||||
- Rotates around Y-axis to create 3D surface
|
||||
- Smooth, aerodynamic appearance
|
||||
|
||||
**Example:**
|
||||
```javascript
|
||||
const profile = noseConeProfile('tangent-ogive', 0.5, 1.0, 24)
|
||||
const geometry = new THREE.LatheGeometry(profile, 24)
|
||||
```
|
||||
|
||||
### Scene Setup
|
||||
|
||||
**Lighting:**
|
||||
- Ambient light (0.6 intensity)
|
||||
- Directional light from top-right
|
||||
- Shadows enabled for depth
|
||||
|
||||
**Camera:**
|
||||
- Orbit controls (rotate, zoom, pan)
|
||||
- Auto-fit to model bounds
|
||||
- Perspective view (60° FOV)
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Design Complete Vehicle
|
||||
|
||||
### Step 1: Import Engine
|
||||
1. Go to **Design > Engine**
|
||||
2. Configure combustion (LOX/RP1, 200 bar, etc.)
|
||||
3. Size structure (Inconel, 3.0 SF)
|
||||
4. Export as JSON
|
||||
5. Return to **Design > Rocket**
|
||||
6. Upload engine JSON
|
||||
→ **Result**: Engine dry mass auto-populated
|
||||
|
||||
### Step 2: Configure Tanks
|
||||
1. Set tank configuration: **Tandem**
|
||||
2. Set outer radius: **1.0 m**
|
||||
3. Set propellant volume: **5000 L**
|
||||
4. Set ullage: **10%**
|
||||
→ **Result**: Calculated tank length, dome geometry
|
||||
|
||||
### Step 3: Design Tank Structure
|
||||
1. Select material: **Aluminum 6061-T6**
|
||||
2. Set safety factor: **2.5**
|
||||
3. Select feed system: **Pressure-Fed**
|
||||
→ **Result**: Wall thickness, tank mass, pressurant requirements
|
||||
|
||||
### Step 4: Set Payload
|
||||
1. Enter payload mass: **50 kg** (avionics, recovery)
|
||||
→ **Result**: Dry mass updated
|
||||
|
||||
### Step 5: View Mass Budget
|
||||
→ **Result**:
|
||||
- Wet mass: 1550 kg
|
||||
- Dry mass: 450 kg
|
||||
- TWR: 10.2
|
||||
- Delta-v (vacuum): 1320 m/s
|
||||
|
||||
### Step 6: Adjust Nose Cone
|
||||
1. Select shape: **Von Kármán**
|
||||
→ **Result**: 3D model updates with optimal nose cone
|
||||
|
||||
### Step 7: Export & Simulate
|
||||
1. Export vehicle JSON
|
||||
2. Go to **Design > Trajectory**
|
||||
3. Import vehicle & engine data
|
||||
4. Run flight simulation
|
||||
→ **Result**: Altitude, downrange, apogee, landing site
|
||||
|
||||
---
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Multi-Stage Rockets
|
||||
|
||||
Not yet implemented, but conceptually:
|
||||
- Stage 1: Large engines, heavy structure
|
||||
- Stage 2: Smaller engines, lighter structure
|
||||
- Interstage adapter: mass penalty
|
||||
- Staging sequence: defined by velocity requirements
|
||||
|
||||
Implementation would require:
|
||||
- Multiple vehicle definitions (or list of stages)
|
||||
- Trajectory system that handles stage separation
|
||||
- Cumulative mass and thrust calculations
|
||||
|
||||
### Composite Materials
|
||||
|
||||
CFRP offers best strength-to-weight but requires special analysis:
|
||||
- **Fiber direction** — properties vary with orientation
|
||||
- **Matrix** — epoxy, vinyl ester
|
||||
- **Layup schedule** — [0°/90°/45°] typical
|
||||
- **Microbuckling** — axial compression limit
|
||||
- **Matrix cracking** — transverse tensile limit
|
||||
|
||||
Advanced model would include:
|
||||
- Classical laminate theory (CLT)
|
||||
- Ply-by-ply failure criteria (Tsai-Wu, Hashin)
|
||||
- Buckling analysis (Timoshenko, finite element)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tank too long?
|
||||
- Reduce ullage percentage (lower to 5%)
|
||||
- Increase radius (larger tank, shorter cylinder)
|
||||
- Split into multiple smaller tanks
|
||||
- Switch to coaxial configuration
|
||||
|
||||
### Vehicle too heavy?
|
||||
- Switch to lighter material (CFRP)
|
||||
- Reduce safety factor (if acceptable)
|
||||
- Decrease payload mass
|
||||
- Use pump-fed system (avoids pressurant)
|
||||
|
||||
### Nose cone looks wrong?
|
||||
- Verify radius and length (L = 2R)
|
||||
- Try different shape (Von Kármán usually best)
|
||||
- Check 3D viewer isn't zoomed in too far
|
||||
|
||||
### 3D model not rendering?
|
||||
- WebGL must be enabled
|
||||
- Check browser console for Three.js errors
|
||||
- Ensure geometry dimensions are reasonable (not NaN)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NASA SP-8007: Structural Design and Test Factors of Safety for Spaceflight Hardware
|
||||
- Huzel, D. K., & Huang, D. H. (1992). Modern engineering for design of liquid-propellant rocket engines.
|
||||
- Rocket Propulsion Elements (8th ed.). by Sutton & Biblarz.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-02 | **Status**: Current (v3 — Domed Tanks)
|
||||
319
docs/SOLVER.md
Normal file
319
docs/SOLVER.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# Solver Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The **Equation Solver** is a constraint-based computational engine that automatically solves rocket propulsion equations. Rather than manually plugging numbers into formulas, users specify constraints (inputs), and the solver propagates solutions through an interconnected equation network.
|
||||
|
||||
**Key Concept**: Drag variables onto the workspace, set values, and the solver automatically computes unknowns.
|
||||
|
||||
## User Interface
|
||||
|
||||
### Variable Palette (Left)
|
||||
- Searchable list of all variables
|
||||
- Organized by category (thrust, Isp, chamber, etc.)
|
||||
- Drag variables onto workspace
|
||||
|
||||
### Workspace (Center)
|
||||
- Drop zone for constraint cards
|
||||
- Cards show variable name, unit, input field
|
||||
- Set constraint by entering value
|
||||
- Results auto-compute below
|
||||
|
||||
### Results Panel (Right)
|
||||
- Shows all computed values
|
||||
- Organized by category
|
||||
- Clickable to copy values
|
||||
- Unit selector for each variable
|
||||
|
||||
## Constraint Propagation Algorithm
|
||||
|
||||
The solver implements **greedy propagation**:
|
||||
|
||||
### Step-by-Step
|
||||
|
||||
1. **User Input**: Sets constraint on variable `x`
|
||||
2. **Find Equations**: Locates all equations referencing `x`
|
||||
3. **Attempt Solve**: For each equation, tries to solve for unknowns
|
||||
- If equation has 1 unknown: solve directly
|
||||
- If equation has 2+ unknowns: skip (not enough constraints)
|
||||
4. **Update State**: Newly-solved variables are added to known set
|
||||
5. **Recurse**: Repeat step 2 with newly-known variables
|
||||
6. **Stop**: When no new variables can be computed
|
||||
|
||||
### Example
|
||||
|
||||
**Given:**
|
||||
- `thrust = massFlowRate * exitVelocity`
|
||||
- `exitVelocity = sqrt(2 * Cp * (T0 - Te))`
|
||||
- `massFlowRate = densityO2 * densityFuel * burnRate`
|
||||
|
||||
**User Constraints:**
|
||||
- `thrust = 50000 N`
|
||||
- `massFlowRate = 100 kg/s`
|
||||
|
||||
**Solver Flow:**
|
||||
```
|
||||
1. Set thrust = 50000
|
||||
2. Find equations with thrust: Eq1
|
||||
3. Eq1 has 2 unknowns (massFlowRate, exitVelocity) → skip
|
||||
4. Set massFlowRate = 100
|
||||
5. Find equations with massFlowRate: Eq1, Eq3
|
||||
6. Eq1 now has 1 unknown (exitVelocity) → solve: exitVelocity = 500 m/s
|
||||
7. Find equations with exitVelocity: Eq2
|
||||
8. Eq2 has 2 unknowns (T0, Te) → skip
|
||||
9. No new variables → done
|
||||
```
|
||||
|
||||
## Variable Definitions
|
||||
|
||||
Variables are defined in `src/engine/variables.js` with metadata:
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: 'thrust',
|
||||
name: 'Thrust',
|
||||
unit: 'N',
|
||||
category: 'performance',
|
||||
type: 'number'
|
||||
}
|
||||
```
|
||||
|
||||
**Categories:**
|
||||
- `thrust` — Force (N, lbf)
|
||||
- `isp` — Specific impulse (s, m/s)
|
||||
- `chamber` — Chamber conditions (P, T, density)
|
||||
- `nozzle` — Nozzle geometry (area, diameter, angle)
|
||||
- `propellant` — Fuel/oxidizer properties
|
||||
- `flow` — Mass flow rate, burn rate
|
||||
- `thermal` — Heat, temperature
|
||||
- `structural` — Stress, strain, thickness
|
||||
|
||||
## Equation Library
|
||||
|
||||
Equations are defined in `src/engine/equations.js`. Each equation:
|
||||
|
||||
1. **Specifies variables** it relates
|
||||
2. **Implements forward solver** (compute output given inputs)
|
||||
3. **Implements per-variable solvers** (solve for each variable given others)
|
||||
|
||||
### Example Equation
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: 'thrustEquation',
|
||||
name: 'Thrust (Momentum)',
|
||||
variables: ['thrust', 'massFlowRate', 'exitVelocity'],
|
||||
equation: 'thrust = massFlowRate * exitVelocity',
|
||||
forward: (inputs) => {
|
||||
return inputs.massFlowRate * inputs.exitVelocity
|
||||
},
|
||||
solvers: {
|
||||
exitVelocity: (inputs) => {
|
||||
return inputs.thrust / inputs.massFlowRate
|
||||
},
|
||||
thrust: (inputs) => {
|
||||
return inputs.massFlowRate * inputs.exitVelocity
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Transcendental Equations (Bisection)
|
||||
|
||||
For equations with no closed-form solution (e.g., Mach from area ratio), the solver uses **bisection**:
|
||||
|
||||
```javascript
|
||||
// In numerics.js
|
||||
function bisection(fn, target, min, max, tolerance) {
|
||||
while (max - min > tolerance) {
|
||||
const mid = (min + max) / 2
|
||||
const fMid = fn(mid)
|
||||
if (fMid < target) {
|
||||
min = mid
|
||||
} else {
|
||||
max = mid
|
||||
}
|
||||
}
|
||||
return (min + max) / 2
|
||||
}
|
||||
```
|
||||
|
||||
Example: Finding Mach number from area ratio
|
||||
```javascript
|
||||
solvers: {
|
||||
machNumber: (inputs) => {
|
||||
const fn = (M) => isentropicAreaRatio(M, inputs.gamma)
|
||||
return bisection(fn, inputs.areaRatio, 0.01, 10, 1e-6)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Equations
|
||||
|
||||
### Thrust
|
||||
```
|
||||
thrust = mass_flow_rate * exit_velocity
|
||||
thrust = chamber_pressure * throat_area * CF
|
||||
```
|
||||
|
||||
### Specific Impulse
|
||||
```
|
||||
Isp = exit_velocity / g
|
||||
Isp_vac = exit_velocity / g
|
||||
Isp_sl = (exit_velocity - P_exit / mass_flow_rate * area_exit) / g
|
||||
```
|
||||
|
||||
### Chamber Conditions (Isentropic Flow)
|
||||
```
|
||||
T_exit = T_chamber * (P_exit / P_chamber)^((gamma - 1) / gamma)
|
||||
rho_exit = rho_chamber * (P_exit / P_chamber)^(1 / gamma)
|
||||
```
|
||||
|
||||
### Nozzle Area Ratio
|
||||
```
|
||||
A_exit / A_throat = (2 / (gamma + 1)) * (1 + (gamma - 1)/2 * M_exit^2))^((gamma + 1) / (2 * (gamma - 1))) / M_exit
|
||||
```
|
||||
(requires bisection to invert for M)
|
||||
|
||||
### Characteristic Velocity
|
||||
```
|
||||
c_star = P_chamber * A_throat / mass_flow_rate
|
||||
```
|
||||
|
||||
### Thrust Coefficient
|
||||
```
|
||||
CF = sqrt(2 * gamma^2 / (gamma - 1) * (2 / (gamma + 1))^((gamma + 1) / (gamma - 1)) * (1 - (P_exit / P_chamber)^((gamma - 1) / gamma)))
|
||||
```
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Example 1: Determine Exit Velocity from Isp
|
||||
|
||||
**Goal:** Calculate exit velocity given Isp
|
||||
|
||||
**Steps:**
|
||||
1. Drag `specificImpulse` onto workspace
|
||||
2. Set `specificImpulse = 300 s`
|
||||
3. Solver computes `exitVelocity = 300 * 9.81 ≈ 2943 m/s`
|
||||
|
||||
### Example 2: Find Chamber Pressure from Thrust
|
||||
|
||||
**Goal:** Find chamber pressure needed for 50 kN thrust
|
||||
|
||||
**Steps:**
|
||||
1. Drag `thrust`, `throatDiameter`, `massFlowRate` onto workspace
|
||||
2. Set:
|
||||
- `thrust = 50000 N`
|
||||
- `throatDiameter = 0.1 m`
|
||||
- `massFlowRate = 100 kg/s`
|
||||
3. Solver finds equations with these variables
|
||||
4. Uses thrust equation to find thrust coefficient needed
|
||||
5. Inverts nozzle area ratio with bisection to find Mach
|
||||
6. Uses isentropic relations to find chamber pressure
|
||||
7. Displays `chamberPressure = X bar`
|
||||
|
||||
### Example 3: Design for Specific Isp
|
||||
|
||||
**Goal:** Find propellant combination for Isp = 350 s
|
||||
|
||||
**Steps:**
|
||||
1. Drag `specificImpulse`, `chamberTemperature`, `exhaustGamma` onto workspace
|
||||
2. Set `specificImpulse = 350 s`
|
||||
3. Click on knowledgebase to find propellant with T0 ≈ 3500 K
|
||||
4. Enter that temperature
|
||||
5. Solver computes `exitVelocity`, then works backward to required conditions
|
||||
6. Compare against available propellants
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Unit Conversion
|
||||
Every variable card has a unit selector. Setting a variable automatically converts:
|
||||
```
|
||||
thrust = 50000 N → 11240.44 lbf
|
||||
thrust = 11240.44 lbf → 50000 N
|
||||
```
|
||||
|
||||
### Importing Engine Design
|
||||
Engine design results can be fed into the solver:
|
||||
- File → Import Engine JSON
|
||||
- Automatically populates thrust, Isp, chamber pressure, etc.
|
||||
- Enables end-to-end rocket design workflow
|
||||
|
||||
### Variable Categories
|
||||
Filter variables by category to reduce clutter:
|
||||
- Thrust (F, Isp, c*)
|
||||
- Chamber (P, T, density)
|
||||
- Nozzle (area, geometry)
|
||||
- Propellant (fuel/oxidizer properties)
|
||||
- Flow (mass flow, burn rate)
|
||||
|
||||
## Limitations & Gotchas
|
||||
|
||||
1. **No Circular Dependencies**: If equations form a cycle, solver may loop infinitely
|
||||
- Solver stops after N iterations to prevent this
|
||||
- Design equations to be acyclic where possible
|
||||
|
||||
2. **Insufficient Constraints**: If variables are underdetermined (more unknowns than equations)
|
||||
- Solver computes what it can, leaves rest as unknown
|
||||
- User must provide more constraints
|
||||
|
||||
3. **Overdetermined System**: If too many constraints (conflicting values)
|
||||
- Solver uses first constraint encountered
|
||||
- Other constraints ignored (may warn in future)
|
||||
|
||||
4. **Transcendental Equation Tolerance**: Bisection has numerical error
|
||||
- Default tolerance: 1e-6
|
||||
- Results accurate to ~6 significant figures
|
||||
- Adjust in `numerics.js` if higher precision needed
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Solver not computing?
|
||||
- Ensure at least one constraint is set
|
||||
- Check that equation network connects the variables you're trying to solve
|
||||
- Look for missing material properties (fuel, oxidizer data)
|
||||
|
||||
### Result seems wrong?
|
||||
- Verify input units match variable definition
|
||||
- Check variable category (is it the right variable?)
|
||||
- Try solving step-by-step with intermediate variables
|
||||
|
||||
### Equation not available?
|
||||
- Not all rocketry equations are implemented
|
||||
- Submit a feature request to add more
|
||||
- Or add the equation yourself in `src/engine/equations.js`
|
||||
|
||||
## Development Guide
|
||||
|
||||
### Adding a New Equation
|
||||
|
||||
1. **Define variables** in `variables.js` if needed
|
||||
2. **Implement equation** in `equations.js`:
|
||||
|
||||
```javascript
|
||||
equations.push({
|
||||
id: 'myEquation',
|
||||
name: 'My Equation',
|
||||
variables: ['var1', 'var2', 'var3'],
|
||||
equation: 'var1 = var2 * var3',
|
||||
solvers: {
|
||||
var1: (inputs) => inputs.var2 * inputs.var3,
|
||||
var2: (inputs) => inputs.var1 / inputs.var3,
|
||||
var3: (inputs) => inputs.var1 / inputs.var2
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
3. **Test** by:
|
||||
- Setting constraints manually
|
||||
- Verifying solver produces correct result
|
||||
- Testing with known values
|
||||
|
||||
### Debugging Solver
|
||||
- Add console logs in `solver.js` propagation loop
|
||||
- Log variable state at each iteration
|
||||
- Verify equation network is correct
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-02 | **Status**: Current
|
||||
503
docs/TRAJECTORY.md
Normal file
503
docs/TRAJECTORY.md
Normal file
@@ -0,0 +1,503 @@
|
||||
# Trajectory Simulation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The **Trajectory Simulator** predicts rocket flight paths using physics-based 4th-order Runge-Kutta integration. It accounts for atmospheric drag, gravity, thrust, and user-defined events to compute complete vehicle trajectories from liftoff to landing.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Configure Vehicle**
|
||||
- Import engine (from Engine Designer) or specify manually
|
||||
- Enter vehicle mass (wet & dry), reference area, drag coefficient
|
||||
|
||||
2. **Configure Atmosphere**
|
||||
- Select model (US Standard, exponential)
|
||||
- Set sea-level conditions (temperature, pressure)
|
||||
|
||||
3. **Set Pitch Program**
|
||||
- Vertical hold duration or altitude
|
||||
- Then gravity turn (pitch follows velocity vector)
|
||||
|
||||
4. **Add Events** (optional)
|
||||
- Guidance commands (pitch changes)
|
||||
- Jettison (drop mass during flight)
|
||||
- Markers (annotations)
|
||||
|
||||
5. **Run Simulation**
|
||||
- Click "Run Simulation"
|
||||
- Wait for RK4 integration to complete
|
||||
|
||||
6. **Playback**
|
||||
- Watch animation (1×, 5×, 10× speed)
|
||||
- Scrub timeline to jump to time
|
||||
- Click on plot to jump to position
|
||||
|
||||
---
|
||||
|
||||
## Physics Model
|
||||
|
||||
### State Vector
|
||||
|
||||
At each timestep, we track:
|
||||
```
|
||||
state = [x, y, vx, vy, m]
|
||||
```
|
||||
|
||||
- `x` — downrange distance (m)
|
||||
- `y` — altitude above sea level (m)
|
||||
- `vx` — horizontal velocity (m/s, positive = downrange)
|
||||
- `vy` — vertical velocity (m/s, positive = up)
|
||||
- `m` — vehicle mass (kg)
|
||||
|
||||
### Forces
|
||||
|
||||
**Thrust:**
|
||||
```
|
||||
F_thrust = thrust(t) × cos(pitch_angle) [horizontal component]
|
||||
F_thrust = thrust(t) × sin(pitch_angle) [vertical component]
|
||||
```
|
||||
|
||||
Direction depends on pitch program (see below).
|
||||
|
||||
**Gravity (altitude-dependent):**
|
||||
```
|
||||
g(h) = g0 × (R_earth / (R_earth + h))²
|
||||
```
|
||||
|
||||
Where:
|
||||
- `g0` = 9.81 m/s²
|
||||
- `R_earth` = 6.371×10⁶ m
|
||||
- `h` = altitude (m)
|
||||
|
||||
**Drag:**
|
||||
```
|
||||
F_drag = 0.5 × ρ(h) × v² × Cd × A_ref
|
||||
```
|
||||
|
||||
Opposed to velocity direction:
|
||||
```
|
||||
F_drag_x = -F_drag × (vx / v)
|
||||
F_drag_y = -F_drag × (vy / v)
|
||||
```
|
||||
|
||||
Where `v = √(vx² + vy²)` is total velocity.
|
||||
|
||||
### Atmosphere
|
||||
|
||||
**US Standard Model (default):**
|
||||
- Piecewise linear layers
|
||||
- Troposphere: 0–8500 m (temperature decreases 6.5 K/km)
|
||||
- Stratosphere: 8500–15000 m (isothermal at 216.5 K)
|
||||
- Higher: exponential decay
|
||||
|
||||
**Exponential Model:**
|
||||
```
|
||||
ρ(h) = ρ0 × exp(-h / H)
|
||||
```
|
||||
|
||||
Where:
|
||||
- `ρ0` = sea-level density (1.225 kg/m³)
|
||||
- `H` = scale height (~8500 m)
|
||||
|
||||
**Pressure & Temperature:**
|
||||
- US Standard uses table lookup
|
||||
- Temperature affects gas density (lower T = higher ρ at same P)
|
||||
|
||||
### Equations of Motion
|
||||
|
||||
**Acceleration:**
|
||||
```
|
||||
a_x = (F_thrust_x + F_drag_x) / m
|
||||
a_y = (F_thrust_y + F_drag_y - m×g(h)) / m
|
||||
```
|
||||
|
||||
**Mass Change (during burn):**
|
||||
```
|
||||
dm/dt = -mass_flow_rate
|
||||
```
|
||||
|
||||
Mass only changes during engine burn phase (after liftoff, before MECO).
|
||||
|
||||
### Numerical Integration (RK4)
|
||||
|
||||
The integrator advances state by small timesteps (default: dt = 0.05 s):
|
||||
|
||||
```
|
||||
k1 = derivatives(t, state)
|
||||
k2 = derivatives(t + dt/2, state + k1×dt/2)
|
||||
k3 = derivatives(t + dt/2, state + k2×dt/2)
|
||||
k4 = derivatives(t + dt, state + k3×dt)
|
||||
|
||||
state_new = state + (k1 + 2×k2 + 2×k3 + k4) × dt/6
|
||||
```
|
||||
|
||||
**Accuracy**: RK4 is 4th-order accurate; typical error scales as O(dt⁵).
|
||||
|
||||
**Advantages:**
|
||||
- More accurate than Euler method
|
||||
- Reasonable computational speed
|
||||
- Standard in trajectory software
|
||||
|
||||
**Limitations:**
|
||||
- No adaptive timestep (dt is fixed)
|
||||
- Cannot handle stiff equations
|
||||
- Small dt needed for accuracy (0.01–0.1 s typical)
|
||||
|
||||
---
|
||||
|
||||
## Inputs
|
||||
|
||||
### Vehicle Configuration
|
||||
|
||||
**From Engine Designer (auto-populated if imported):**
|
||||
- `thrust` — engine thrust curve or constant
|
||||
- `isp` — specific impulse (vacuum)
|
||||
- `mdot` — mass flow rate (kg/s)
|
||||
- `burnTime` — engine burn duration (s)
|
||||
- `dryMass` — engine dry mass (kg)
|
||||
|
||||
**Vehicle Properties (manual input):**
|
||||
- `wetMass` — total mass with propellant (kg)
|
||||
- `dryMass` — mass without propellant (kg)
|
||||
- **Note**: Used after engine shutdown
|
||||
- `referenceArea` — cross-sectional area for drag (m²)
|
||||
- `dragCoefficient` — Cd (typically 0.2–0.3 for rockets)
|
||||
- `payloadMass` — payload (kg, contributes to dry mass)
|
||||
|
||||
### Atmospheric Conditions
|
||||
|
||||
- `atmosphereModel` — US Standard or Exponential
|
||||
- `seaLevelTemperature` — T0 (K), default 288.15 K (15°C)
|
||||
- `seaLevelPressure` — P0 (Pa), default 101325 Pa
|
||||
- `windSpeed` — not yet implemented
|
||||
|
||||
### Pitch Program
|
||||
|
||||
**Vertical Hold Phase:**
|
||||
- `pitchStartAlt` — altitude to begin gravity turn (m)
|
||||
- Duration: liftoff until altitude > pitchStartAlt
|
||||
- Pitch angle: 90° (straight up)
|
||||
|
||||
**Gravity Turn Phase:**
|
||||
- Pitch angle follows velocity vector
|
||||
- `pitch = atan2(vy, vx)`
|
||||
- Vehicle points along flight path (min drag)
|
||||
|
||||
**Advanced Programs (future):**
|
||||
- Custom pitch schedule vs. time
|
||||
- Thrust vector control
|
||||
- Angle of attack constraints
|
||||
|
||||
---
|
||||
|
||||
## Outputs
|
||||
|
||||
### Trajectory States
|
||||
|
||||
Array of `state` vectors at each timestep:
|
||||
```javascript
|
||||
[
|
||||
{time: 0, x: 0, y: 0, vx: 0, vy: 0.1, m: 2000},
|
||||
{time: 0.05, x: 0, y: 0.005, vx: 0.2, vy: 15.0, m: 1999.5},
|
||||
...
|
||||
{time: 60, x: 5000, y: 50000, vx: 2000, vy: 0, m: 800}
|
||||
]
|
||||
```
|
||||
|
||||
Total states: ~1200 for 60 second flight (0.05 s dt)
|
||||
|
||||
### Auto-Detected Events
|
||||
|
||||
**Liftoff:**
|
||||
- First time `y > 0` and `vy > 0`
|
||||
- Time, altitude, velocity logged
|
||||
|
||||
**Main Engine Cutoff (MECO):**
|
||||
- When `burnTime` expires
|
||||
- Last time mass changes
|
||||
- Marks end of powered flight
|
||||
|
||||
**Max Q (Dynamic Pressure):**
|
||||
- Maximum value of `q = 0.5 × ρ × v²`
|
||||
- Often a structural design point
|
||||
- Time, altitude, velocity, q value
|
||||
|
||||
**Apogee:**
|
||||
- Highest altitude reached
|
||||
- First time `vy` changes from positive to negative
|
||||
- Last point of ascending flight
|
||||
|
||||
**Landing:**
|
||||
- First time `y ≤ 0` after apogee
|
||||
- Final altitude, downrange, velocity
|
||||
|
||||
### User-Defined Events
|
||||
|
||||
**Guidance (Pitch Command):**
|
||||
```javascript
|
||||
{type: 'guidance', time: 30, pitchAngle: 45}
|
||||
```
|
||||
At t=30s, change pitch to 45° (overrides gravity turn)
|
||||
|
||||
**Jettison (Mass Drop):**
|
||||
```javascript
|
||||
{type: 'jettison', time: 25, massDropped: 50}
|
||||
```
|
||||
Drop 50 kg (e.g., fairings) at t=25s
|
||||
- Reduces drag & inertia
|
||||
- Affects apogee & downrange
|
||||
|
||||
**Marker (Annotation):**
|
||||
```javascript
|
||||
{type: 'marker', time: 15, label: 'Separation'}
|
||||
```
|
||||
Just marks event on timeline; no physics change
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Simulate LOX/RP1 Rocket
|
||||
|
||||
### Step 1: Design Engine
|
||||
1. Go to **Design > Engine**
|
||||
2. LOX/RP1, 200 bar → ~150 kN thrust, 310 s Isp, 60 s burn
|
||||
3. Export JSON
|
||||
|
||||
### Step 2: Design Rocket
|
||||
1. Go to **Design > Rocket**
|
||||
2. Import engine JSON (gets thrust, Isp, burn time)
|
||||
3. Configure tanks (5000 L, tandem)
|
||||
4. Set payload (50 kg)
|
||||
→ **Result**: Wet mass 1550 kg, dry mass 450 kg
|
||||
|
||||
### Step 3: Run Trajectory
|
||||
1. Go to **Design > Trajectory**
|
||||
2. Import rocket JSON (gets wet/dry mass, reference area)
|
||||
3. Import engine JSON (gets thrust, Isp, burn time)
|
||||
4. Set pitch start altitude: 1000 m
|
||||
5. Click "Run Simulation"
|
||||
→ **Result**: ~5000 m downrange, 50 km apogee, 180 s flight time
|
||||
|
||||
### Step 4: Analyze Results
|
||||
- **Plot**: Shows altitude vs. downrange (parabolic path)
|
||||
- **Timeline**: Mark apogee, MECO, Max Q
|
||||
- **Playback**: Watch animation in real time
|
||||
- **Scrub**: Jump to specific times to see position/velocity
|
||||
|
||||
### Step 5: Optimize
|
||||
- Try different masses (remove payload → higher apogee)
|
||||
- Try different pitch programs (start gravity turn later → longer range)
|
||||
- Try jettison events (drop fairings at MECO → save mass)
|
||||
|
||||
---
|
||||
|
||||
## Event System
|
||||
|
||||
### Event Structure
|
||||
|
||||
```javascript
|
||||
{
|
||||
type: 'liftoff' | 'meco' | 'maxQ' | 'apogee' | 'landing' | 'guidance' | 'jettison' | 'marker',
|
||||
time: number, // seconds
|
||||
altitude?: number, // meters
|
||||
downrange?: number, // meters
|
||||
velocity?: number, // m/s
|
||||
label?: string, // display name
|
||||
value?: any // event-specific data
|
||||
}
|
||||
```
|
||||
|
||||
### Auto-Detected Events (Read-Only)
|
||||
|
||||
Computed during simulation; user cannot edit.
|
||||
|
||||
**Liftoff**: `{type: 'liftoff', time: 0.05, altitude: 0.1, velocity: 1.5}`
|
||||
|
||||
**Max Q**: `{type: 'maxQ', time: 5.2, altitude: 1000, q: 50000}`
|
||||
|
||||
**Apogee**: `{type: 'apogee', time: 120, altitude: 50000, velocity: 0}`
|
||||
|
||||
**Landing**: `{type: 'landing', time: 180, altitude: 0, downrange: 5000, velocity: -50}`
|
||||
|
||||
### User Events
|
||||
|
||||
**Guidance Command:**
|
||||
```javascript
|
||||
{type: 'guidance', time: 30, pitchAngle: 45, label: 'Pitch over'}
|
||||
```
|
||||
- Changes pitch at specified time
|
||||
- Overrides gravity turn
|
||||
- Can be used for coast phase burn starts, etc.
|
||||
|
||||
**Jettison:**
|
||||
```javascript
|
||||
{type: 'jettison', time: 25, massDropped: 50, label: 'Fairing separation'}
|
||||
```
|
||||
- Removes mass from trajectory
|
||||
- Affects drag & inertia
|
||||
- Typically after Max Q (fairing drag not needed)
|
||||
|
||||
**Marker:**
|
||||
```javascript
|
||||
{type: 'marker', time: 60, label: 'Engine cutoff'}
|
||||
```
|
||||
- Pure annotation
|
||||
- No physics effect
|
||||
- Useful for documentation
|
||||
|
||||
---
|
||||
|
||||
## 3D Visualization
|
||||
|
||||
### Trajectory Plot
|
||||
|
||||
HTML5 Canvas rendering of flight path:
|
||||
|
||||
**Axes:**
|
||||
- X: downrange (0 to max)
|
||||
- Y: altitude (0 to apogee + margin)
|
||||
- Aspect ratio: ~2:1 (wider than tall)
|
||||
|
||||
**Elements:**
|
||||
- Trajectory curve (light blue line)
|
||||
- Event markers (circles at key points)
|
||||
- Grid (light gray, 10 km spacing)
|
||||
- Labels (altitude, downrange at axis)
|
||||
- Legend (event types & colors)
|
||||
|
||||
**Interactivity:**
|
||||
- Click on plot → jump to that time
|
||||
- Hover on point → show values (alt, range, velocity)
|
||||
- Hover on event marker → show label
|
||||
- Zoom (mousewheel) — not yet implemented
|
||||
|
||||
### 3D Flight Animation
|
||||
|
||||
**Top-down view** showing:
|
||||
- Vehicle model (small rocket symbol or sphere)
|
||||
- Flight path (line from start to current position)
|
||||
- Current altitude/range indicators
|
||||
- Compass heading
|
||||
|
||||
**Implementation:** Canvas 2D or Three.js (current: Canvas)
|
||||
|
||||
---
|
||||
|
||||
## Playback Controls
|
||||
|
||||
### Timeline Bar
|
||||
|
||||
Located below trajectory plot:
|
||||
|
||||
**Play/Pause Button:**
|
||||
- Starts/stops animation
|
||||
- Keyboard: Space bar
|
||||
|
||||
**Speed Selector:**
|
||||
- 1× — real time
|
||||
- 5× — 5× faster
|
||||
- 10× — 10× faster
|
||||
|
||||
**Scrubber (Time Slider):**
|
||||
- Drag to jump to any time
|
||||
- Release to play from that point
|
||||
- Shows current time in seconds
|
||||
|
||||
**Event Timeline:**
|
||||
- Vertical lines at event times
|
||||
- Hover to see event name
|
||||
- Click to jump to event
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
- **Space**: Play/pause
|
||||
- **→**: Jump forward 10 seconds
|
||||
- **←**: Jump backward 10 seconds
|
||||
- **Home**: Jump to start
|
||||
- **End**: Jump to end
|
||||
|
||||
---
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Thrust Curves (Future)
|
||||
|
||||
Instead of constant thrust, can import actual thrust vs. time:
|
||||
```javascript
|
||||
{
|
||||
type: 'thrustCurve',
|
||||
data: [
|
||||
{time: 0, thrust: 150000},
|
||||
{time: 5, thrust: 145000},
|
||||
{time: 60, thrust: 0}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Would enable:
|
||||
- Throttling analysis (variable thrust)
|
||||
- Solid rocket motor curves
|
||||
- Multi-engine clustering
|
||||
|
||||
### Stage Separation
|
||||
|
||||
Currently single-stage only. Multi-stage would require:
|
||||
- Stage definition (separate vehicle configs)
|
||||
- Coast phase between stages
|
||||
- Staging logic (when to ignite next stage)
|
||||
- Updated mass calculations
|
||||
|
||||
### Wind Effects
|
||||
|
||||
Could add:
|
||||
- Constant wind (direction, magnitude)
|
||||
- Turbulence (atmospheric gusts)
|
||||
- Wind shear (altitude-dependent)
|
||||
- Affects trajectory & landing site
|
||||
|
||||
### Control Systems
|
||||
|
||||
Could add:
|
||||
- Attitude feedback (pitch control gains)
|
||||
- Stability margin (static/dynamic)
|
||||
- Fin-based control
|
||||
- Thrust vector control (TVC)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Trajectory looks wrong
|
||||
- Check vehicle mass (should match design)
|
||||
- Verify drag coefficient (0.25 ± 0.05 typical)
|
||||
- Confirm reference area (cross-sectional)
|
||||
- Ensure engine thrust profile is correct
|
||||
|
||||
### Apogee seems too low
|
||||
- Verify engine thrust (check import)
|
||||
- Check mass (try reducing payload)
|
||||
- Ensure Isp is correct (affects delta-v)
|
||||
- Try longer burn time or higher chamber pressure
|
||||
|
||||
### Simulation diverges (NaN values)
|
||||
- Reduce timestep dt (smaller step size)
|
||||
- Check for negative mass (propellant consumed)
|
||||
- Verify atmosphere model (no singularities)
|
||||
- Ensure velocity doesn't exceed sound barrier (should be OK)
|
||||
|
||||
### Playback animation slow
|
||||
- Reduce speed (don't use 10×)
|
||||
- Close other browser tabs
|
||||
- Lower resolution (use simpler plot)
|
||||
- Reduce state vector size (use larger dt)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- Beard, R. W., & McLain, T. W. (2012). Small unmanned aircraft: Theory and practice. Princeton University Press.
|
||||
- Vallado, D. A., Crawford, P., Hujsa, R., & Kelso, T. S. (2006). Revisiting spacetrack report #3. AIAA/AAS Astrodynamics Specialist Conference.
|
||||
- US Standard Atmosphere 1976. NASA TM-X-74335
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-02 | **Status**: Current (v1)
|
||||
Reference in New Issue
Block a user