From 5b3efdb76a03a04ccad30dbd37828b390feda23c Mon Sep 17 00:00:00 2001 From: SheetJS Date: Sat, 14 Dec 2013 02:11:37 -0500 Subject: [PATCH] Initial commit --- .travis.yml | 6 +++ LICENSE | 12 +++++ Makefile | 6 +++ README.md | 32 +++++++++++++ frac.js | 20 +++++++++ frac.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 19 ++++++++ test.js | 2 + 8 files changed, 222 insertions(+) create mode 100644 .travis.yml create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.md create mode 100644 frac.js create mode 100644 frac.md create mode 100644 package.json create mode 100644 test.js diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..a1f55b5 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,6 @@ +language: node_js +node_js: + - "0.10" + - "0.8" +before_install: + - "npm install -g mocha" diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c038b84 --- /dev/null +++ b/LICENSE @@ -0,0 +1,12 @@ +Copyright (C) 2013 SheetJS + +The MIT License (MIT) + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + +Except where noted, this license applies to any and all software programs and associated documentation files created by the Original Author and distributed with the Software. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..7ad878d --- /dev/null +++ b/Makefile @@ -0,0 +1,6 @@ +frac.js: frac.md + voc frac.md + +.PHONY: test +test: + mocha -R spec diff --git a/README.md b/README.md new file mode 100644 index 0000000..070bbe9 --- /dev/null +++ b/README.md @@ -0,0 +1,32 @@ +# frac + +Rational approximation to a floating point number with bounded denominator. + +Uses the Mediant Method + +## JS Installation and Usage + +In node: + + $ npm install frac + +In the browser: + + + +The exported `frac` function takes three arguments: + + - `x` the number we wish to approximate + - `D` the maximum denominator + - `mixed` if true, return a mixed fraction (default); if false, improper + +The return value is an array of the form `[quot, num, den]` where `quot==0` +for improper fractions. + +For example: + +``` +> // var frac = require('frac'); // uncomment this line if in node +> frac(Math.PI,100) // [ 0, 22, 7 ] +> frac(Math.PI,100,true) // [ 3, 1, 7 ] +``` diff --git a/frac.js b/frac.js new file mode 100644 index 0000000..0451e66 --- /dev/null +++ b/frac.js @@ -0,0 +1,20 @@ +var frac = function(x, D, mixed) { + var n1 = Math.floor(x), d1 = 1; + var n2 = n1+1, d2 = 1; + if(x !== n1) while(d1 <= D && d2 <= D) { + var m = (n1 + n2) / (d1 + d2); + if(x === m) { + if(d1 + d2 <= D) d1+=d2, n1+=n2, d2=D+1; + else if(d1 > d2) d2=D+1; + else d1=D+1; + break; + } + else if(x < m) n2 = n1+n2, d2 = d1+d2; + else n1 = n1+n2, d1 = d1+d2; + } + if(d1 > D) d1 = d2, n1 = n2; + if(!mixed) return [0, n1, d1]; + var q = Math.floor(n1/d1); + return [q, n1 - q*d1, d1]; +}; +if(typeof module !== undefined) module.exports = frac; diff --git a/frac.md b/frac.md new file mode 100644 index 0000000..2d8f76f --- /dev/null +++ b/frac.md @@ -0,0 +1,125 @@ +# Target + +In all languages, the target is a function that takes 3 parameters: + + - `x` the number we wish to approximate + - `D` the maximum denominator + - `mixed` if true, return a mixed fraction (default); if false, improper + +The JS implementation walks through the algorithm. + +# JS Implementation + +In this version, the return value is `[quotient, numerator, denominator]`, +where `quotient == 0` for improper fractions. The interpretation is +`x ~ quotient + numerator / denominator` where `0 <= numerator < denominator` +and `quotient <= x` for negative `x`. + +```js>frac.js +var frac = function(x, D, mixed) { +``` + +The goal is to maintain a feasible fraction (with bounded denominator) below +the target and another fraction above the target. The lower bound is +`floor(x) / 1` and the upper bound is `(floor(x) + 1) / 1`. We keep track of +the numerators and denominators separately: + +``` + var n1 = Math.floor(x), d1 = 1; + var n2 = n1+1, d2 = 1; +``` + +If `x` is not integral, we bisect using mediants until a denominator exceeds +our target: + +``` + if(x !== n1) while(d1 <= D && d2 <= D) { +``` + +The mediant is the sum of the numerators divided by the sum of demoninators: + +``` + var m = (n1 + n2) / (d1 + d2); +``` + +If we happened to stumble upon the exact value, then we choose the closer one +(the mediant if the denominator is within bounds, or the bound with the larger +denominator) + +``` + if(x === m) { + if(d1 + d2 <= D) d1+=d2, n1+=n2, d2=D+1; + else if(d1 > d2) d2=D+1; + else d1=D+1; + break; + } +``` + +Otherwise shrink the range: + +``` + else if(x < m) n2 = n1+n2, d2 = d1+d2; + else n1 = n1+n2, d1 = d1+d2; + } +``` + +At this point, `d1 > D` or `d2 > D` (but not both -- keep track of how `d1` and +`d2` change). So we merely return the desired values: + +``` + if(d1 > D) d1 = d2, n1 = n2; + if(!mixed) return [0, n1, d1]; + var q = Math.floor(n1/d1); + return [q, n1 - q*d1, d1]; +}; +``` + +Finally we put some export jazz: + +``` +if(typeof module !== undefined) module.exports = frac; +``` + +# Tests + +```js>test.js +var frac; +describe('source', function() { it('should load', function() { frac = require('./'); }); }); +``` + +# Miscellany + +```make>Makefile +frac.js: frac.md + voc frac.md + +.PHONY: test +test: + mocha -R spec +``` + +## Node Ilk + +```json>package.json +{ + "name": "frac", + "version": "0.1.0", + "author": "SheetJS", + "description": "Rational approximation with bounded denominator", + "keywords": [ "math", "fraction", "rational", "approximation" ], + "main": "./frac.js", + "dependencies": {}, + "devDependencies": {"mocha":""}, + "repository": { + "type":"git", + "url": "git://github.com/SheetJS/frac.git" + }, + "scripts": { + "test": "make test" + }, + "bugs": { "url": "https://github.com/SheetJS/frac/issues" }, + "engines": { "node": ">=0.8" } +} +``` + + diff --git a/package.json b/package.json new file mode 100644 index 0000000..064e49c --- /dev/null +++ b/package.json @@ -0,0 +1,19 @@ +{ + "name": "frac", + "version": "0.1.0", + "author": "SheetJS", + "description": "Rational approximation with bounded denominator", + "keywords": [ "math", "fraction", "rational", "approximation" ], + "main": "./frac.js", + "dependencies": {}, + "devDependencies": {"mocha":""}, + "repository": { + "type":"git", + "url": "git://github.com/SheetJS/frac.git" + }, + "scripts": { + "test": "make test" + }, + "bugs": { "url": "https://github.com/SheetJS/frac/issues" }, + "engines": { "node": ">=0.8" } +} diff --git a/test.js b/test.js new file mode 100644 index 0000000..73d9f6e --- /dev/null +++ b/test.js @@ -0,0 +1,2 @@ +var frac; +describe('source', function() { it('should load', function() { frac = require('./'); }); });