{"id":30437466,"url":"https://github.com/alexeev-prog/fib_miles2km","last_synced_at":"2025-08-23T03:49:53.258Z","repository":{"id":305330229,"uuid":"1022569378","full_name":"alexeev-prog/fib_miles2km","owner":"alexeev-prog","description":"Converter from miles to km using Fibonacci series in C","archived":false,"fork":false,"pushed_at":"2025-07-31T03:38:14.000Z","size":46,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-31T06:38:28.383Z","etag":null,"topics":["c","computer-science","converter","fibonacci","fibonacci-numbers","fibonacci-sequence","mathematics","miles2km"],"latest_commit_sha":null,"homepage":"https://alexeev-prog.github.io/fib_miles2km/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexeev-prog.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-19T11:03:29.000Z","updated_at":"2025-07-31T03:38:17.000Z","dependencies_parsed_at":"2025-07-19T16:58:12.164Z","dependency_job_id":"60730707-f32c-4c68-8b51-cca44972c02a","html_url":"https://github.com/alexeev-prog/fib_miles2km","commit_stats":null,"previous_names":["alexeev-prog/fib_miles2km"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexeev-prog/fib_miles2km","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexeev-prog%2Ffib_miles2km","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexeev-prog%2Ffib_miles2km/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexeev-prog%2Ffib_miles2km/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexeev-prog%2Ffib_miles2km/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexeev-prog","download_url":"https://codeload.github.com/alexeev-prog/fib_miles2km/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexeev-prog%2Ffib_miles2km/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271740176,"owners_count":24812636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","computer-science","converter","fibonacci","fibonacci-numbers","fibonacci-sequence","mathematics","miles2km"],"created_at":"2025-08-23T03:49:52.430Z","updated_at":"2025-08-23T03:49:53.236Z","avatar_url":"https://github.com/alexeev-prog.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fib_miles2km: Advanced Distance Conversion Using Fibonacci Mathematics\n\nThanks to contributors:\n\n + [vitaliy-chernyshov](https://github.com/vitaliy-chernyshov)\n\n## Usage\n\n```\nAdvanced distance converter: miles to kilometers\nUsage: ./bin/fib_miles2km [OPTIONS] [distance]\n\nOptions:\n  -h, --help                     Show help information\n  -f, --fib=ARG                  Convert miles to km using basic Fibonacci\n  -b, --basic=ARG                Convert miles to km using standard formula\n  -i, --fib-interp=ARG           Convert using Fibonacci interpolation\n  -c, --fib-cache=ARG            Convert using cached Fibonacci\n  -g, --fib-golden=ARG           Convert using golden ratio\n```\n\n## Install\n\n```bash\ngit clone https://github.com/alexeev-prog/fib_miles2km\ncd fib_miles2km\nmake\n```\n\n## Technical Overview\n\nThis 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.\n\nThe core insight leverages the remarkable proximity between:\n- The golden ratio (φ ≈ 1.618034)\n- The exact miles-to-kilometers conversion factor (1.609344)\n\nThis 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.\n\n## Mathematical Foundations\n\n### Fibonacci Sequence\nThe Fibonacci sequence is defined by the recurrence relation:\n```\nF₀ = 0\nF₁ = 1\nFₙ = Fₙ₋₁ + Fₙ₋₂ for n ≥ 2\n```\nProducing: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89,...\n\n### Golden Ratio (φ)\nThe golden ratio emerges as the limit of consecutive Fibonacci ratios:\n```\nφ = lim (n→∞) Fₙ₊₁/Fₙ = (1 + √5)/2 ≈ 1.618034\n```\n\n### Conversion Relationship\nThe exact conversion factor is:\n```\n1 mile = 1.609344 kilometers\n```\nWith relative error between φ and the true factor:\n```\n(1.618034 - 1.609344)/1.609344 × 100% ≈ 0.54%\n```\n\n### Linear Interpolation\nFor values between Fibonacci numbers, we use linear interpolation:\n```\nkm = Fₖ₊₁ + (miles - Fₖ) × (Fₖ₊₂ - Fₖ₊₁)/(Fₖ₊₁ - Fₖ)\n```\nWhere:\n- Fₖ: Largest Fibonacci number ≤ miles\n- Fₖ₊₁: Next Fibonacci number\n- Fₖ₊₂: Subsequent Fibonacci number\n\n## Algorithmic Implementations\n\n### 1. Iterative Fibonacci with Interpolation\n\n**Core Algorithm** (`fib_interpolate` in `algorithms.c`):\n```c\nfloat fib_interpolate(float miles) {\n    if (miles \u003c 5.0f) return basic_miles2km(miles);\n\n    uint64_t prev_mile = 0;   // F₀\n    uint64_t prev_km = 1;     // F₁\n    uint64_t curr_mile = 1;   // F₁\n    uint64_t curr_km = 1;     // F₂\n\n    while (curr_mile \u003c= miles) {\n        uint64_t next_mile = curr_km;\n        uint64_t next_km = prev_km + curr_km;\n\n        if (next_km \u003c curr_km) break; // Overflow protection\n\n        prev_mile = curr_mile;\n        prev_km = curr_km;\n        curr_mile = next_mile;\n        curr_km = next_km;\n    }\n\n    return prev_km + (miles - prev_mile) *\n           ((float)(curr_km - prev_km) / (curr_mile - prev_mile));\n}\n```\n\n**Key Features**:\n- Dynamically computes Fibonacci numbers until bracketing the input value\n- Uses 64-bit integers for precision\n- Implements overflow protection\n- Falls back to exact conversion for values \u003c 5 miles\n- Time complexity: O(log φ(miles))\n\n**Example Execution**:\nFor 10 miles:\n1. Compute sequence: 0, 1, 1, 2, 3, 5, 8, 13\n2. Identify bracket: 8 ≤ 10 \u003c 13\n3. Interpolate between (8,13) and (13,21)\n4. Result: 16.2 km (vs exact 16.09344 km)\n\n### 2. Cached Fibonacci Conversion\n\n**Core Algorithm** (`fib_cache_convert` in `algorithms.c`):\n```c\nfloat fib_cache_convert(float miles) {\n    #define MAX_CACHE 94\n    static uint64_t cache[MAX_CACHE] = {0};\n    static int initialized = 0;\n\n    if (!initialized) {\n        cache[0] = 0;\n        cache[1] = 1;\n        for (int i = 2; i \u003c MAX_CACHE; i++) {\n            cache[i] = cache[i-1] + cache[i-2];\n        }\n        initialized = 1;\n    }\n\n    if (miles \u003c 5.0f) return basic_miles2km(miles);\n\n    int i = 1;\n    while (i \u003c MAX_CACHE-1 \u0026\u0026 cache[i] \u003c= miles) i++;\n\n    if (i \u003e= MAX_CACHE-1) return basic_miles2km(miles);\n\n    uint64_t F_prev = cache[i-1];\n    uint64_t F_curr = cache[i];\n    uint64_t F_next = cache[i+1];\n\n    return F_curr + (miles - F_prev) *\n           ((float)(F_next - F_curr) / (F_curr - F_prev));\n}\n```\n\n**Key Features**:\n- Precomputes Fibonacci numbers up to F₉₃ (max before 64-bit overflow)\n- Uses static cache for single initialization\n- Binary-compatible values ensure consistency\n- Constant-time lookup after initialization\n- Falls back to exact conversion when input exceeds cache range\n\n**Technical Notes**:\n- MAX_CACHE = 94 because F₉₃ = 12,200,160,415,121,876,738 (max for uint64_t)\n- Cache initialization occurs on first function call\n- Linear search through cache (O(n)) but n is small (94 elements)\n\n### 3. Golden Ratio Conversion (Binet's Formula)\n\n**Core Algorithm** (`fib_golden_ratio` in `algorithms.c`):\n```c\nfloat fib_golden_ratio(float miles) {\n    const double sqrt5 = sqrt(5.0);\n    const double phi = (1.0 + sqrt5) / 2.0;\n\n    if (miles \u003c 1e-5) return 0.0f;\n\n    double n = log(miles * sqrt5) / log(phi);\n    int k = (int)floor(n);\n\n    double F_k = (pow(phi, k) - pow(-phi, -k)) / sqrt5;\n    double F_k1 = (pow(phi, k+1) - pow(-phi, -k-1)) / sqrt5;\n    double F_k2 = (pow(phi, k+2) - pow(-phi, -k-2)) / sqrt5;\n\n    return F_k1 + (miles - F_k) *\n           ((float)(F_k2 - F_k1) / (F_k1 - F_k));\n}\n```\n\n**Key Features**:\n- Direct implementation of Binet's closed-form formula\n- Uses logarithmic calculation to find Fibonacci index\n- Handles non-integer inputs naturally\n- Subject to floating-point precision limitations\n- Requires linking with math library (-lm)\n\n**Precision Considerations**:\n- Double precision maintains accuracy until ~F₇₀\n- Relative error increases exponentially beyond F₇₈\n- Edge case handling prevents division by zero\n\n## Command-Line Interface Architecture\n\nThe command parser implements a POSIX-style option processing system:\n\n### Option Configuration Structure\n```c\nstruct CommandOption {\n    const char* help;\n    const char* long_name;\n    char short_name;\n    int has_arg;\n    const char* default_value;\n    void* handler;\n};\n```\n\n### Conflict Detection Logic\n```c\nint fib_methods_count = 0;\nif (fib_value) fib_methods_count++;\nif (fib_interp_value) fib_methods_count++;\n// ... check other methods\n\nif (fib_methods_count \u003e 1) {\n    fprintf(stderr, \"Error: Use only one Fibonacci conversion method\\n\");\n    return EXIT_FAILURE;\n}\n```\n\n### Input Validation\n```c\nchar* endptr;\ndouble miles = strtod(input_value, \u0026endptr);\nif (*endptr != '\\0' || miles \u003c 0) {\n    fprintf(stderr, \"Error: Invalid distance value '%s'\\n\", input_value);\n    return EXIT_FAILURE;\n}\n```\n\n## Error Handling System\n\nComprehensive checks include:\n- Invalid numeric inputs\n- Negative distance values\n- Conflicting conversion methods\n- Integer overflow protection\n- Floating-point underflow/overflow\n- Mathematical domain errors\n- Memory boundary checks\n\n```c\n// In golden ratio implementation\nif (F_k1 - F_k \u003c DBL_EPSILON) {\n    return basic_miles2km(miles); // Fallback to prevent division by zero\n}\n```\n\n## Build and Execution\n\n### Compilation\n```bash\ngcc -Wall -Wextra -O2 -lm src/*.c -o bin/fib_miles2km\n```\n\n### Execution Examples\n```bash\n# Fibonacci interpolation (default)\n./bin/fib_miles2km 21\n\n# Cached Fibonacci conversion\n./bin/fib_miles2km --fib-cache 34.7\n\n# Golden ratio conversion\n./bin/fib_miles2km --fib-golden 55.3\n\n# Standard conversion\n./bin/fib_miles2km --basic 100\n```\n\n### Output Samples\n```\n21.00 miles = 33.80 km (Basic convert)\n21.00 miles ≈ 34.00 km (Fibonacci interpolation)\n34.70 miles ≈ 55.82 km (Cached Fibonacci)\n55.30 miles ≈ 89.11 km (Golden Ratio)\n100.00 miles = 160.93 km\n```\n\n## Performance Characteristics\n\n| Method          | Time Complexity | Space Complexity | Max Input (miles) | Precision        |\n|-----------------|-----------------|------------------|-------------------|------------------|\n| Basic           | O(1)            | O(1)             | ∞                 | Exact            |\n| Interpolation   | O(log φ(n))     | O(1)             | F₉₂ ≈ 7.5e19      | ~0.54% error     |\n| Cached          | O(1)            | O(94)            | F₉₂ ≈ 7.5e19      | ~0.54% error     |\n| Golden Ratio    | O(1)            | O(1)             | ∞                 | Degrades with n  |\n\n## Limitations and Future Work\n\n### Current Limitations\n- Golden ratio method precision limited by double-precision floating point\n- Maximum input 93 miles for integer-based methods\n- No multi-threading support\n- Limited error statistics collection\n\n### Enhancement Opportunities\n1. **Arbitrary-precision arithmetic** for larger values\n2. **Hybrid approaches** combining multiple methods\n3. **Error correction** using machine learning\n4. **Parallel computation** for cache initialization\n5. **WebAssembly port** for browser execution\n\n### Research Directions\n- Formal analysis of error distribution\n- Comparative study of computational efficiency\n- Hybrid numerical methods\n- Precision optimization techniques\n\n## Conclusion\n\nThis 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.\n\nThe project exemplifies core software engineering principles:\n- **DRY (Don't Repeat Yourself)**: Algorithmic reuse\n- **KISS (Keep It Simple)**: Clean function boundaries\n- **Robustness**: Comprehensive error handling\n- **Efficiency**: Appropriate algorithm selection\n\nBy combining mathematical foundations with practical C implementation, this project serves as an educational resource for both computer science and computational mathematics.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexeev-prog%2Ffib_miles2km","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexeev-prog%2Ffib_miles2km","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexeev-prog%2Ffib_miles2km/lists"}