{"id":17626618,"url":"https://github.com/georgy7/toyfloat","last_synced_at":"2025-03-30T02:20:38.376Z","repository":{"id":57645569,"uuid":"439841500","full_name":"georgy7/toyfloat","owner":"georgy7","description":"A library that encodes 3 to 16 bits wide floating-point numbers.","archived":false,"fork":false,"pushed_at":"2022-02-14T01:37:53.000Z","size":1594,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-05T04:45:32.600Z","etag":null,"topics":["floating-point","half-precision","minifloat","quantization"],"latest_commit_sha":null,"homepage":"","language":"Go","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/georgy7.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-19T11:07:48.000Z","updated_at":"2022-01-13T19:45:22.000Z","dependencies_parsed_at":"2022-09-08T15:11:58.408Z","dependency_job_id":null,"html_url":"https://github.com/georgy7/toyfloat","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgy7%2Ftoyfloat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgy7%2Ftoyfloat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgy7%2Ftoyfloat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgy7%2Ftoyfloat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/georgy7","download_url":"https://codeload.github.com/georgy7/toyfloat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246266478,"owners_count":20749807,"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","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":["floating-point","half-precision","minifloat","quantization"],"created_at":"2024-10-22T23:07:18.310Z","updated_at":"2025-03-30T02:20:38.356Z","avatar_url":"https://github.com/georgy7.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Toyfloat\n\nIt encodes and decodes floating-point numbers with a width of 3 to 16 bits.\n\nExpected applications:\n\n* file format design,\n* lossy compression.\n\nIt has:\n\n* exact 0, 1, -1\n* no NaN, -Inf, +Inf\n* values, that are in range about:\n  * (-256, +256) for 4-bit exponent\n  * (-4, +4) for 3-bit exponent\n  * (-3, +3) for 2-bit exponent\n  * up to 10^308 (custom settings).\n\n![Formula](images/formula.png)\n\nBase 3 in 2-bit exponent provides a higher density\nof values close to zero and a wider range,\nat the cost of reduced precision of values greater than one-third.\n\nYou can also choose other settings.\n\n```\nExamples:\n\n____ sxxx xmmm mmmm - 12-bit\n____ xxxx mmmm mmmm - 12-bit unsigned\n___s xxxx mmmm mmmm - 13-bit\n__sx xxxm mmmm mmmm - 14-bit\n_sxx xmmm mmmm mmmm - 15-bit with 3-bit exponent\n```\n\n![Precision graph](images/comparison.png)\n\n## Usage\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/georgy7/toyfloat\"\n\t\"math\"\n\t\"os\"\n)\n\nfunc exitOnError(err error) {\n\tif err != nil {\n\t\tfmt.Println(\"impossible type\")\n\t\tos.Exit(1)\n\t}\n}\n\nfunc printHeader(header string) {\n\tfmt.Println(header)\n\tfor i := 0; i \u003c len(header); i++ {\n\t\tfmt.Print(\"-\")\n\t}\n\tfmt.Println()\n}\n\nfunc report(t toyfloat.Type, value float64) {\n\tencoded := t.Encode(value)\n\tcomparable := t.ToComparable(encoded)\n\tdecoded := t.Decode(encoded)\n\tfmt.Printf(\"Input:      %f\\n\", value)\n\tfmt.Printf(\"Encoded:    0x%X\\n\", encoded)\n\tfmt.Printf(\"Comparable: 0x%X\\n\", comparable)\n\tfmt.Printf(\"Decoded:    %f\\n\", decoded)\n\tfmt.Printf(\"Error:      %f\\n\", math.Abs(value-decoded))\n\tfmt.Printf(\"Relative:   %f\\n\\n\", math.Abs((value-decoded)/value))\n}\n\nfunc main() {\n\tfmt.Println()\n\n\ttoyfloat12, err12 := toyfloat.NewTypeX4(12, true)\n\ttoyfloat5x3, err5x3 := toyfloat.NewTypeX3(5, true)\n\ttoyfloat3x2u, err3x2u := toyfloat.NewTypeX2(3, false)\n\td8x3, errD8x3 := toyfloat.NewType(8, 10, 3, -2, true)\n\n\texitOnError(err12)\n\texitOnError(err5x3)\n\texitOnError(err3x2u)\n\texitOnError(errD8x3)\n\n\tconst input = 1.567\n\n\tprintHeader(\"12-bit signed\")\n\treport(toyfloat12, input)\n\n\tprintHeader(\"5-bit signed with 3-bit exponent\")\n\treport(toyfloat5x3, input)\n\n\tprintHeader(\"3-bit unsigned with 2-bit exponent\")\n\treport(toyfloat3x2u, input)\n\n\tprintHeader(\"8-bit with base 10 exponent (-2..5)\")\n\treport(d8x3, input/10)\n\treport(d8x3, input)\n\treport(d8x3, 65536)\n\treport(d8x3, -7.5e5)\n\treport(d8x3, 1e6)\n\n\tfmt.Println()\n\tfmt.Println(\"Delta encoding (12-bit)\")\n\tfmt.Println(\"-----------------------\")\n\tfmt.Println()\n\n\tseries := []float64{\n\t\t-0.0058, 0.01, -0.0058, 0.01, 0.066, 0.123,\n\t\t0.134, 0.132, 0.144, 0.145, 0.140}\n\n\tprevious := toyfloat12.Encode(series[0])\n\tcPrevious := toyfloat12.ToComparable(previous)\n\n\tpDecoded := toyfloat12.Decode(previous)\n\n\tfmt.Printf(\"  Int. delta    Unsigned    Fp delta    Value\\n\")\n\tfmt.Printf(\"  % 47.6f\\n\", pDecoded)\n\n\tfor i := 1; i \u003c len(series); i++ {\n\t\tthis := toyfloat12.Encode(series[i])\n\t\tcThis := toyfloat12.ToComparable(this)\n\n\t\tdelta := toyfloat12.GetIntegerDelta(previous, this)\n\t\tunsignedDelta := cThis - cPrevious\n\n\t\tx := toyfloat12.Decode(this)\n\t\tfpDelta := x - pDecoded\n\t\tfmt.Printf(\"  %+10d    %8d    %+.6f   % .6f\\n\",\n\t\t\tdelta, unsignedDelta, fpDelta, x)\n\n\t\tprevious = this\n\t\tcPrevious = toyfloat12.ToComparable(previous)\n\n\t\tpDecoded = toyfloat12.Decode(previous)\n\t}\n\n\tfmt.Println()\n}\n```\n\n```shell\ngo get -u github.com/georgy7/toyfloat\ngo run example.go\n```\n\n```\n12-bit signed\n-------------\nInput:      1.567000\nEncoded:    0x448\nComparable: 0xC48\nDecoded:    1.564706\nError:      0.002294\nRelative:   0.001464\n\n5-bit signed with 3-bit exponent\n--------------------------------\nInput:      1.567000\nEncoded:    0xD\nComparable: 0x1D\nDecoded:    1.507937\nError:      0.059063\nRelative:   0.037692\n\n3-bit unsigned with 2-bit exponent\n----------------------------------\nInput:      1.567000\nEncoded:    0x7\nComparable: 0x7\nDecoded:    2.038462\nError:      0.471462\nRelative:   0.300869\n\n8-bit with base 10 exponent (-2..5)\n-----------------------------------\nInput:      0.156700\nEncoded:    0x11\nComparable: 0x91\nDecoded:    0.147727\nError:      0.008973\nRelative:   0.057261\n\nInput:      1.567000\nEncoded:    0x21\nComparable: 0xA1\nDecoded:    1.568182\nError:      0.001182\nRelative:   0.000754\n\nInput:      65536.000000\nEncoded:    0x6A\nComparable: 0xEA\nDecoded:    66919.181818\nError:      1383.181818\nRelative:   0.021106\n\nInput:      -750000.000000\nEncoded:    0xFB\nComparable: 0x4\nDecoded:    -726010.090909\nError:      23989.909091\nRelative:   0.031987\n\nInput:      1000000.000000\nEncoded:    0x7F\nComparable: 0xFF\nDecoded:    953282.818182\nError:      46717.181818\nRelative:   0.046717\n\n\nDelta encoding (12-bit)\n-----------------------\n\n  Int. delta    Unsigned    Fp delta    Value\n                                        -0.005821\n        +387         387    +0.015809    0.009988\n        -387       65149    -0.015809   -0.005821\n        +387         387    +0.015809    0.009988\n        +300         300    +0.056189    0.066176\n        +114         114    +0.056373    0.122549\n         +12          12    +0.011765    0.134314\n          -2       65534    -0.001961    0.132353\n         +12          12    +0.011765    0.144118\n          +1           1    +0.000980    0.145098\n          -5       65531    -0.004902    0.140196\n```\n\n## Performance\n\n```\nBenchmarkFloat64IncrementAsAReference-8     1000000000           1.09 ns/op\nBenchmarkCreateTypeX4-8                      3917901           299 ns/op\nBenchmarkCreateTypeX3-8                     11907438           103 ns/op\nBenchmarkCreateTypeX2-8                     13006556            92.4 ns/op\nBenchmarkEncode-8                           90582355            13.2 ns/op\nBenchmarkDecode-8                           229913229            5.15 ns/op\nBenchmarkEncode12X2-8                       94929739            12.4 ns/op\nBenchmarkDecode12X2-8                       236135440            5.40 ns/op\nBenchmarkGetDelta-8                         540333522            2.19 ns/op\nBenchmarkGetDeltaX2-8                       603912135            1.86 ns/op\nBenchmarkUseDelta-8                         263490146            4.53 ns/op\nBenchmarkUseDeltaX2-8                       249798333            4.54 ns/op\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgy7%2Ftoyfloat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorgy7%2Ftoyfloat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgy7%2Ftoyfloat/lists"}