clarify docs, bump version number

README.md

@@ -65,7 +65,29 @@ approx runtime:
 
 ## tips
 
-* `quickseries.benchmark()` offers an easy way to test the accuracy and
+* Multivariate `quickseries()`-generated functions always map positional arguments
+  to variables in the string representation of the input function in alphanumeric
+  order. This is in order to maintain consistency between slightly different 
+  forms of the same expression.
+  * Examples:
+    * `quickseries("cos(x) * sin(y)")(1, 2)` approximates `sin(1) * cos(2)`
+    * `quickseries("sin(y) * cos(x)")(1, 2)` approximates `cos(1) * sin(2)` 
+    * `quickseries("sin(x) * cos(y)")(1, 2)` approximates `sin(1) * cos(2)`
+  * Note that you can always determine the argument order of a `quickseries()`-
+    generated function by using the `help()` builtin, `inspect.getfullargspec()`,
+    examining the function's docstring, etc.
+* Most legal Python variable names are allowable names for free variables.
+  Named mathematical functions and constants are the major exceptions.
+  * Examples:
+    * `"ln(_)"`, `"ln(One_kitty)"`, `"ln(x0)"`, and `"ln(ă)"` will all work fine.
+    * `"ln(if)"` and `"ln(🔥)"` will both fail, because `if` and `🔥` are not
+      legal Python variable names.
+    * `"ln(gamma)"` will fail, because `quickseries()` will interpret "gamma"
+      as the gamma function.
+    * `"cos(x) * cos(pi * 2)"` will succeed, but `quickseries()` will interpret 
+      it as "the cosine of a variable named 'x' times the cosine of two times
+      the mathematical constant pi" -- in other words, as `"cos(x)"`.
+  * `quickseries.benchmark()` offers an easy way to test the accuracy and
   efficiency of `quickseries.quickseries()`-generated functions.
 * Narrowing `bounds` will tend to make the approximation more accurate within
 those bounds. In the example above, setting `bounds` to `(-1, 1)` provides 

quickseries/__init__.py

@@ -1,4 +1,4 @@
 from quickseries.approximate import quickseries
 from quickseries.benchmark import benchmark
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

quickseries/sourceutils.py

@@ -9,6 +9,7 @@
 
 from dustgoggles.dynamic import define, get_codechild
 
+
 CACHE_ARGS = (
     "func",
     "bounds",
@@ -42,11 +43,16 @@ def _cachedir(callfile: str) -> Path:
 
 
 def _cachekey(args, callfile=None):
+    from quickseries import __version__
+
     # TODO: is this actually stable?
     arghash = pickle.dumps(
-        {a: args.locals[a] for a in sorted(CACHE_ARGS)} | {'f': callfile}
+        {a: args.locals[a] for a in sorted(CACHE_ARGS)}
+        | {'f': callfile, '__version__': __version__}
     )
-    return f"quickseries_{md5(arghash).hexdigest()}"
+    # arbitrary cutoff for a reasonable tradeoff between collision safety and
+    # readability
+    return f"quickseries_{md5(arghash).hexdigest()}"[:-18]
 
 
 # TODO, maybe: the frame traversal is potentially wasteful when repeated,

setup.py

@@ -2,7 +2,7 @@
 
 setup(
     name="quickseries",
-    version="0.1.1",
+    version="0.2.0",
     packages=find_packages(),
     url="https://github.com/millionconcepts/quickseries.git",
     author="Michael St. Clair",