new functions for transforming Ising multipliers

added vec2mat and mat2vec
updated doc

Author: eltrompetero

coniii/models.py

@@ -123,12 +123,16 @@ def __init__(self, multipliers, rng=None, n_cpus=None, verbose=False):
         Parameters
         ----------
         multipliers : list of ndarray or ndarray
-            Can be a list of vectors [fields, couplings], a vector of fields and couplings
-            concatenated together, or a matrix of parameters where the diagonal entries
-            are the fields.
+            Can be an integer (all parameters are set to zero), list of vectors [fields,
+            couplings], a vector of fields and couplings concatenated together, or a
+            matrix of parameters where the diagonal entries are the fields.
         """
 
         # intelligently read in multipliers by handling multiple use cases
+        if type(multipliers) is int:
+            assert multipliers>1, "System size must be greater than 1."
+            self.n = multipliers
+            multipliers = np.zeros(self.n+self.n*(self.n-1)//2)
         if len(multipliers)==2:
             # case where two vectors are given
             self.n = len(multipliers[0])

coniii/solvers.py

@@ -24,7 +24,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 # =============================================================================================== #
-from scipy.optimize import minimize,fmin_ncg,minimize_scalar,root
+from scipy.optimize import minimize, fmin_ncg, minimize_scalar, root
 import multiprocess as mp
 import copy
 from . import mean_field_ising
@@ -147,7 +147,8 @@ def solve(self,
         Returns
         -------
         ndarray
-            Solved multipliers (parameters).
+            Solved multipliers (parameters). For Ising problem, these can be converted
+            into matrix format using utils.vec2mat.
         dict, optional
             Output from scipy.optimize.root.
         """
@@ -417,7 +418,8 @@ def solve(self,
         Returns
         -------
         ndarray
-            Solution.
+            Solved multipliers (parameters). For Ising problem, these can be converted
+            into matrix format using utils.vec2mat.
         dict (optional)
             Output from scipy.optimize.minimize returned if full_output is True.
         """
@@ -568,7 +570,8 @@ def learn_settings(i):
         Returns
         -------
         ndarray
-            Found solution to inverse problem.
+            Solved multipliers (parameters). For Ising problem, these can be converted
+            into matrix format using utils.vec2mat.
         int
             Error flag.
             0, converged within given criterion
@@ -1116,7 +1119,8 @@ def solve(self, force_general=False, **kwargs):
         Returns
         -------
         ndarray
-            multipliers
+            Solved multipliers (parameters). For Ising problem, these can be converted
+            into matrix format using utils.vec2mat.
         """
 
         if type(self.model) is Ising and not force_general:
@@ -1690,26 +1694,31 @@ def solve(self, threshold,
         ----------
         threshold : float
         meanFieldRef : bool, False
-            Expand about mean-field reference
+            Expand about mean-field reference.
         independentRef : bool, True
-            Expand about independent reference
+            Expand about independent reference.
         priorLmbda : float, 0.
-            Strength of non-interacting prior
+            Strength of non-interacting prior.
         meanFieldPriorLmbda : float, None
             Strength of non-interacting prior in mean field calculation (defaults to
-            priorLmbda)
+            priorLmbda).
         
         Returns
         -------
-        With full_output=False, returns
-            J           : Estimated interaction matrix
-        
-        With full_output=True, returns
-            ent         : Estimated entropy
-            J           : Estimated interaction matrix
-            clusters    : List of clusters
-            deltaSdict  : 
-            deltaJdict  :
+        ndarray
+            Solved multipliers (parameters). For Ising problem, these can be converted
+            into matrix format using utils.vec2mat.
+        float (optional, only if full_output=True)
+            Estimated entropy.
+        ndarray
+            Solved multipliers (parameters). For Ising problem, these can be converted
+            into matrix format using utils.vec2mat.
+        list (optional, only if full_output=True)
+            List of clusters.
+        dict (optional, only if full_output=True)
+            deltaSdict
+        dict (optional, only if full_output=True)
+            deltaJdict
         """
 
         # convert input to coocMat
@@ -1776,7 +1785,7 @@ def solve(self, threshold,
         self.multipliers = convert_params( h, squareform(J)*2, '11', concat=True )
 
         if full_output:
-            return ent, self.multipliers, clusters, deltaSdict, deltaJdict
+            return self.multipliers, ent, clusters, deltaSdict, deltaJdict
         else:
             return self.multipliers
 # end ClusterExpansion
@@ -1840,6 +1849,8 @@ def solve(self,
         """Varies the strength of regularization on the mean field J to best fit given
         cooccurrence data.
         
+        Parameters
+        ----------
         n_grid_points : int, 200
             If bracket is given, first test at n_grid_points points evenly spaced in the
             bracket interval, then give the lowest three points to
@@ -1862,6 +1873,12 @@ def solve(self,
         priorLmbda : float,0.
             ** As of v1.0.3, not currently implemented **
             Strength of noninteracting prior.
+
+        Returns
+        -------
+        ndarray
+            Solved multipliers (parameters). For Ising problem, these can be converted
+            into matrix format using utils.vec2mat.
         """
 
         from scipy import transpose

coniii/test_utils.py

@@ -195,5 +195,12 @@ def test_base_repr():
         for power in range(1,7):
             assert ''.join(base_repr(i**power,i))=='1'+'0'*power
 
+def test_vec2mat():
+    for n in range(3,100):
+        x = np.random.rand(n+n*(n-1)//2)
+        assert np.array_equal(x, mat2vec(vec2mat(x)))
+        xvec, xmat = vec2mat(x, True)
+        assert np.array_equal(xvec, x[:n])
+
 if __name__=='__main__':
     test_convert_params()

coniii/utils.py

@@ -1140,3 +1140,51 @@ def coarse_grain_with_func(X, n_times, sim_func, coarse_func):
     binsix = originalIx
 
     return coarseX, binsix
+
+def vec2mat(multipliers, separate_fields=False):
+    """Convert vector of parameters containing fields and couplings to a matrix where the
+    diagonal elements are the fields and the remaining elements are the couplings. Fields
+    can be returned separately with the separate_fields keyword argument.
+
+    This is specific to the Ising model.
+    
+    Parameters
+    ----------
+    multipliers : ndarray
+        Vector of fields and couplings.
+    separate_fields : bool, False
+    
+    Returns
+    -------
+    ndarray
+        n x n matrix. Diagonal elements are fields *unless* separate_fields keyword
+        argument is True, in which case the diagonal elements are 0.
+    ndarray (optional)
+        Fields if separate_fields keyword argument is True.
+    """
+
+    n = (np.sqrt(1+8*multipliers.size)-1)//2
+    assert (n%1)==0, "Must be n fields and (n choose 2) couplings."
+    n = int(n)
+
+    if separate_fields:
+        return multipliers[:n], squareform(multipliers[n:])
+    return replace_diag(squareform(multipliers[n:]), multipliers[:n])
+
+def mat2vec(multipliers):
+    """Convert matrix form of Ising parameters to a vector. 
+
+    This is specific to the Ising model.
+    
+    Parameters
+    ----------
+    multipliers : ndarray
+        Matrix of couplings with diagonal elements as fields.
+    
+    Returns
+    -------
+    ndarray
+        Vector of fields and couplings, respectively.
+    """
+
+    return np.concatenate([multipliers.diagonal(), squareform(zero_diag(multipliers))])