Function for bounding number of Trotter steps required (#121)

* Added function for computing Trotter step requirements

* Change + test to enforce rtype int in Python2

* Corrected Trotter number bound

Author: idk3

src/fermilib/utils/_trotter_error.py

@@ -13,7 +13,7 @@
 """Module to compute the second order Trotter error."""
 from future.utils import iteritems
 
-from math import sqrt
+from math import sqrt, ceil
 from scipy.linalg import expm
 
 from fermilib.config import *
@@ -164,3 +164,23 @@ def error_bound(terms, tight=False):
                 error += 4.0 * abs(coefficient_a) * error_a ** 2
 
     return error
+
+
+def trotter_steps_required(trotter_error_bound, time, energy_precision):
+    """Determine the number of Trotter steps for accurate simulation.
+
+    Args:
+        trotter_error_bound (float): Upper bound on Trotter error in the
+                                     state of interest.
+        time (float): The total simulation time.
+        energy_precision (float): Acceptable shift in state energy.
+
+    Returns:
+        The integer minimum number of Trotter steps required for
+        simulation to the desired precision.
+
+    Notes:
+        The number of Trotter steps required is an upper bound on the
+        true requirement, which may be lower.
+    """
+    return int(ceil(time * sqrt(trotter_error_bound / energy_precision)))

src/fermilib/utils/_trotter_error_test.py

@@ -148,3 +148,16 @@ def test_error_bound_qubit_tight_less_than_loose_integration(self):
         terms = [QubitOperator('X1'), QubitOperator('Y1'), QubitOperator('Z1')]
         self.assertLess(error_bound(terms, tight=True),
                         error_bound(terms, tight=False))
+
+
+class TrotterStepsRequiredTest(unittest.TestCase):
+    def test_trotter_steps_required(self):
+        self.assertEqual(trotter_steps_required(
+            trotter_error_bound=0.3, time=2.5, energy_precision=0.04), 7)
+
+    def test_trotter_steps_required_negative_time(self):
+        self.assertEqual(trotter_steps_required(
+            trotter_error_bound=0.1, time=3.3, energy_precision=0.11), 4)
+
+    def test_return_type(self):
+        self.assertIsInstance(trotter_steps_required(0.1, 0.1, 0.1), int)