507 lines
17 KiB
Markdown
507 lines
17 KiB
Markdown
# Formula and Unit File Format Guide
|
||
|
||
This document describes the format for contributing formulas and units to the d4rt_formulas project. It is intended for formula contributors and developers.
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [Overview](#overview)
|
||
2. [Formula Files](#formula-files)
|
||
3. [Unit Files](#unit-files)
|
||
4. [Writing Descriptions](#writing-descriptions)
|
||
5. [Best Practices](#best-practices)
|
||
6. [Examples](#examples)
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
The project uses two types of asset files:
|
||
|
||
| File Type | Location | Extension | Format |
|
||
|--------------|--------------------|---------------|---------------------------------|
|
||
| **Formulas** | `assets/formulas/` | `.d4rt` | Dart array literals (JSON-like) |
|
||
| **Units** | `assets/units/` | `.d4rt.units` | Dart array literals (JSON-like) |
|
||
|
||
Both formats use Dart set/array literals with map entries. Files are parsed at runtime to populate the formula calculator.
|
||
|
||
---
|
||
|
||
## Formula Files
|
||
|
||
### File Structure
|
||
|
||
Formula files are organized by topic (e.g., `geometry.d4rt`, `electromagnetism.d4rt`). Each file contains a Dart array literal with formula objects:
|
||
|
||
```dart
|
||
[
|
||
{
|
||
"name": "Formula Name",
|
||
"description": r"""Markdown description with LaTeX""",
|
||
"input": [
|
||
{"name": "variable1", "unit": "unit_name"},
|
||
{"name": "variable2", "unit": "unit_name"}
|
||
],
|
||
"output": {"name": "result", "unit": "unit_name"},
|
||
"d4rtCode": "result = expression;",
|
||
"tags": ["tag1", "tag2"]
|
||
},
|
||
// More formulas...
|
||
]
|
||
```
|
||
|
||
### Formula Object Fields
|
||
|
||
| Field | Type | Required | Description |
|
||
|---------------|--------|----------|------------------------------------------------------------------------------------------|
|
||
| `name` | String | Yes | Human-readable formula name |
|
||
| `description` | String | Yes | Markdown description with LaTeX math (see [Writing Descriptions](#writing-descriptions)) |
|
||
| `input` | Array | Yes | List of input variables with their units |
|
||
| `output` | Object | Yes | Output variable name and unit |
|
||
| `d4rtCode` | String | Yes | Dart code that computes the result |
|
||
| `tags` | Array | Yes | Categorization tags for search/filter |
|
||
|
||
### Input/Output Format
|
||
|
||
**Input variables:**
|
||
```dart
|
||
"input": [
|
||
{"name": "m", "unit": "kilogram"},
|
||
{"name": "a", "unit": "meters per square second"}
|
||
]
|
||
```
|
||
|
||
**Output variable:**
|
||
```dart
|
||
"output": {"name": "F", "unit": "newton"}
|
||
```
|
||
|
||
### Unit Names
|
||
|
||
Unit names must match entries in the `assets/units/` directory. Use the full unit name (lowercase), not the symbol:
|
||
|
||
| Correct | Incorrect |
|
||
|-----------------------|-----------|
|
||
| `"meter"` | `"m"` |
|
||
| `"kilogram"` | `"kg"` |
|
||
| `"meters per second"` | `"m/s"` |
|
||
| `"square meter"` | `"m²"` |
|
||
|
||
### Dart Code (`d4rtCode`)
|
||
|
||
The `d4rtCode` field contains valid Dart code that:
|
||
- Uses input variable names directly
|
||
- Assigns the result to the output variable name
|
||
- Can use Dart's `math` library functions (`sin`, `cos`, `sqrt`, `pow`, `pi`, etc.)
|
||
|
||
**Simple formula:**
|
||
```dart
|
||
"d4rtCode": "F = m * a;"
|
||
```
|
||
|
||
**Multi-line formula:**
|
||
```dart
|
||
"d4rtCode": """
|
||
var radians = angle * (pi / 180);
|
||
result = sin(radians);
|
||
"""
|
||
```
|
||
|
||
**With validation:**
|
||
```dart
|
||
"d4rtCode": """
|
||
if (a + b < c) {
|
||
signal("Invalid triangle: sides do not satisfy triangle inequality");
|
||
}
|
||
var s = (a + b + c) / 2;
|
||
A = sqrt(s * (s - a) * (s - b) * (s - c));
|
||
"""
|
||
```
|
||
|
||
---
|
||
|
||
## Unit Files
|
||
|
||
### File Structure
|
||
|
||
Unit files define units of measurement organized by category (e.g., `distance.d4rt.units`, `force.d4rt.units`). Each file contains a Dart array literal with unit objects:
|
||
|
||
```dart
|
||
[
|
||
{"name": "meter", "symbol": "m", "isBase": true},
|
||
{"name": "kilometer", "symbol": "km", "baseUnit": "meter", "factor": 1000},
|
||
// More units...
|
||
]
|
||
```
|
||
|
||
### Unit Object Fields
|
||
|
||
| Field | Type | Required | Description |
|
||
|------------|---------|-------------|---------------------------------------------------------------------|
|
||
| `name` | String | Yes | Full unit name (lowercase) |
|
||
| `symbol` | String | Yes | Unit symbol for display |
|
||
| `isBase` | Boolean | Conditional | `true` if this is a base unit (no conversion needed) |
|
||
| `baseUnit` | String | Conditional | Name of the base unit for conversion |
|
||
| `factor` | Number | Conditional | Multiplication factor to convert to base unit |
|
||
| `toBase` | String | Conditional | Expression/code to convert to base unit (for complex conversions) |
|
||
| `fromBase` | String | Conditional | Expression/code to convert from base unit (for complex conversions) |
|
||
|
||
### Base Units vs Derived Units
|
||
|
||
**Base units** define the reference for a category:
|
||
```dart
|
||
{"name": "meter", "symbol": "m", "isBase": true}
|
||
{"name": "newton", "symbol": "N", "isBase": true}
|
||
{"name": "joule", "symbol": "J", "isBase": true}
|
||
{"name": "Kelvin", "symbol": "K", "isBase": true}
|
||
```
|
||
|
||
**Derived units** specify conversion to their base unit. There are two types:
|
||
|
||
#### Simple Linear Conversions (using `factor`)
|
||
|
||
For units where conversion is a simple multiplication:
|
||
|
||
```dart
|
||
{"name": "kilometer", "symbol": "km", "baseUnit": "meter", "factor": 1000}
|
||
{"name": "inch", "symbol": "in", "baseUnit": "meter", "factor": 0.0254}
|
||
{"name": "pound-force", "baseUnit": "newton", "factor": 4.44822}
|
||
```
|
||
|
||
The `factor` converts **from** the defined unit **to** the base unit:
|
||
|
||
```dart
|
||
// 1 kilometer = 1000 meters
|
||
{"name": "kilometer", "baseUnit": "meter", "factor": 1000}
|
||
|
||
// 1 inch = 0.0254 meters
|
||
{"name": "inch", "baseUnit": "meter", "factor": 0.0254}
|
||
```
|
||
|
||
#### Complex Conversions (using `toBase` and `fromBase`)
|
||
|
||
For units requiring non-linear conversions (e.g., temperature scales), use `toBase` and `fromBase` expressions. The variable `x` represents the value to convert.
|
||
|
||
**Example: Celsius to Kelvin**
|
||
```dart
|
||
{
|
||
"name": "Celsius",
|
||
"symbol": "°C",
|
||
"baseUnit": "Kelvin",
|
||
"toBase": "x + 273.15", // °C → K
|
||
"fromBase": "x - 273.15", // K → °C
|
||
}
|
||
```
|
||
|
||
**Example: Fahrenheit to Kelvin**
|
||
```dart
|
||
{
|
||
"name": "Fahrenheit",
|
||
"symbol": "°F",
|
||
"baseUnit": "Kelvin",
|
||
"toBase": "(x - 32) * 5/9 + 273.15", // °F → K
|
||
"fromBase": "(x - 273.15) * 9/5 + 32", // K → °F
|
||
}
|
||
```
|
||
|
||
**Example: Multi-line conversion (Gas Mark to Kelvin)**
|
||
```dart
|
||
{
|
||
"name": "Gas Mark",
|
||
"symbol": "GM",
|
||
"baseUnit": "Kelvin",
|
||
"toBase": r"""
|
||
if (x < 1) {
|
||
double celsius = (243 - 25 * (log(1 / x) / log(2))) / 1.8;
|
||
return celsius + 273.15;
|
||
} else {
|
||
double celsius = x * 14 + 121;
|
||
return celsius + 273.15;
|
||
}
|
||
""",
|
||
"fromBase": """
|
||
double celsius = x - 273.15;
|
||
if (celsius < 135) {
|
||
return pow(2, (1.8 * celsius - 243) / 25);
|
||
} else {
|
||
return (celsius - 121) / 14;
|
||
}
|
||
"""
|
||
}
|
||
```
|
||
|
||
### Common Temperature Conversions
|
||
|
||
| Unit | toBase (→ K) | fromBase (← K) |
|
||
|------------|------------------------------|------------------------------|
|
||
| Celsius | `x + 273.15` | `x - 273.15` |
|
||
| Fahrenheit | `(x - 32) * 5/9 + 273.15` | `(x - 273.15) * 9/5 + 32` |
|
||
| Rankine | `x * 5/9` | `x * 9/5` |
|
||
| Réaumur | `x * 5/4 + 273.15` | `(x - 273.15) * 4/5` |
|
||
| Delisle | `373.15 - x * 2/3` | `(373.15 - x) * 3/2` |
|
||
| Rømer | `(x - 7.5) * 40/21 + 273.15` | `(x - 273.15) * 21/40 + 7.5` |
|
||
|
||
---
|
||
|
||
## Writing Descriptions
|
||
|
||
The `description` field uses **raw Dart string literals** (`r"""..."""`) with **Markdown** and **LaTeX** math.
|
||
|
||
### Format
|
||
|
||
```dart
|
||
"description": r"""
|
||
Short description of the formula.
|
||
|
||
$$F = m \cdot a$$
|
||
|
||
Where:
|
||
- $F$: Force (Newtons)
|
||
- $m$: Mass (kilograms)
|
||
- $a$: Acceleration (m/s²)
|
||
|
||
Additional context or notes.""",
|
||
```
|
||
|
||
### LaTeX Math
|
||
|
||
Use **MathJax/KaTeX** syntax for mathematical expressions:
|
||
|
||
| Type | Syntax | Example |
|
||
|---------------------|-----------------------------|--------------------------|
|
||
| Inline math | `$...$` | `$F = ma$` |
|
||
| Display math | `$$...$$` | `$$E = mc^2$$` |
|
||
| Fractions | `\frac{a}{b}` | `$$\frac{1}{2}mv^2$$` |
|
||
| Subscripts | `x_i` | `$v_0$` |
|
||
| Superscripts | `x^2` | `$a^2 + b^2$` |
|
||
| Greek letters | `\alpha`, `\beta`, `\theta` | `$$\sin(\theta)$$` |
|
||
| Special symbols | `\cdot`, `\times`, `\pm` | `$m \cdot a$` |
|
||
| Units in math | `\mathrm{m/s^2}` | `$9.81\ \mathrm{m/s^2}$` |
|
||
| Scientific notation | `\times 10^{-11}` | `$6.674\times 10^{-11}$` |
|
||
|
||
### Including Images
|
||
|
||
Add Wikipedia or other educational images using Markdown:
|
||
|
||
```markdown
|
||
|
||
```
|
||
|
||
**Example:**
|
||
```dart
|
||
"description": r"""
|
||
Newton's law of universal gravitation.
|
||
|
||
$$F = G\frac{m_1m_2}{r^2}$$
|
||
|
||
""",
|
||
```
|
||
|
||
### Description Structure
|
||
|
||
A well-structured description includes:
|
||
|
||
1. **Opening sentence** - Brief statement of what the formula calculates
|
||
2. **LaTeX formula** - The mathematical expression in display mode
|
||
3. **Variable definitions** - List of all variables with units
|
||
4. **Additional context** - Notes, assumptions, or applications
|
||
5. **Image** (optional) - Diagram or illustration
|
||
|
||
---
|
||
|
||
## Best Practices
|
||
|
||
### For Formulas
|
||
|
||
1. **Use clear variable names** - Single letters for physics conventions (`F`, `m`, `a`), descriptive names when clarity matters
|
||
2. **Match units precisely** - Ensure input/output units match what the formula expects
|
||
3. **Add validation** - Use `signal()` for invalid inputs (e.g., triangle inequality)
|
||
4. **Include tags** - Add relevant tags for discoverability
|
||
5. **Use LaTeX for all math** - Even simple formulas should have LaTeX representation
|
||
6. **Add images** - Include diagrams from Wikipedia when helpful
|
||
7. **Comment your code** - Use `//` comments before each formula object
|
||
|
||
### For Units
|
||
|
||
1. **Use lowercase names** - `"meter"` not `"Meter"`
|
||
2. **Include common conversions** - Add both metric and imperial units when relevant
|
||
3. **Use standard symbols** - Follow SI conventions where applicable
|
||
4. **Document the factor** - Ensure conversion factors are accurate
|
||
|
||
### For Descriptions
|
||
|
||
1. **Be concise but complete** - Explain what the formula does and what each variable means
|
||
2. **Use consistent formatting** - Follow the established pattern in existing files
|
||
3. **Include units in variable definitions** - Always specify units for each variable
|
||
4. **Add context** - Explain when/why the formula is used
|
||
5. **Note assumptions** - Mention any constraints or special conditions
|
||
|
||
---
|
||
|
||
## Examples
|
||
|
||
### Complete Formula Example
|
||
|
||
```dart
|
||
// Newton's Second Law
|
||
{
|
||
"name": "Newton's Second Law",
|
||
"description": r"""
|
||
Force equals mass times acceleration.
|
||
|
||
$$F = m \cdot a$$
|
||
|
||
Where:
|
||
- $m$: Mass of object ($\mathrm{kg}$)
|
||
- $a$: Acceleration ($\mathrm{m/s^2}$)
|
||
|
||
""",
|
||
"input": [
|
||
{"name": "m", "unit": "kilogram"},
|
||
{"name": "a", "unit": "meters per square second"}
|
||
],
|
||
"output": {"name": "F", "unit": "newton"},
|
||
"d4rtCode": "F = m * a;",
|
||
"tags": ["physics", "mechanics", "newton"]
|
||
}
|
||
```
|
||
|
||
### Complete Unit Example
|
||
|
||
```dart
|
||
[
|
||
{
|
||
"name": "newton",
|
||
"symbol": "N",
|
||
"isBase": true
|
||
},
|
||
{
|
||
"name": "kilonewton",
|
||
"symbol": "kN",
|
||
"baseUnit": "newton",
|
||
"factor": 1000
|
||
},
|
||
{
|
||
"name": "pound-force",
|
||
"symbol": "lbf",
|
||
"baseUnit": "newton",
|
||
"factor": 4.44822
|
||
}
|
||
]
|
||
```
|
||
|
||
### Multi-line Dart Code Example
|
||
|
||
```dart
|
||
// Cosine Rule
|
||
{
|
||
"name": "Cosine Rule",
|
||
"description": r"""
|
||
Generalization of the Pythagorean theorem for any triangle.
|
||
|
||
$$c^2 = a^2 + b^2 - 2ab\cos(C)$$
|
||
|
||
Where:
|
||
- $a$, $b$, $c$: Sides of the triangle
|
||
- $C$: Angle opposite to side $c$""",
|
||
"input": [
|
||
{"name": "a", "unit": "meter"},
|
||
{"name": "b", "unit": "meter"},
|
||
{"name": "C", "unit": "degree"}
|
||
],
|
||
"output": {"name": "c", "unit": "meter"},
|
||
"d4rtCode": """
|
||
var angleCRad = C * (pi / 180);
|
||
c = sqrt(pow(a, 2) + pow(b, 2) - 2*a*b*cos(angleCRad));
|
||
""",
|
||
"tags": ["trigonometry", "triangle", "cosine"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## File Organization
|
||
|
||
### Formula Categories
|
||
|
||
| File | Topic |
|
||
|----------------------------------|--------------------------------|
|
||
| `formulas.d4rt` | General physics formulas |
|
||
| `geometry.d4rt` | Geometric calculations |
|
||
| `electromagnetism.d4rt` | Electric and magnetic formulas |
|
||
| `energy_and_power.d4rt` | Energy, work, and power |
|
||
| `thermodynamics.d4rt` | Heat and thermodynamics |
|
||
| `fluids_and_pressure.d4rt` | Fluid mechanics |
|
||
| `optics.d4rt` | Light and optics |
|
||
| `trigonometry.d4rt` | Trigonometric relations |
|
||
| `materials_elasticity.d4rt` | Material properties |
|
||
| `medical_and_bio.d4rt` | Medical/biological formulas |
|
||
| `networking.d4rt` | Network calculations |
|
||
| `conversions_and_constants.d4rt` | Physical constants |
|
||
| `misc_math.d4rt` | Miscellaneous mathematics |
|
||
|
||
### Unit Categories
|
||
|
||
| File | Unit Type |
|
||
|--------------------------|------------------------|
|
||
| `distance.d4rt.units` | Length/distance |
|
||
| `mass.d4rt.units` | Mass |
|
||
| `time.d4rt.units` | Time |
|
||
| `force.d4rt.units` | Force |
|
||
| `energy.d4rt.units` | Energy |
|
||
| `power.d4rt.units` | Power |
|
||
| `pressure.d4rt.units` | Pressure |
|
||
| `velocity.d4rt.units` | Speed/velocity |
|
||
| `area.d4rt.units` | Area |
|
||
| `volume.d4rt.units` | Volume |
|
||
| `temperature.d4rt.units` | Temperature |
|
||
| `angle.d4rt.units` | Angles |
|
||
| `frequency.d4rt.units` | Frequency |
|
||
| `electricity.d4rt.units` | Electrical units |
|
||
| `derived.d4rt.units` | Derived/compound units |
|
||
|
||
---
|
||
|
||
## Quick Reference
|
||
|
||
### Common LaTeX Symbols
|
||
|
||
| Symbol | LaTeX | Symbol | LaTeX |
|
||
|--------|-----------|--------|----------|
|
||
| × | `\times` | · | `\cdot` |
|
||
| ± | `\pm` | ÷ | `\div` |
|
||
| ≤ | `\leq` | ≥ | `\geq` |
|
||
| √ | `\sqrt{}` | ∞ | `\infty` |
|
||
| π | `\pi` | θ | `\theta` |
|
||
| α | `\alpha` | β | `\beta` |
|
||
| Δ | `\Delta` | δ | `\delta` |
|
||
| Σ | `\Sigma` | σ | `\sigma` |
|
||
| Ω | `\Omega` | ω | `\omega` |
|
||
|
||
### Common Dart Math Functions
|
||
|
||
| Function | Description |
|
||
|---------------------------------|-----------------------------------|
|
||
| `sin(x)`, `cos(x)`, `tan(x)` | Trigonometric functions (radians) |
|
||
| `asin(x)`, `acos(x)`, `atan(x)` | Inverse trig functions |
|
||
| `sqrt(x)` | Square root |
|
||
| `pow(x, y)` | x raised to power y |
|
||
| `log(x)` | Natural logarithm |
|
||
| `log10(x)` | Base-10 logarithm |
|
||
| `abs(x)` | Absolute value |
|
||
| `exp(x)` | e raised to power x |
|
||
| `pi` | π constant |
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
1. **Choose the right file** - Add formulas to the appropriate category file
|
||
2. **Follow the format** - Match the structure of existing entries
|
||
3. **Test your code** - Ensure `d4rtCode` is valid Dart syntax
|
||
4. **Add description** - Include complete LaTeX documentation
|
||
5. **Tag appropriately** - Add relevant tags for searchability
|
||
6. **Review** - Check existing formulas for consistency
|
||
|
||
For questions or clarifications, refer to existing formulas in the `assets/formulas/` directory as examples.
|