README.md (5406B)
1 # A minimalist calculator for fermi estimation 2 3 This project is a minimalist, calculator-style DSL for fermi estimation. It can multiply, divide, add and substract scalars, lognormals and beta distributions. 4 5 ## Motivation 6 7 Sometimes, [Squiggle](https://github.com/quantified-uncertainty/squiggle), [simple squiggle](https://git.nunosempere.com/quantified.uncertainty/simple-squiggle) or [squiggle.c](https://git.nunosempere.com/personal/squiggle.c) are still too complicated and un-unix-like. 8 9 ## Installation 10 11 ``` 12 make build 13 sudo make install 14 fermi 15 ``` 16 17 ## Usage 18 19 ``` 20 $ fermi 21 5000000 12000000 22 => 5.0M 12.0M 23 * beta 1 200 24 1.9K 123.1K 25 * 30 180 26 122.9K 11.7M 27 / 48 52 28 2.5K 234.6K 29 / 5 6 30 448.8 43.0K 31 / 6 8 32 64.5 6.2K 33 / 60 34 1.1 103.7 35 ``` 36 37 Perhaps this example is more understandable with comments and better units: 38 39 ``` 40 $ fermi 41 5M 12M # number of people living in Chicago 42 => 5.0M 12.0M 43 * beta 1 200 # fraction of people that have a piano 44 1.9K 123.1K 45 30 180 # minutes it takes to tune a piano, including travel time 46 122.9K 11.7M 47 / 48 52 # weeks a year pianotuners work for 48 2.5K 234.6K 49 / 6 8 # hours a day 50 353.9 34.1K 51 / 60 # minutes to an hour 52 5.9 568.3 53 =: piano_tuners_in_Chicago 54 piano_tuners_in_Chicago => 5.9 568.3 55 ``` 56 57 Here is instead an example using beta distributions and variables: 58 59 ``` 60 $ fermi 61 1 2 62 => 1.0 2.0 63 * 1_000_000_000 64 => 1000.0M 2.0B 65 =: x # assign to variable 66 x => 1000.0M 2.0B 67 . # clear the stack, i.e., make it be 1 68 69 beta 1 2 70 => beta 1.0 2.0 71 beta 12 300 72 => beta 13.0 302.0 73 =. y # assign to variable and clear the stack (return it to 1) 74 y => beta 13.0 302.0 75 76 x 77 => 1000.0M 2.0B 78 * y 79 => samples 31.3M 98.2M 80 ``` 81 82 The difference between `=: x` and `=. y` is that `=.` clears the stack after the assignment. 83 84 If you type "help", you can see a small grammar: 85 86 ``` 87 $ fermi 88 help 89 Operation | Variable assignment | Special 90 Operation: operator operand 91 operator: (empty) | * | / | + | - 92 operand: scalar | lognormal | beta | variable 93 lognormal: low high 94 beta: beta alpha beta 95 Variable assignment: =: variable_name 96 Variable assignment and clear stack: =. variable_name 97 Special: 98 Clear stack: clear | c | . 99 Print this help message: help | h 100 Print debug info: debug | d 101 Exit: exit | e 102 Comment: # this is a comment 103 Examples: 104 + 2 105 / 2.5 106 * 1 10 (interpreted as lognormal) 107 + 1 10 108 * beta 1 10 109 1 10 (multiplication taken as default operation) 110 =: x 111 . 112 1 100 113 + x 114 # this is a comment 115 * 1 12 # this is an operation followed by a comment 116 exit 117 ``` 118 119 ## Tips & tricks 120 121 - It's conceptually clearer to have all the multiplications first and then all the divisions 122 - For things between 0 and 1, consider using a beta distribution 123 - Because the model reads from standard input, you can pipe a model to it. For instance, try cat more/piano-tuners.f | fermi 124 125 ## Different levels of complexity 126 127 The top level f.go file (400 lines) has a bunch of complexity: variables, parenthesis, samples, beta distributions. In the simple/ folder: 128 129 - f_simple.go (370 lines) strips variables and parenthesis, but keeps beta distributions, samples, and addition and substraction 130 - f_minimal.go (140 lines) strips everything that isn't lognormal and scalar multiplication and addition, plus a few debug options. 131 132 ## Roadmap 133 134 Done: 135 136 - [x] Write README 137 - [x] Add division? 138 - [x] Read from file? 139 - [x] Save to file? 140 - [x] Allow comments? 141 - [x] Use a sed filter? 142 - [x] Add proper comment processing 143 - [x] Add show more info version 144 - [x] Scalar multiplication and division 145 - [x] Think how to integrate with squiggle.c to draw samples 146 - [x] Copy the time to botec go code 147 - [x] Define samplers 148 - [x] Call those samplers when operating on distributions that can't be operted on algebraically 149 - [x] Display output more nicely, with K/M/B/T 150 - [x] Consider the following: make this into a stack-based DSL, with: 151 - [x] Variables that can be saved to and then displayed 152 - [x] Other types of distributions, particularly beta distributions? => But then this requires moving to bags of samples. It could still be ~instantaneous though. 153 - [x] Added bags of samples to support addition and multiplication of betas and lognormals 154 - [x] Figure out go syntax for 155 - Maps 156 - Joint types 157 - Enums 158 - [x] Fix correlation problem, by spinning up a new randomness thing every time some serial computation is done. 159 - [x] Clean up error code. Right now only needed for division 160 - [x] Maintain *both* a more complex thing that's more featureful *and* the more simple multiplication of lognormals thing. 161 - [x] Allow input with K/M/T 162 163 To (possibly) do: 164 165 - [ ] Specify number of samples as a command line option 166 - [ ] Document parenthesis syntax 167 - [ ] Add functions. Now easier to do with an explicit representation of the stakc 168 - [ ] Think about how to draw a histogram from samples 169 - [ ] Dump samples to file 170 - [ ] Represent samples/statistics in some other way 171 - [ ] Perhaps use qsort rather than full sorting 172 - [ ] Program into a small device, like a calculator? 173 174 Discarded: 175 176 - [ ] ~~Think of some way of calling bc~~