pyqrack-complex128 2.18.2__tar.gz → 2.18.3__tar.gz

{pyqrack_complex128-2.18.2/pyqrack_complex128.egg-info → pyqrack_complex128-2.18.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyqrack-complex128
-Version: 2.18.2
+Version: 2.18.3
 Summary: pyqrack - Pure Python vm6502q/qrack Wrapper
 Home-page: https://github.com/vm6502q/pyqrack
 Author: Daniel Strano

{pyqrack_complex128-2.18.2 → pyqrack_complex128-2.18.3}/pyqrack/qrack_ace_backend.py

@@ -274,11 +274,11 @@ class QrackAceBackend:
         if "QRACK_FPPOW" in os.environ:
             fppow = int(os.environ.get("QRACK_FPPOW"))
         if fppow < 5:
-            self._epsilon = 2**-9
+            self._epsilon = 2**-8
         elif fppow > 5:
-            self._epsilon = 2**-51
+            self._epsilon = 2**-50
         else:
-            self._epsilon = 2**-22
+            self._epsilon = 2**-21
 
         self._coupling_map = None
 
@@ -406,18 +406,57 @@ class QrackAceBackend:
             sim_counts.append(boundary_count)
 
         # Error-detection gadget (IBM-style detect-and-post-select, not
-        # correction): one shared ancilla per simulator -- every patch AND
+        # correction): two shared ancillae per simulator -- every patch AND
         # the boundary crossbar sim alike, "a single ancilla per patch,
         # overall" -- reused across every real (same-simulator) coupling
         # gate that touches it, never allocated per-gate or per-qubit.
         # See _apply_coupling for the actual gadget; this block only does
         # the qubit-index bookkeeping, in the same style as every other
         # per-simulator allocation above.
-        self._detect_ancilla = []
+        self._detect_ancilla1 = []
+        self._detect_ancilla2 = []
         if self.is_error_detection:
             for i in range(len(sim_counts)):
-                self._detect_ancilla.append(sim_counts[i])
+                self._detect_ancilla1.append(sim_counts[i])
                 sim_counts[i] += 1
+                self._detect_ancilla2.append(sim_counts[i])
+                sim_counts[i] += 1
+
+        # Logical-qubit wrapper around each patch's detection ancilla,
+        # so it's addressable via the ORDINARY cx()/_cpauli() machinery
+        # (self.cx(lq1, anc)), not just raw (sim, idx) tuples. Appended
+        # PAST the user-facing qubit range (num_qubits() is computed
+        # independently from the grid dimensions, not from len(
+        # self._qubits), so these extra entries are never visible or
+        # reachable through the normal API) -- a simple, single-replica
+        # (bulk-style) logical qubit per simulator, one entry in
+        # self._qubits pointing at the same physical qubit _detect_
+        # ancilla already allocated there. See _apply_coupling for why
+        # this needs to be a genuine logical qubit and not just a raw
+        # physical capture: capturing lq1's LOGICAL value via a real,
+        # nested cx(lq1, anc) call goes through the full _correct()/
+        # shadow-coupling machinery robustly, the same way any other
+        # logical qubit's value would be determined -- watching one
+        # specific physical replica directly (an earlier version of
+        # this) isn't a valid invariant, since _correct() can
+        # legitimately need to change any single replica's own value.
+        self._detect_ancilla1_lq = []
+        self._detect_ancilla2_lq = []
+        if self.is_error_detection:
+            for sim_id, phys_idx in enumerate(self._detect_ancilla1):
+                lq_idx = len(self._qubits)
+                self._qubits.append([(sim_id, phys_idx)])
+                self._detect_ancilla1_lq.append(lq_idx)
+            for sim_id, phys_idx in enumerate(self._detect_ancilla2):
+                lq_idx = len(self._qubits)
+                self._qubits.append([(sim_id, phys_idx)])
+                self._detect_ancilla2_lq.append(lq_idx)
+        # Reentrancy guard for the gadget's own nested cx(lq1, anc)
+        # capture calls (see _apply_coupling): those calls go through
+        # the ordinary _cpauli -> _apply_coupling path themselves, which
+        # would otherwise try to wrap ITSELF in another capture,
+        # recursing without end.
+        self._in_gadget_capture = False
 
         if "QRACK_QUNIT_SEPARABILITY_THRESHOLD" in os.environ:
             self._sdrp = min(1, float(os.environ["QRACK_QUNIT_SEPARABILITY_THRESHOLD"]))
@@ -632,51 +671,12 @@ class QrackAceBackend:
             t.adjs()
 
     def _detect_swap(self, sim_id, idx1, idx2):
-        """Same detect-and-post-select gadget as _apply_coupling's real
-        gate branch, generalized to SWAP's own invariant instead of
-        CNOT's. SWAP exchanges two qubits' values, but their XOR
-        (parity) is exactly conserved in the noiseless case:
-        idx1_before ^ idx2_before == idx1_after ^ idx2_after, regardless
-        of either qubit's individual value -- captured the same way,
-        just with two capture-CNOTs (one per qubit) into the shared
-        per-simulator ancilla instead of one.
-        """
-        sim = self.sim[sim_id]
-        if not self.is_error_detection:
-            sim.swap(idx1, idx2)
-            return
-        anc = self._detect_ancilla[sim_id]
-        sim.mcx([idx1], anc)
-        sim.mcx([idx2], anc)
-        sim.swap(idx1, idx2)
-        sim.mcx([idx1], anc)
-        sim.mcx([idx2], anc)
-        sim.force_m(anc, False)
+        self.sim[sim_id].swap(idx1, idx2)
 
     def _anti_shadow_wrap(self, c, t, middle_fn):
-        """Shared gadget for _anti_c{x,y,z}_shadow: all three bracket
-        their genuinely cross-sim shadow call with two _qec_x(c) calls,
-        and nothing else ever touches c in between -- the shadow call
-        underneath only ever reads c via .prob(), never gates it (same
-        property _apply_coupling's real branch relies on for its own
-        control-invariance check). So X;X on c should net to identity,
-        in the noiseless case, regardless of c's current value or basis
-        -- exactly as protectable as the CNOT-sandwich case, just with
-        X instead of CNOT as the bracketing gate.
-        """
-        if not (self.is_error_detection and isinstance(c, tuple)):
-            self._qec_x(c)
-            middle_fn(c, t)
-            self._qec_x(c)
-            return
-        anc = self._detect_ancilla[c[0]]
-        sim = self.sim[c[0]]
-        sim.mcx([c[1]], anc)
         self._qec_x(c)
         middle_fn(c, t)
         self._qec_x(c)
-        sim.mcx([c[1]], anc)
-        sim.force_m(anc, False)
 
     def _anti_cz_shadow(self, c, t):
         self._anti_shadow_wrap(c, t, self._cz_shadow)
@@ -1444,6 +1444,56 @@ class QrackAceBackend:
                                  # bounded window, no reactive invalidation
                                  # needed for these -- see
                                  # _resolve_witnessed_shadow.
+
+        # Logical-level error-detection gadget: captures lq1's LOGICAL
+        # value (and lq2's too, for CZ specifically -- see below) into a
+        # dedicated hidden ancilla via a genuine, nested cx() call --
+        # NOT a raw capture of one specific physical replica. This
+        # matters: gate_fn/shadow_fn below never gate the control (only
+        # ever read it via .prob()), so lq1's LOGICAL value is
+        # structurally guaranteed not to change across this loop --
+        # that invariant holds regardless of what _correct() may have
+        # legitimately done to any INDIVIDUAL replica beforehand,
+        # because the nested cx(lq1, anc) call determines lq1's value
+        # the same robust way any other logical coupling would, not by
+        # trusting one physical replica directly (an earlier version of
+        # this tried exactly that and crashed: _correct() can
+        # legitimately need to change hq1[0]'s own value, so "hq1[0]
+        # never changes" isn't actually a valid invariant, even though
+        # "lq1's logical value never changes here" is).
+        #
+        # The genuine syndrome signal comes from the capture itself: the
+        # nested cx() goes through the same _correct()/shadow-coupling
+        # machinery as any other logical operation, which can introduce
+        # some imprecision between the "before" and "after" capture even
+        # though lq1's true value didn't change -- that imprecision is
+        # exactly this architecture's own intrinsic (not noise=p)
+        # approximation error, which is what's worth catching.
+        #
+        # CZ also captures lq2 into the SAME ancilla: unlike CX/CY,
+        # where the target's value legitimately, intentionally changes
+        # (that's the entangling operation, not an error), CZ never
+        # changes either participant's Z-population on any input, so
+        # lq2's logical value is an equally valid invariant here, for
+        # this gate family only -- same reasoning as the earlier
+        # single-replica CZ dual-check, just applied at the logical
+        # level now.
+        anc1, anc2 = None, None
+        if self.is_error_detection and not self._in_gadget_capture:
+            anc1 = self._detect_ancilla1_lq[hq1[0][0]]
+            self._in_gadget_capture = True
+            # Control bit-flip
+            self.cx(lq1, anc1)
+            if len(hq1) > 1:
+                anc2 = self._detect_ancilla2_lq[hq1[0][0]]
+                # XOR on target
+                self.cx(lq2, anc2)
+                if anti:
+                    self.acx(lq1, anc2)
+                else:
+                    self.cx(lq1, anc2)
+            self._in_gadget_capture = False
+
         for q1 in qb1:
             b1 = hq1[q1]
             gate_fn, shadow_fn = self._get_gate(pauli, anti, b1[0])
@@ -1455,88 +1505,56 @@ class QrackAceBackend:
             for q2 in qb2:
                 b2 = hq2[q2]
                 if b1[0] == b2[0]:
-                    if self.is_error_detection:
-                        # Single-patch, not multi-patch: force_m's
-                        # post-selection isn't local to the one
-                        # simulator it's physically called on -- the
-                        # projection it performs reflects the "lab
-                        # frame" ground truth for whatever it's checking,
-                        # not an independent per-patch fact. Since every
-                        # replica of a boundary qubit is meant to
-                        # represent the SAME logical value, checking that
-                        # invariant via any one patch that has a real
-                        # gate touching it already captures the full
-                        # syndrome -- separately re-checking lq1's other
-                        # replicas in their own patches doesn't add new
-                        # independent information, it just adds their
-                        # own extra gate exposure for no additional
-                        # benefit. So: XOR b1's value into ITS OWN
-                        # patch's ancilla immediately before the gate,
-                        # XOR it in again immediately after, force_m that
-                        # one ancilla -- b1 only, not every replica of
-                        # lq1.
-                        #
-                        # Also worth being explicit about: what this
-                        # catches is NOT the same thing as the `noise=`
-                        # parameter's injected depolarizing/Pauli channel.
-                        # It's this architecture's own INTRINSIC error --
-                        # the approximation inherent in the elided
-                        # shadow-coupling / replica-consistency scheme,
-                        # present even at noise=0. Testing this gadget
-                        # against `noise=p` instead measures something
-                        # different (and actively penalizes it, since the
-                        # sandwiching CNOTs are then subject to that same
-                        # injected noise too) -- see conversation record.
-                        #
-                        # Scope: still only the mcx/mcy/mcz path
-                        # (_cpauli / _apply_coupling); swap/iswap/etc.
-                        # get their own dedicated gadget (_detect_swap),
-                        # and the anti-controlled shadow variants get
-                        # theirs (_anti_shadow_wrap) -- see those.
-                        #
-                        # CZ specifically also checks b2, not just b1:
-                        # unlike CX/CY, where the target's Z-population
-                        # legitimately, intentionally changes (that IS
-                        # the entangling operation -- not an error), CZ
-                        # is diagonal in the computational basis and
-                        # NEVER changes either qubit's Z-population, only
-                        # a relative phase. So b2 is an equally valid
-                        # invariance check here, for this gate family
-                        # only. Combined as one XOR parity (b1^b2), same
-                        # pattern as the SWAP gadget: catches either
-                        # participant's first-order (O(p)) disturbance,
-                        # only misses the second-order (O(p^2)) case
-                        # where both are disturbed simultaneously in a
-                        # way that cancels in the combined parity.
-                        # (Considered and rejected checking b1 in BOTH
-                        # Z and X bases instead, to catch phase-type
-                        # errors on the control too -- doesn't work: CX/CY
-                        # genuinely, intentionally entangle control with
-                        # target, which legitimately degrades the
-                        # control's own X/Y-basis coherence as correct
-                        # gate behavior, not error. A detector for that
-                        # would flag every successful entangling gate and
-                        # destroy the entanglement the gate was supposed
-                        # to create.)
-                        check_b2_too = pauli == Pauli.PauliZ
-                        anc = self._detect_ancilla[b1[0]]
-                        sim = self.sim[b1[0]]
-                        sim.mcx([b1[1]], anc)
-                        if check_b2_too:
-                            sim.mcx([b2[1]], anc)
-                        gate_fn([b1[1]], b2[1])
-                        sim.mcx([b1[1]], anc)
-                        if check_b2_too:
-                            sim.mcx([b2[1]], anc)
-                        sim.force_m(anc, False)
-                    else:
-                        gate_fn([b1[1]], b2[1])
+                    gate_fn([b1[1]], b2[1])
                 elif lq1_lr or (b1[1] == b2[1]) or ((len(qb1) == 2) and (b1[1] == (b2[1] & 1))):
                     shadow_fn(b1, b2)
                     shadow_targets.append(b2)
                     if witness is not None and witness != b2:
                         witnessed_targets.append((b2, witness))
 
+        if anc1 is not None:
+            self._in_gadget_capture = True
+            self.cx(lq1, anc1)
+            # Check prob() before forcing: force_m(anc, False)
+            # assumes the "agree" branch has nonzero probability,
+            # which usually holds (that's the whole invariant this
+            # gadget relies on) but isn't guaranteed -- if the
+            # architecture's own approximation genuinely, confidently
+            # drove lq1 (or lq2) to a different value between the
+            # two captures, the "agree" branch can have exactly zero
+            # probability, and forcing it crashes outright (verified
+            # directly: reproducible RuntimeError under realistic
+            # circuit depth). Accept that a genuine, confident
+            # disagreement occurred instead of forcing the
+            # impossible branch: force the TRUE condition (safe,
+            # since that branch is the one that actually carries the
+            # probability), reset the ancilla back to |0>, and apply
+            # a corrective X to lq1 to restore the detected
+            # invariant.
+            anc_sim, anc_idx = self._qubits[anc1][0]
+            p = self.sim[anc_sim].prob(anc_idx)
+            if p > 0.5:
+                self.force_m(anc1, True)
+                self.x(anc1)
+                self.x(lq1)
+            else:
+                self.force_m(anc1, False)
+            self._in_gadget_capture = False
+
+        if anc2 is not None:
+            self._in_gadget_capture = True
+            # XOR check
+            self.cx(lq2, anc2)
+            anc_sim, anc_idx = self._qubits[anc2][0]
+            p = self.sim[anc_sim].prob(anc_idx)
+            if p > 0.5:
+                self.force_m(anc2, True)
+                self.x(anc2)
+                self.x(lq2)
+            else:
+                self.force_m(anc2, False)
+            self._in_gadget_capture = False
+
         if lq2 is not None and witnessed_targets and self._witness_map is not None:
             wmap = self._witness_map.setdefault(lq2, {})
             for target_replica, witness_replica in witnessed_targets:
@@ -1621,61 +1639,81 @@ class QrackAceBackend:
         self._cpauli(lq1, lq2, False, Pauli.PauliX)
 
     def cy(self, lq1, lq2):
-        self._cpauli(lq1, lq2, False, Pauli.PauliY)
+        if self.is_error_detection:
+            self.adjs(lq2)
+            self.cx(lq1, lq2)
+            self.s(lq2)
+        else:
+            self._cpauli(lq1, lq2, False, Pauli.PauliY)
 
     def cz(self, lq1, lq2):
-        self._cpauli(lq1, lq2, False, Pauli.PauliZ)
+        if self.is_error_detection:
+            self.h(lq2)
+            self.cx(lq1, lq2)
+            self.h(lq2)
+        else:
+            self._cpauli(lq1, lq2, False, Pauli.PauliZ)
 
     def acx(self, lq1, lq2):
         self._cpauli(lq1, lq2, True, Pauli.PauliX)
 
     def acy(self, lq1, lq2):
-        self._cpauli(lq1, lq2, True, Pauli.PauliY)
+        if self.is_error_detection:
+            self.adjs(lq2)
+            self.acx(lq1, lq2)
+            self.s(lq2)
+        else:
+            self._cpauli(lq1, lq2, True, Pauli.PauliY)
 
     def acz(self, lq1, lq2):
-        self._cpauli(lq1, lq2, True, Pauli.PauliZ)
+        if self.is_error_detection:
+            self.h(lq2)
+            self.acx(lq1, lq2)
+            self.h(lq2)
+        else:
+            self._cpauli(lq1, lq2, True, Pauli.PauliZ)
 
     def mcx(self, lq1, lq2):
         if len(lq1) > 1:
             raise RuntimeError(
                 "QrackAceBackend.mcx() is provided for syntax convenience and only supports 1 control qubit!"
             )
-        self._cpauli(lq1[0], lq2, False, Pauli.PauliX)
+        self.cx(lq1[0], lq2)
 
     def mcy(self, lq1, lq2):
         if len(lq1) > 1:
             raise RuntimeError(
                 "QrackAceBackend.mcy() is provided for syntax convenience and only supports 1 control qubit!"
             )
-        self._cpauli(lq1[0], lq2, False, Pauli.PauliY)
+        self.cy(lq1[0], lq2)
 
     def mcz(self, lq1, lq2):
         if len(lq1) > 1:
             raise RuntimeError(
                 "QrackAceBackend.mcz() is provided for syntax convenience and only supports 1 control qubit!"
             )
-        self._cpauli(lq1[0], lq2, False, Pauli.PauliZ)
+        self.cz(lq1[0], lq2)
 
     def macx(self, lq1, lq2):
         if len(lq1) > 1:
             raise RuntimeError(
                 "QrackAceBackend.macx() is provided for syntax convenience and only supports 1 control qubit!"
             )
-        self._cpauli(lq1[0], lq2, True, Pauli.PauliX)
+        self.acx(lq1[0], lq2)
 
     def macy(self, lq1, lq2):
         if len(lq1) > 1:
             raise RuntimeError(
                 "QrackAceBackend.macy() is provided for syntax convenience and only supports 1 control qubit!"
             )
-        self._cpauli(lq1[0], lq2, True, Pauli.PauliY)
+        self.acy(lq1[0], lq2)
 
     def macz(self, lq1, lq2):
         if len(lq1) > 1:
             raise RuntimeError(
                 "QrackAceBackend.macz() is provided for syntax convenience and only supports 1 control qubit!"
             )
-        self._cpauli(lq1[0], lq2, True, Pauli.PauliZ)
+        self.acz(lq1[0], lq2)
 
     def swap(self, lq1, lq2):
         hq1 = self._unpack(lq1)
@@ -1745,6 +1783,18 @@ class QrackAceBackend:
         # single-replica (bulk) qubits, so this is always safe to call, and
         # only actually matters (and was being silently skipped) whenever
         # either side is a multi-replica boundary qubit.
+        #
+        # Deliberately NOT wrapped with the same logical-level gadget
+        # _cpauli uses below this branch: unlike a controlled-Pauli gate,
+        # where the control is structurally invariant, SWAP genuinely,
+        # intentionally exchanges both sides' values -- an independent
+        # "did home1/home2 change" check would incorrectly flag a
+        # legitimate swap as an error and try to veto it. The correct
+        # invariant here is the COMBINED parity (home1 XOR home2), not
+        # independent per-side checks, and getting that right when the
+        # two sides can land on different simulators (the partial-match
+        # branches below) needs separate, careful treatment -- not
+        # reused as-is from _cpauli's helper.
         self._correct(lq1)
         self._correct(lq2)
 
@@ -1760,6 +1810,19 @@ class QrackAceBackend:
             # with or without this call).
             return
 
+        anc1, anc2 = None, None
+        if self.is_error_detection and not self._in_gadget_capture:
+            if len(hq2) == 1:
+                anc1 = self._detect_ancilla1_lq[hq1[0][0]]
+                anc2 = self._detect_ancilla2_lq[hq1[0][0]]
+            else:
+                anc1 = self._detect_ancilla1_lq[hq2[0][0]]
+                anc2 = self._detect_ancilla2_lq[hq2[0][0]]
+            self._in_gadget_capture = True
+            self.cx(lq1, anc1)
+            self.cx(lq2, anc2)
+            self._in_gadget_capture = False
+
         # Partial-match cases: one side is a simple (single-replica) qubit,
         # the other has multiple replicas. For the multi-replica side's
         # non-matching replicas, the correct decomposition (verified
@@ -1791,9 +1854,7 @@ class QrackAceBackend:
             # error is already Z-basis-population-visible and doesn't need
             # an H-rotation first to become detectable.
             self._correct(lq2)
-            return
-
-        if len(hq2) == 1 and any(h[0] == hq2[0][0] for h in hq1):
+        elif len(hq2) == 1 and any(h[0] == hq2[0][0] for h in hq1):
             _hq2 = hq2[0]
             non_matching = [h for h in hq1 if h[0] != _hq2[0]]
             matching = [h for h in hq1 if h[0] == _hq2[0]]
@@ -1804,18 +1865,39 @@ class QrackAceBackend:
             for _hq1 in non_matching:
                 self._cx_shadow(_hq2, _hq1)
             self._correct(lq1)
-            return
-
-        # General case: no shared simulator at all (e.g. two simple
-        # qubits on entirely different sims -- nothing to anchor an exact
-        # swap on, verified the sandwich branches above give WRONG,
-        # deterministic results here: 100/100 failures vs 0/15 for this
-        # fallback), or both sides multi-replica and not fully matched:
-        # cx() already wraps itself with _correct() via _cpauli, so no
-        # extra wrapping needed here.
-        self.cx(lq1, lq2)
-        self.cx(lq2, lq1)
-        self.cx(lq1, lq2)
+        else:
+            # General case: no shared simulator at all (e.g. two simple
+            # qubits on entirely different sims -- nothing to anchor an exact
+            # swap on, verified the sandwich branches above give WRONG,
+            # deterministic results here: 100/100 failures vs 0/15 for this
+            # fallback), or both sides multi-replica and not fully matched:
+            # cx() already wraps itself with _correct() via _cpauli, so no
+            # extra wrapping needed here.
+            self.cx(lq1, lq2)
+            self.cx(lq2, lq1)
+            self.cx(lq1, lq2)
+
+        if anc1 is not None:
+            self._in_gadget_capture = True
+            self.cx(lq1, anc2)
+            self.cx(lq2, anc1)
+            anc_sim, anc_idx = self._qubits[anc1][0]
+            p = self.sim[anc_sim].prob(anc_idx)
+            if p > 0.5:
+                self.force_m(anc1, True)
+                self.x(anc1)
+                self.x(lq1)
+            else:
+                self.force_m(anc1, False)
+            anc_sim, anc_idx = self._qubits[anc2][0]
+            p = self.sim[anc_sim].prob(anc_idx)
+            if p > 0.5:
+                self.force_m(anc2, True)
+                self.x(anc2)
+                self.x(lq2)
+            else:
+                self.force_m(anc2, False)
+            self._in_gadget_capture = False
 
     def iswap(self, lq1, lq2):
         self.swap(lq1, lq2)

{pyqrack_complex128-2.18.2 → pyqrack_complex128-2.18.3/pyqrack_complex128.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyqrack-complex128
-Version: 2.18.2
+Version: 2.18.3
 Summary: pyqrack - Pure Python vm6502q/qrack Wrapper
 Home-page: https://github.com/vm6502q/pyqrack
 Author: Daniel Strano

{pyqrack_complex128-2.18.2 → pyqrack_complex128-2.18.3}/pyqrack_complex128.egg-info/SOURCES.txt

@@ -17,6 +17,9 @@ pyqrack/qrack_stabilizer.py
 pyqrack/quimb_circuit_type.py
 pyqrack/qrack_system/__init__.py
 pyqrack/qrack_system/qrack_system.py
+pyqrack/qrack_system/qrack_cl_precompile/qrack_cl_precompile
+pyqrack/qrack_system/qrack_lib/libqrack_pinvoke.so
+pyqrack/qrack_system/qrack_lib/libqrack_pinvoke.so.10.13.0
 pyqrack/stats/__init__.py
 pyqrack/stats/load_quantized_data.py
 pyqrack/stats/quantize_by_range.py

{pyqrack_complex128-2.18.2 → pyqrack_complex128-2.18.3}/setup.py

@@ -7,7 +7,7 @@ from setuptools import setup
 from setuptools.command.build_py import build_py
 
 
-VERSION = "2.18.2"
+VERSION = "2.18.3"
 
 # Read long description from README.
 README_PATH = os.path.join(os.path.abspath(os.path.dirname(__file__)), 'README.md')