isoring 0.0.1__tar.gz

isoring-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Richard Pham
+
+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.

isoring-0.0.1/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: isoring
+Version: 0.0.1
+Summary: A structure for data security and a cracking environment.
+Home-page: https://github.com/Changissnz/isoring
+Author: Richard Pham
+Author-email: Richard Pham <phamrichard45@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/changissnz/isoring
+Project-URL: Issues, https://github.com/changissnz/isoring/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+
+# isoring
+a component from the terminated project, puissec. 
+
+A structure called the `IsoRingedChain` is supposed to guard a big secret, comprised of a sequence 
+of arbitrarily-lengthed vectors (secrets). 
+
+# What is a Secret? 
+
+Who knows, really?  
+
+In this computer program, a secret is represented by a finitely lengthed vector. The `Sec` structure contains this vector of 
+length `n`, as well as `k` additional vectors in the same dimension of `n`. These `k+1` vectors are the local optima of 
+`n`-space in real numbers. Every one of those vectors has an associated probability value, the probability values adding up 
+to one. These probability values can be arbitrary, meaning the actual secret (vector) of `Sec` may have any probability 
+value in `[0,1.]`. Design of `Sec` is based on the common machine-learning problem of choosing local optima over the best 
+solution. 
+
+The `IsoRing` structure contains the secret, a vector in finite space. It contains that secret in one `Sec` instance. 
+`IsoRing` also holds an additional `j` `Sec` instances, each of these `Sec` instances in a unique finite vector 
+dimension. These `j` instances serve as buffers to third-party acquisition of the actual `Sec` instance. In effect, 
+`IsoRing` has two primary layers of defenses: the `j` `Sec` instances and the `r_j >= 1` alternative local optima to 
+the actual vector of some `Sec`. 
+
+At any point in program run, outward representative of `IsoRing` is exactly one `Sec` instance, the isomorphic 
+representation (iso-repr). 
+
+In order for a third-party to interact with an `IsoRing` for information, third-party will have to interact with 
+feedback function of `IsoRing`. For an `IsoRing` in iso-repr vector dimension `q`, feedback function provides a 
+`q`-vector of distance scores. Distance scores are conventionally euclidean point distances. However, there are 
+alternative feedback functions that provide distorted distance scores via pseudo-random number generator. 
+
+For a sequence of arbitrarily-lengthed vectors (secrets), an `IsoRingedChain` is used to cover it and this structure 
+is, in turn, composed of a number of `IsoRing`s equal to the number of those vectors (secrets). 
+
+# What is an Isomorphic Ringed Chain? 
+
+An `IsoRingedChain` guards a sequence of vectors (secrets). Any of the `IsoRing`s in an `IsoRingedChain` may be in 
+an isomorphic representation not of the same dimension of the actual secret. Additionally, every `IsoRing` in an 
+`IsoRingedChain` has dependencies and co-dependencies in order for third-party access to it. Dependencies are the 
+`IsoRing`s that must have been "cracked" by the third-party before getting to it, and co-dependencies are the 
+`IsoRing`s that must be "cracked" alongside it. Cracking cannot proceed by an ordering of the `IsoRing`s that 
+violate the specified dependencies and co-dependencies linking these structures together for the `IsoRingedChain`. 
+
+# What is Cracking? 
+
+In this program, the `Cracker` structure is responsible for determining all the secrets of an `IsoRingedChain`. This 
+process of determination is "cracking". The `Cracker` must attempt cracking in the order specified by all of the 
+contained `IsoRing`s' dependencies and co-dependencies. Otherwise, program will halt `Cracker` midway, resulting in 
+its failure. 
+
+`Cracker` is given background information, `BackgroundInfo`, on the target `IsoRingedChain`.  
+
+NOTE: There are deficits to this map design of background information. However, it was chosen because it avoids the 
+      Curse of Dimensionality, one of a few major problems that plagued successful complete development of the 
+      program `puissec`, found at `github.com/changissnz/puissec`. Program `puissec` was the predecessor of this 
+      program `isoring`. Program `isoring` is, in fact, a simpler version of only part of the problems in the 
+      conceptualization of `puissec`. 
+
+`BackgroundInfo` has three main components.  
+1. Hypothesis map,  
+    `<Isoring> identifier -> <Sec> index -> <HypStruct>`.  
+2. Suspected `IsoRing`-to-`Sec` map,  
+    `<Isoring> identifier -> <Sec> index`.  
+3. Order of cracking, a sequence with each element  
+    `{set of co-dependent IsoRing identifiers}`.  
+
+One deficit about design of this `BackgroundInfo` is the hypothesis map. Every `Sec` instance can have at 
+most one hypothesis on it. And the `HypStruct` is focused on exactly one local optimum. 
+
+`HypStruct` represents a hypothesis on a `Sec`, of vector dimension `k`, and has these attributes.  
+1. Suspected optima index `i` of the `Sec`.  
+2. Bounds (a `k x 2` matrix) suspected to contain optima `i`.  
+3. Hop size `h`, an integer, uniformly partitioning the bounds into `k x h` points.  
+4. Probability marker `P`, used to cross-reference with probability output value `P'` from a 
+   cracked `Sec`.  
+
+The probability values in this program are meant to be reference values for a `Cracker`. If a `Cracker` 
+uses a `HypStruct` to crack `Sec`, and the output probability from `Sec` differs from that of the 
+`HypStruct` used, then the `Cracker` does not accept the cracking vector as the actual secret. 
+
+NOTE: these are information games, broadly speaking.  
+
+For every `IsoRing` being targeted by a `Cracker`, `Cracker` uses one `Crackling` at any one time, in 
+order to attempt to crack the `IsoRing` for the vector (secret) of the `IsoRing`'s suspected `Sec`. A 
+`Cracker` will attempt to use as many `Crackling`s, in re-cracking sessions, for an `IsoRing` as program 
+permits until `Cracker` cracks its wanted local optimum from the suspected `Sec` of said `IsoRing`. 
+
+A structure called a `SearchSpaceIterator` is employed by every `Crackling` to execute brute-force 
+cracking attempts on an `IsoRing`'s isomorphic representation. `SearchSpaceIterator` outputs `k x h` 
+points that uniformly cover the input bounds of matrix `k x 2`. 
+
+If the `Cracker` does not a `HypStruct` for the `IsoRing`'s isomorphic representation (the second 
+layer in the three-layer hypothesis map), program halts `Cracker` midway. If the `Crackling` is 
+successful in cracking the isomorphic representation, `IsoRing` has to switch its isomorphic representation 
+to an uncracked `Sec`. If there are none that have not been cracked, `IsoRing` stops switching its 
+isomorphic representation due to the `Cracker` no longer being interested in cracking it anymore. 
+
+If a `Crackling` does not produce any (vector, associated probability value) on a `Sec`, `Cracker` cannot 
+proceed to attempting to crack any `IsoRing`s dependent on the `IsoRing`, pertaining to said `Sec`, being 
+cracked. In most cases, `Cracker` would be halted. 
+
+# The Brute-Force Environment 
+
+There Are Rules To The Game. The rules are enforced in the environment `BruteForceEnv`, where a `Cracker` 
+attempts to crack an `IsoRingedChain`. A `Cracker` is granted some arbitrary amount of energy, a real number. 
+If the energy falls to zero or below, program halts `Cracker`. A `Cracker` can use only `t` number of 
+`Crackling`s at once. If there are co-dependent `IsoRing` sets in `IsoRingedChain` that are greater in size 
+than `t`, successfully cracking the `IsoRingedChain` is impossible for the `Cracker`. 
+
+# What is Successful Cracking? Complete Execution or Complete Acquisition of Actual? 
+
+The complete execution of cracking all the `IsoRing`s in an `IsoRingedChain` can be known by a `Cracker` by 
+the time the program halts `Cracker`. However, the `BackgroundInfo` of a `Cracker` is what allows it to verify 
+on what the actual vectors from `IsoRingedChain` are. 
+
+# Additional Features 
+
+Generative methods, found in this program, can be used to produce the relevant data structures. These 
+methods do come in handy since there are a lot of variables to type up by hand.  
+
+# An Example On the User Interface 
+
+![Screenshot](screeshantaya.png) 

