document negligible

doc/user.rst

@@ -2090,6 +2090,9 @@ you use 'full' precision:
     Applying stimulus @ 200.5us: V(in) = 500mV.
     Pass @ 300.5us: V(out): expected=2V, measured=1.99999965V, diff=346.11713nV.
 
+.. ignore
+    >>> Quantity.set_prefs(spacer=' ')
+
 
 .. index::
    single: equivalence
@@ -2137,6 +2140,48 @@ behavior can be overridden by specifying *check_units*.
    True
 
 
+.. index::
+   single: negligible
+
+.. _negligible values:
+
+Negligible Values
+-----------------
+
+*QuantiPhy* can round small values to zero, which can help to reduce visual 
+clutter.  You can specify the size of a negligible value as a preference using 
+:meth:`Quantity.set_prefs` or :meth:`Quantity.prefs`, or you can specify it 
+locally using:meth:`Quantity.render`.  Any quantity whose absolute value is 
+smaller than the specified value is rendered as zero with the underlying value 
+remaining unchanged.
+
+
+.. code-block:: python
+
+   >>> from quantiphy import Quantity
+   >>> from math import exp
+
+   >>> Vt = 0.025852
+   >>> def cond(v):
+   ...     return Quantity(1e-27 * exp(v/Vt)/Vt, 'Ʊ')
+
+   >>> Quantity.set_prefs(prec=2)
+   >>> for i in range(11):
+   ...     v = Quantity(i/5, 'V')
+   ...     print(f'{v:>6}: {cond(v):>10}, {v:>26}: {cond(v).render(negligible=1e-3):>10}')
+      0 V: 38.7e-27 Ʊ,                        0 V:        0 Ʊ
+   200 mV: 88.6e-24 Ʊ,                     200 mV:        0 Ʊ
+   400 mV:  203e-21 Ʊ,                     400 mV:        0 Ʊ
+   600 mV:     465 aƱ,                     600 mV:        0 Ʊ
+   800 mV:    1.06 pƱ,                     800 mV:        0 Ʊ
+      1 V:    2.44 nƱ,                        1 V:        0 Ʊ
+    1.2 V:    5.58 uƱ,                      1.2 V:        0 Ʊ
+    1.4 V:    12.8 mƱ,                      1.4 V:    12.8 mƱ
+    1.6 V:     29.3 Ʊ,                      1.6 V:     29.3 Ʊ
+    1.8 V:      67 kƱ,                      1.8 V:      67 kƱ
+      2 V:     153 MƱ,                        2 V:     153 MƱ
+
+
 .. index::
    single: infinity
    single: not a number

quantiphy.py

@@ -2231,7 +2231,7 @@ def render(
                 negligible = negligible.get(self.units, negligible.get(None, -1))
             except AttributeError:
                 pass
-            if abs(self.real) <= negligible:
+            if abs(self.real) < negligible:
                 mantissa = '0'
                 exp = 0
                 sign = ''

tests/test_doctests.py

@@ -30,18 +30,18 @@ def test_manual():
         # code used in doctests assumes python3.6
         return
     Quantity.reset_prefs()
-    files = {
+    expected_test_count = {
         '../doc/index.rst': 29,
-        '../doc/user.rst': 361,
+        '../doc/user.rst': 368,
         '../doc/api.rst': 0,
         '../doc/examples.rst': 36,
         '../doc/accessories.rst': 12,
         '../doc/releases.rst': 0,
     }
     found = glob.glob('../doc/*.rst')
     for f in found:
-        assert f in files, f
-    for path, tests in files.items():
+        assert f in expected_test_count, f
+    for path, tests in expected_test_count.items():
         rv = doctest.testfile(path, optionflags=doctest.ELLIPSIS)
         assert rv.failed == 0, path
         assert rv.attempted == tests, path