https://github.com/alexeev-prog/fib_miles2km
Converter from miles to km using Fibonacci series in C
https://github.com/alexeev-prog/fib_miles2km
c computer-science converter fibonacci fibonacci-numbers fibonacci-sequence mathematics miles2km
Last synced: 10 months ago
JSON representation
Converter from miles to km using Fibonacci series in C
- Host: GitHub
- URL: https://github.com/alexeev-prog/fib_miles2km
- Owner: alexeev-prog
- License: mit
- Created: 2025-07-19T11:03:29.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-31T03:38:14.000Z (11 months ago)
- Last Synced: 2025-07-31T06:38:28.383Z (11 months ago)
- Topics: c, computer-science, converter, fibonacci, fibonacci-numbers, fibonacci-sequence, mathematics, miles2km
- Language: HTML
- Homepage: https://alexeev-prog.github.io/fib_miles2km/
- Size: 44.9 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# fib_miles2km: Advanced Distance Conversion Using Fibonacci Mathematics
Thanks to contributors:
+ [vitaliy-chernyshov](https://github.com/vitaliy-chernyshov)
## Usage
```
Advanced distance converter: miles to kilometers
Usage: ./bin/fib_miles2km [OPTIONS] [distance]
Options:
-h, --help Show help information
-f, --fib=ARG Convert miles to km using basic Fibonacci
-b, --basic=ARG Convert miles to km using standard formula
-i, --fib-interp=ARG Convert using Fibonacci interpolation
-c, --fib-cache=ARG Convert using cached Fibonacci
-g, --fib-golden=ARG Convert using golden ratio
```
## Install
```bash
git clone https://github.com/alexeev-prog/fib_miles2km
cd fib_miles2km
make
```
## Technical Overview
This project implements a sophisticated distance converter that transforms miles to kilometers using mathematical properties of the Fibonacci sequence and the golden ratio. The primary purpose is educational: to demonstrate how abstract mathematical concepts can be applied to practical computation problems while exploring different implementation strategies in C.
The core insight leverages the remarkable proximity between:
- The golden ratio (φ ≈ 1.618034)
- The exact miles-to-kilometers conversion factor (1.609344)
This 0.54% difference allows us to use consecutive Fibonacci numbers as approximate conversion pairs (e.g., 5 miles ≈ 8 km, 13 miles ≈ 21 km). The implementation explores three distinct computational approaches to this conversion, each with unique algorithmic characteristics.
## Mathematical Foundations
### Fibonacci Sequence
The Fibonacci sequence is defined by the recurrence relation:
```
F₀ = 0
F₁ = 1
Fₙ = Fₙ₋₁ + Fₙ₋₂ for n ≥ 2
```
Producing: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89,...
### Golden Ratio (φ)
The golden ratio emerges as the limit of consecutive Fibonacci ratios:
```
φ = lim (n→∞) Fₙ₊₁/Fₙ = (1 + √5)/2 ≈ 1.618034
```
### Conversion Relationship
The exact conversion factor is:
```
1 mile = 1.609344 kilometers
```
With relative error between φ and the true factor:
```
(1.618034 - 1.609344)/1.609344 × 100% ≈ 0.54%
```
### Linear Interpolation
For values between Fibonacci numbers, we use linear interpolation:
```
km = Fₖ₊₁ + (miles - Fₖ) × (Fₖ₊₂ - Fₖ₊₁)/(Fₖ₊₁ - Fₖ)
```
Where:
- Fₖ: Largest Fibonacci number ≤ miles
- Fₖ₊₁: Next Fibonacci number
- Fₖ₊₂: Subsequent Fibonacci number
## Algorithmic Implementations
### 1. Iterative Fibonacci with Interpolation
**Core Algorithm** (`fib_interpolate` in `algorithms.c`):
```c
float fib_interpolate(float miles) {
if (miles < 5.0f) return basic_miles2km(miles);
uint64_t prev_mile = 0; // F₀
uint64_t prev_km = 1; // F₁
uint64_t curr_mile = 1; // F₁
uint64_t curr_km = 1; // F₂
while (curr_mile <= miles) {
uint64_t next_mile = curr_km;
uint64_t next_km = prev_km + curr_km;
if (next_km < curr_km) break; // Overflow protection
prev_mile = curr_mile;
prev_km = curr_km;
curr_mile = next_mile;
curr_km = next_km;
}
return prev_km + (miles - prev_mile) *
((float)(curr_km - prev_km) / (curr_mile - prev_mile));
}
```
**Key Features**:
- Dynamically computes Fibonacci numbers until bracketing the input value
- Uses 64-bit integers for precision
- Implements overflow protection
- Falls back to exact conversion for values < 5 miles
- Time complexity: O(log φ(miles))
**Example Execution**:
For 10 miles:
1. Compute sequence: 0, 1, 1, 2, 3, 5, 8, 13
2. Identify bracket: 8 ≤ 10 < 13
3. Interpolate between (8,13) and (13,21)
4. Result: 16.2 km (vs exact 16.09344 km)
### 2. Cached Fibonacci Conversion
**Core Algorithm** (`fib_cache_convert` in `algorithms.c`):
```c
float fib_cache_convert(float miles) {
#define MAX_CACHE 94
static uint64_t cache[MAX_CACHE] = {0};
static int initialized = 0;
if (!initialized) {
cache[0] = 0;
cache[1] = 1;
for (int i = 2; i < MAX_CACHE; i++) {
cache[i] = cache[i-1] + cache[i-2];
}
initialized = 1;
}
if (miles < 5.0f) return basic_miles2km(miles);
int i = 1;
while (i < MAX_CACHE-1 && cache[i] <= miles) i++;
if (i >= MAX_CACHE-1) return basic_miles2km(miles);
uint64_t F_prev = cache[i-1];
uint64_t F_curr = cache[i];
uint64_t F_next = cache[i+1];
return F_curr + (miles - F_prev) *
((float)(F_next - F_curr) / (F_curr - F_prev));
}
```
**Key Features**:
- Precomputes Fibonacci numbers up to F₉₃ (max before 64-bit overflow)
- Uses static cache for single initialization
- Binary-compatible values ensure consistency
- Constant-time lookup after initialization
- Falls back to exact conversion when input exceeds cache range
**Technical Notes**:
- MAX_CACHE = 94 because F₉₃ = 12,200,160,415,121,876,738 (max for uint64_t)
- Cache initialization occurs on first function call
- Linear search through cache (O(n)) but n is small (94 elements)
### 3. Golden Ratio Conversion (Binet's Formula)
**Core Algorithm** (`fib_golden_ratio` in `algorithms.c`):
```c
float fib_golden_ratio(float miles) {
const double sqrt5 = sqrt(5.0);
const double phi = (1.0 + sqrt5) / 2.0;
if (miles < 1e-5) return 0.0f;
double n = log(miles * sqrt5) / log(phi);
int k = (int)floor(n);
double F_k = (pow(phi, k) - pow(-phi, -k)) / sqrt5;
double F_k1 = (pow(phi, k+1) - pow(-phi, -k-1)) / sqrt5;
double F_k2 = (pow(phi, k+2) - pow(-phi, -k-2)) / sqrt5;
return F_k1 + (miles - F_k) *
((float)(F_k2 - F_k1) / (F_k1 - F_k));
}
```
**Key Features**:
- Direct implementation of Binet's closed-form formula
- Uses logarithmic calculation to find Fibonacci index
- Handles non-integer inputs naturally
- Subject to floating-point precision limitations
- Requires linking with math library (-lm)
**Precision Considerations**:
- Double precision maintains accuracy until ~F₇₀
- Relative error increases exponentially beyond F₇₈
- Edge case handling prevents division by zero
## Command-Line Interface Architecture
The command parser implements a POSIX-style option processing system:
### Option Configuration Structure
```c
struct CommandOption {
const char* help;
const char* long_name;
char short_name;
int has_arg;
const char* default_value;
void* handler;
};
```
### Conflict Detection Logic
```c
int fib_methods_count = 0;
if (fib_value) fib_methods_count++;
if (fib_interp_value) fib_methods_count++;
// ... check other methods
if (fib_methods_count > 1) {
fprintf(stderr, "Error: Use only one Fibonacci conversion method\n");
return EXIT_FAILURE;
}
```
### Input Validation
```c
char* endptr;
double miles = strtod(input_value, &endptr);
if (*endptr != '\0' || miles < 0) {
fprintf(stderr, "Error: Invalid distance value '%s'\n", input_value);
return EXIT_FAILURE;
}
```
## Error Handling System
Comprehensive checks include:
- Invalid numeric inputs
- Negative distance values
- Conflicting conversion methods
- Integer overflow protection
- Floating-point underflow/overflow
- Mathematical domain errors
- Memory boundary checks
```c
// In golden ratio implementation
if (F_k1 - F_k < DBL_EPSILON) {
return basic_miles2km(miles); // Fallback to prevent division by zero
}
```
## Build and Execution
### Compilation
```bash
gcc -Wall -Wextra -O2 -lm src/*.c -o bin/fib_miles2km
```
### Execution Examples
```bash
# Fibonacci interpolation (default)
./bin/fib_miles2km 21
# Cached Fibonacci conversion
./bin/fib_miles2km --fib-cache 34.7
# Golden ratio conversion
./bin/fib_miles2km --fib-golden 55.3
# Standard conversion
./bin/fib_miles2km --basic 100
```
### Output Samples
```
21.00 miles = 33.80 km (Basic convert)
21.00 miles ≈ 34.00 km (Fibonacci interpolation)
34.70 miles ≈ 55.82 km (Cached Fibonacci)
55.30 miles ≈ 89.11 km (Golden Ratio)
100.00 miles = 160.93 km
```
## Performance Characteristics
| Method | Time Complexity | Space Complexity | Max Input (miles) | Precision |
|-----------------|-----------------|------------------|-------------------|------------------|
| Basic | O(1) | O(1) | ∞ | Exact |
| Interpolation | O(log φ(n)) | O(1) | F₉₂ ≈ 7.5e19 | ~0.54% error |
| Cached | O(1) | O(94) | F₉₂ ≈ 7.5e19 | ~0.54% error |
| Golden Ratio | O(1) | O(1) | ∞ | Degrades with n |
## Limitations and Future Work
### Current Limitations
- Golden ratio method precision limited by double-precision floating point
- Maximum input 93 miles for integer-based methods
- No multi-threading support
- Limited error statistics collection
### Enhancement Opportunities
1. **Arbitrary-precision arithmetic** for larger values
2. **Hybrid approaches** combining multiple methods
3. **Error correction** using machine learning
4. **Parallel computation** for cache initialization
5. **WebAssembly port** for browser execution
### Research Directions
- Formal analysis of error distribution
- Comparative study of computational efficiency
- Hybrid numerical methods
- Precision optimization techniques
## Conclusion
This implementation demonstrates practical applications of mathematical concepts in systems programming. The Fibonacci-based conversion methods provide a fascinating case study in approximation techniques, while the different implementation strategies (iterative, cached, closed-form) illustrate important optimization patterns.
The project exemplifies core software engineering principles:
- **DRY (Don't Repeat Yourself)**: Algorithmic reuse
- **KISS (Keep It Simple)**: Clean function boundaries
- **Robustness**: Comprehensive error handling
- **Efficiency**: Appropriate algorithm selection
By combining mathematical foundations with practical C implementation, this project serves as an educational resource for both computer science and computational mathematics.