isoring-0.0.1/README.md

@@ -0,0 +1,123 @@
+# isoring
+a component from the terminated project, puissec. 
+
+A structure called the `IsoRingedChain` is supposed to guard a big secret, comprised of a sequence 
+of arbitrarily-lengthed vectors (secrets). 
+
+# What is a Secret? 
+
+Who knows, really?  
+
+In this computer program, a secret is represented by a finitely lengthed vector. The `Sec` structure contains this vector of 
+length `n`, as well as `k` additional vectors in the same dimension of `n`. These `k+1` vectors are the local optima of 
+`n`-space in real numbers. Every one of those vectors has an associated probability value, the probability values adding up 
+to one. These probability values can be arbitrary, meaning the actual secret (vector) of `Sec` may have any probability 
+value in `[0,1.]`. Design of `Sec` is based on the common machine-learning problem of choosing local optima over the best 
+solution. 
+
+The `IsoRing` structure contains the secret, a vector in finite space. It contains that secret in one `Sec` instance. 
+`IsoRing` also holds an additional `j` `Sec` instances, each of these `Sec` instances in a unique finite vector 
+dimension. These `j` instances serve as buffers to third-party acquisition of the actual `Sec` instance. In effect, 
+`IsoRing` has two primary layers of defenses: the `j` `Sec` instances and the `r_j >= 1` alternative local optima to 
+the actual vector of some `Sec`. 
+
+At any point in program run, outward representative of `IsoRing` is exactly one `Sec` instance, the isomorphic 
+representation (iso-repr). 
+
+In order for a third-party to interact with an `IsoRing` for information, third-party will have to interact with 
+feedback function of `IsoRing`. For an `IsoRing` in iso-repr vector dimension `q`, feedback function provides a 
+`q`-vector of distance scores. Distance scores are conventionally euclidean point distances. However, there are 
+alternative feedback functions that provide distorted distance scores via pseudo-random number generator. 
+
+For a sequence of arbitrarily-lengthed vectors (secrets), an `IsoRingedChain` is used to cover it and this structure 
+is, in turn, composed of a number of `IsoRing`s equal to the number of those vectors (secrets). 
+
+# What is an Isomorphic Ringed Chain? 
+
+An `IsoRingedChain` guards a sequence of vectors (secrets). Any of the `IsoRing`s in an `IsoRingedChain` may be in 
+an isomorphic representation not of the same dimension of the actual secret. Additionally, every `IsoRing` in an 
+`IsoRingedChain` has dependencies and co-dependencies in order for third-party access to it. Dependencies are the 
+`IsoRing`s that must have been "cracked" by the third-party before getting to it, and co-dependencies are the 
+`IsoRing`s that must be "cracked" alongside it. Cracking cannot proceed by an ordering of the `IsoRing`s that 
+violate the specified dependencies and co-dependencies linking these structures together for the `IsoRingedChain`. 
+
+# What is Cracking? 
+
+In this program, the `Cracker` structure is responsible for determining all the secrets of an `IsoRingedChain`. This 
+process of determination is "cracking". The `Cracker` must attempt cracking in the order specified by all of the 
+contained `IsoRing`s' dependencies and co-dependencies. Otherwise, program will halt `Cracker` midway, resulting in 
+its failure. 
+
+`Cracker` is given background information, `BackgroundInfo`, on the target `IsoRingedChain`.  
+
+NOTE: There are deficits to this map design of background information. However, it was chosen because it avoids the 
+      Curse of Dimensionality, one of a few major problems that plagued successful complete development of the 
+      program `puissec`, found at `github.com/changissnz/puissec`. Program `puissec` was the predecessor of this 
+      program `isoring`. Program `isoring` is, in fact, a simpler version of only part of the problems in the 
+      conceptualization of `puissec`. 
+
+`BackgroundInfo` has three main components.  
+1. Hypothesis map,  
+    `<Isoring> identifier -> <Sec> index -> <HypStruct>`.  
+2. Suspected `IsoRing`-to-`Sec` map,  
+    `<Isoring> identifier -> <Sec> index`.  
+3. Order of cracking, a sequence with each element  
+    `{set of co-dependent IsoRing identifiers}`.  
+
+One deficit about design of this `BackgroundInfo` is the hypothesis map. Every `Sec` instance can have at 
+most one hypothesis on it. And the `HypStruct` is focused on exactly one local optimum. 
+
+`HypStruct` represents a hypothesis on a `Sec`, of vector dimension `k`, and has these attributes.  
+1. Suspected optima index `i` of the `Sec`.  
+2. Bounds (a `k x 2` matrix) suspected to contain optima `i`.  
+3. Hop size `h`, an integer, uniformly partitioning the bounds into `k x h` points.  
+4. Probability marker `P`, used to cross-reference with probability output value `P'` from a 
+   cracked `Sec`.  
+
+The probability values in this program are meant to be reference values for a `Cracker`. If a `Cracker` 
+uses a `HypStruct` to crack `Sec`, and the output probability from `Sec` differs from that of the 
+`HypStruct` used, then the `Cracker` does not accept the cracking vector as the actual secret. 
+
+NOTE: these are information games, broadly speaking.  
+
+For every `IsoRing` being targeted by a `Cracker`, `Cracker` uses one `Crackling` at any one time, in 
+order to attempt to crack the `IsoRing` for the vector (secret) of the `IsoRing`'s suspected `Sec`. A 
+`Cracker` will attempt to use as many `Crackling`s, in re-cracking sessions, for an `IsoRing` as program 
+permits until `Cracker` cracks its wanted local optimum from the suspected `Sec` of said `IsoRing`. 
+
+A structure called a `SearchSpaceIterator` is employed by every `Crackling` to execute brute-force 
+cracking attempts on an `IsoRing`'s isomorphic representation. `SearchSpaceIterator` outputs `k x h` 
+points that uniformly cover the input bounds of matrix `k x 2`. 
+
+If the `Cracker` does not a `HypStruct` for the `IsoRing`'s isomorphic representation (the second 
+layer in the three-layer hypothesis map), program halts `Cracker` midway. If the `Crackling` is 
+successful in cracking the isomorphic representation, `IsoRing` has to switch its isomorphic representation 
+to an uncracked `Sec`. If there are none that have not been cracked, `IsoRing` stops switching its 
+isomorphic representation due to the `Cracker` no longer being interested in cracking it anymore. 
+
+If a `Crackling` does not produce any (vector, associated probability value) on a `Sec`, `Cracker` cannot 
+proceed to attempting to crack any `IsoRing`s dependent on the `IsoRing`, pertaining to said `Sec`, being 
+cracked. In most cases, `Cracker` would be halted. 
+
+# The Brute-Force Environment 
+
+There Are Rules To The Game. The rules are enforced in the environment `BruteForceEnv`, where a `Cracker` 
+attempts to crack an `IsoRingedChain`. A `Cracker` is granted some arbitrary amount of energy, a real number. 
+If the energy falls to zero or below, program halts `Cracker`. A `Cracker` can use only `t` number of 
+`Crackling`s at once. If there are co-dependent `IsoRing` sets in `IsoRingedChain` that are greater in size 
+than `t`, successfully cracking the `IsoRingedChain` is impossible for the `Cracker`. 
+
+# What is Successful Cracking? Complete Execution or Complete Acquisition of Actual? 
+
+The complete execution of cracking all the `IsoRing`s in an `IsoRingedChain` can be known by a `Cracker` by 
+the time the program halts `Cracker`. However, the `BackgroundInfo` of a `Cracker` is what allows it to verify 
+on what the actual vectors from `IsoRingedChain` are. 
+
+# Additional Features 
+
+Generative methods, found in this program, can be used to produce the relevant data structures. These 
+methods do come in handy since there are a lot of variables to type up by hand.  
+
+# An Example On the User Interface 
+
+![Screenshot](screeshantaya.png) 

isoring-0.0.1/isoring/brute_forcer/background_info.py

@@ -0,0 +1,172 @@
+from .hypothesis import * 
+from ..secrets.big_secret import * 
+
+
+def prng_to_decimal_output(prng):
+
+    def f(): 
+        q1 = abs(prng()) 
+        q2 = abs(prng())
+        if q1 == 0 or q2 == 0: return 0.0 
+
+        if q1 < q2: return q1 / q2
+        return q2 / q1 
+    return f 
+
+# NOTE: this prng must exclusively output integers 
+def n_swaps_on_seq(seq,n,prng):
+
+    ix = [_ for _ in range(len(seq))] 
+    ix = prg_seqsort(ix,prng) 
+
+    for i in range(n): 
+        # pop index 
+        index = ix[i%len(ix)]
+        x = seq.pop(index) 
+
+        # re-insert 
+        index = prng() % (len(seq) +1)
+
+        seq.insert(index,x) 
+    return seq 
+
+class BackgroundInfo:
+
+    """
+    info := dict, <Isoring> identifier -> <Sec> index -> <HypStruct> 
+    suspected_isoring_to_sec_idn := dict, <IsoRing> -> index of <Sec> most likely to be solution. 
+    order_of_cracking := list, of sets of <IsoRing> identifiers, specifying the 
+                         order that a <Cracker> will attempt cracking an <IsoRingedChain>. 
+    """
+    # NOTE: `suspected_isoring_to_sec_idn` can be incomplete w.r.t. `info`. In these cases, 
+    # <BackgroundInfo> uses method<default_most_likely_Sec_index_for_IsoRing> to decide 
+    # the best <HypStruct>. 
+    def __init__(self,info:dict,suspected_isoring_to_sec_idn:dict,order_of_cracking:list): 
+        assert BackgroundInfo.verify_valid_info(info) 
+
+        q = set(info.keys()) 
+        c = set() 
+        for o in order_of_cracking: c |= o 
+        assert q == c 
+
+        self.info = info 
+        self.suspected_isoring_to_sec_idn = suspected_isoring_to_sec_idn
+        self.order_of_cracking = order_of_cracking
+        return
+
+    def hypothesis_for_IsoRingANDSec(self,i,s): 
+        if not self.hypothesis_exists_for_IsoRingANDSec(i,s): 
+            return None 
+        return self.info[i][s] 
+
+    def hypothesis_exists_for_IsoRingANDSec(self,i,s): 
+        if i not in self.info: 
+            return False 
+        
+        if s not in self.info[i]: 
+            return False 
+        return True 
+
+    @staticmethod
+    def verify_valid_info(info): 
+        for k,v in info.items(): 
+            if not type(k) == int: return False 
+            for k2,v2 in v.items(): 
+                if not type(k2) == int: return False 
+                if not type(v2) == HypStruct: return False 
+        return True 
+
+    # TODO: test this. 
+    @staticmethod
+    def extract_from_IsoRingedChain(irc,prng,actual_sec_vec_ratio_range,dim_covered_ratio_range,\
+        valid_bounds_ratio_range,prioritize_actual_Sec_ratio,shuffle_OOC_ratio,\
+        suspected_isoring_to_sec_idn_error_ratio,valid_one_shot_kill_ratio_range=[0.,0.]):
+        assert type(irc) == IsoRingedChain 
+        assert 0. <= actual_sec_vec_ratio_range[0] <= actual_sec_vec_ratio_range[1] <= 1.
+        assert 0. <= dim_covered_ratio_range[0] <= dim_covered_ratio_range[1] <= 1.
+        assert 0. <= valid_bounds_ratio_range[0] <= valid_bounds_ratio_range[1] <= 1.
+        assert 0. <= prioritize_actual_Sec_ratio <= 1.0
+        assert 0. <= shuffle_OOC_ratio <= 1.0
+        assert 0. <= suspected_isoring_to_sec_idn_error_ratio <= 1.0
+
+        def prg_(): return int(prng())
+
+        prng_dec = prng_to_decimal_output(prng) 
+
+        info = dict() 
+        for idn_tag,ir in irc.ir_dict.items():
+            # fetch all ratios and bools 
+            if actual_sec_vec_ratio_range[0] == actual_sec_vec_ratio_range[1]: 
+                actual_sec_vec_ratio = actual_sec_vec_ratio_range[0]
+            else: 
+                actual_sec_vec_ratio = modulo_in_range(prng_dec(),actual_sec_vec_ratio_range)
+
+            if dim_covered_ratio_range[0] == dim_covered_ratio_range[1]: 
+                ratio_of_dim_covered = dim_covered_ratio_range[0]
+            else: 
+                ratio_of_dim_covered = modulo_in_range(prng_dec(),dim_covered_ratio_range) 
+
+            if valid_bounds_ratio_range[0] == valid_bounds_ratio_range[1]: 
+                valid_bounds_ratio = valid_bounds_ratio_range[0] 
+            else: 
+                valid_bounds_ratio = modulo_in_range(prng_dec(),valid_bounds_ratio_range)
+
+            if valid_one_shot_kill_ratio_range[0] == valid_one_shot_kill_ratio_range[1]: 
+                valid_one_shot_kill_ratio = valid_one_shot_kill_ratio_range[0]
+            else: 
+                valid_one_shot_kill_ratio = modulo_in_range(prng_dec(),valid_one_shot_kill_ratio_range)
+
+            prioritize_actual_Sec = prng_dec() <= prioritize_actual_Sec_ratio
+
+            hdict = HypStruct.extract_from_IsoRing_into_HypStruct_dict(ir,prng,actual_sec_vec_ratio,\
+                ratio_of_dim_covered,valid_bounds_ratio,prioritize_actual_Sec,valid_one_shot_kill_ratio)
+            info[idn_tag] = hdict 
+
+        # get the IsoRing identifiers for the IsoRing to Sec index error 
+        i2s_error = int(ceil(suspected_isoring_to_sec_idn_error_ratio * len(info))) 
+        L = sorted(info.keys())
+        L = prg_seqsort(L,prg_)[:i2s_error] 
+        S = dict() 
+        for k in info.keys(): 
+            ir = irc.fetch_IsoRing(k)
+            
+            # case: correct <Sec> index 
+            actual = ir.actual_sec_index
+            if k not in L: 
+                S[k] = actual 
+            else: 
+                qs = [_ for _ in range(len(ir.sec_list)) if _ != actual]
+
+                # case: no alternative Sec, use actual 
+                if len(qs) == 0: 
+                    S[k] = actual
+                else: 
+                    qi = prg_() % len(qs)
+                    S[k] = qs[qi] 
+               
+        # get the OOC 
+        num_swaps = int(ceil(shuffle_OOC_ratio * len(irc.ooc)))
+        ooc = n_swaps_on_seq(deepcopy(irc.ooc),num_swaps,prg_)
+
+        return BackgroundInfo(info,S,ooc) 
+
+    def sec_index_for_IsoRing(self,ir_idn): 
+        if ir_idn not in self.suspected_isoring_to_sec_idn: 
+            return self.default_most_likely_Sec_index_for_IsoRing(ir_idn)
+        return self.suspected_isoring_to_sec_idn[ir_idn]
+
+    """
+    chooses the <Sec> index with a <HypStruct> of highest probability marker. 
+    """
+    def default_most_likely_Sec_index_for_IsoRing(self,ir_idn): 
+        if ir_idn not in self.info: return None 
+
+        d = self.info[ir_idn] 
+        if len(d) == 0: return None 
+
+        secindex_pr = [] 
+        for k,v in d.items(): 
+            secindex_pr.append((k,v.probability_marker)) 
+        
+        secindex_pr = sorted(secindex_pr,key=lambda x:x[1],reverse=True)
+        return secindex_pr[0][0]

isoring-0.0.1/isoring/brute_forcer/brute_force_env.py

@@ -0,0 +1,133 @@
+from .cracker import * 
+
+def one_to_one_IsoRing2Crackling_map(ir_idn:set): 
+    assert type(ir_idn) == set 
+    return {i:1 for i in ir_idn} 
+
+"""
+environment for a Cracker, given background information on an IsoRingedChain, to conduct brute-force guesses 
+against it. 
+"""
+class BruteForceEnv:
+
+    def __init__(self,crck:Cracker,irc:IsoRingedChain,prng=None,verbose=True): 
+        assert type(crck) == Cracker and type(irc) == IsoRingedChain
+        assert type(verbose) == bool 
+        self.crck = crck 
+        self.irc = irc 
+
+        if type(prng) == type(None): 
+            self.prng = default_std_Python_prng(output_range=[-10000,10000],rounding_depth=0) 
+        else: 
+            self.prng = prng 
+        self.irc.prng = self.prng 
+        self.verbose = verbose 
+
+        self.cbridges = [] 
+
+        self.num_iter = 0 
+        return
+
+    def __next__(self): 
+        # case: finished 
+        if self.is_finished(): return 
+
+        # if no CBridges exist, declare them 
+        if len(self.cbridges) == 0: 
+            stat = self.first_cracking_bridges()
+            if not stat: 
+                return 
+        
+        self.run_cbridges() 
+        self.num_iter += 1 
+        return
+
+    # TODO: finish 
+    def is_finished(self): 
+        if self.crck.halted: 
+            return True 
+        return False 
+
+    def run_cbridges(self): 
+        any_terminated = False 
+
+        i = 0 
+        while i < len(self.cbridges): 
+            c = self.cbridges[i] 
+            if c.terminated: 
+                any_terminated = True 
+                self.cbridges.pop(i)
+                continue 
+            next(c) 
+            i += 1 
+            
+
+        if any_terminated: 
+
+            wanted_finishes,recracks = self.crck.manage_cracklings() 
+            if self.verbose: 
+                print("# BRIDGES: ",len(self.cbridges))
+                print("\t- finished cracking on IsoRings\n{}".format(wanted_finishes)) 
+                print("\t- recracking on IsoRings\n{}".format(recracks)) 
+                print("=======================================================") 
+
+            self.send_IsoRingedChain_info_on_cracked(wanted_finishes,recracks) 
+
+            if len(recracks) > 0: 
+                self.add_recracking_bridges(recracks)
+
+        self.crck.did_fail() 
+
+    def first_cracking_bridges(self): 
+        stat = self.crck.next_target_IsoRing_set()
+
+        if self.verbose: 
+            print("[!] t={}, Adding initial cracking bridges to IsoRings\n{}\n".format(self.num_iter,self.crck.target_ir_set))
+
+        # case: no new targets, terminated
+        if not stat: 
+            if self.verbose: print("[X] no new target IsoRings. DONE.")
+            self.crck.halted = True 
+            return stat  
+
+        # case: wrong order, IsoRingedChain does not accept
+        stat = self.irc.accept_cracker_targetset(self.crck.target_ir_set)
+        if not stat: 
+            if self.verbose: print("[X] wrong cracking order. DONE.")
+            self.crck.halted = True 
+            return stat 
+
+        stat = self.initiate_Cracker_deployment(self.crck.target_ir_set)
+
+        self.crck.increment_index() 
+        return stat 
+
+    def add_recracking_bridges(self,recrack_set):
+        assert recrack_set.issubset(self.crck.target_ir_set) 
+        return self.initiate_Cracker_deployment(recrack_set)
+
+    def initiate_Cracker_deployment(self,ir_set): 
+
+        # send Cracker info on IsoRing iso-repr state 
+        ir_state = self.irc.repr_dict_for_IsoRings(ir_set)
+        i2c_map = one_to_one_IsoRing2Crackling_map(ir_set)
+            
+        stat = self.crck.deploy_cracklings(ir_state,i2c_map)
+
+        # case: Cracker is stuck. 
+        if not stat: 
+            self.crck.halted = True 
+            return stat 
+
+        # form the bridges 
+        q = -sum(i2c_map.values())
+        for cr in self.crck.active_cracklings[q:]: 
+            hs = self.crck.bi.hypothesis_for_IsoRingANDSec(cr.target_ir,cr.ir_sec_index) 
+            ir = self.irc.fetch_IsoRing(cr.target_ir)       
+            cb = CBridge(cr,hs,ir) 
+            self.cbridges.append(cb) 
+        return True 
+
+    def send_IsoRingedChain_info_on_cracked(self,wanted_finishes,recracks): 
+        self.irc.register_cracked_IsoRings(wanted_finishes,recracks)
+        return