function rename, and fix in docstring

xsuite · Jan 15, 2025 · e89f859 · e89f859
1 parent f508b00
commit e89f859
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 25 deletions.
diff --git a/tests/test_ibs_equilibrium_emittances.py b/tests/test_ibs_equilibrium_emittances.py
@@ -25,7 +25,7 @@ def test_ibs_emittance_constraints(emittance_constraint):
 
     emittance_coupling_factor = 0.02
 
-    time, emittances_x_list, emittances_y_list, emittances_z_list, T_x, T_y, T_z = xf.ibs.compute_emittance_evolution(
+    time, emittances_x_list, emittances_y_list, emittances_z_list, T_x, T_y, T_z = xf.ibs.compute_equilibrium_emittances_from_sr_and_ibs(
         twiss, bunch_intensity,
         emittance_coupling_factor=emittance_coupling_factor,
         emittance_constraint=emittance_constraint,
@@ -82,7 +82,7 @@ def test_ibs_emittance_coupling_factor(emittance_coupling_factor):
     # Equilibrium emittances calculations #
     #######################################
 
-    time, emittances_x_list, emittances_y_list, emittances_z_list, T_x, T_y, T_z = xf.ibs.compute_emittance_evolution(
+    time, emittances_x_list, emittances_y_list, emittances_z_list, T_x, T_y, T_z = xf.ibs.compute_equilibrium_emittances_from_sr_and_ibs(
         twiss, bunch_intensity,
         emittance_coupling_factor=emittance_coupling_factor,
     )
@@ -126,7 +126,7 @@ def test_ibs_emittance_no_constraint(emittance_coupling_factor):
     # Equilibrium emittances calculations #
     #######################################
 
-    time, emittances_x_list, emittances_y_list, emittances_z_list, T_x, T_y, T_z = xf.ibs.compute_emittance_evolution(
+    time, emittances_x_list, emittances_y_list, emittances_z_list, T_x, T_y, T_z = xf.ibs.compute_equilibrium_emittances_from_sr_and_ibs(
         twiss, bunch_intensity,
         initial_emittances=initial_emittances,
         emittance_coupling_factor=emittance_coupling_factor,

diff --git a/xfields/ibs/__init__.py b/xfields/ibs/__init__.py
@@ -6,13 +6,13 @@
 from ._analytical import BjorkenMtingwaIBS, IBSGrowthRates, NagaitsevIBS
 from ._api import configure_intrabeam_scattering, get_intrabeam_scattering_growth_rates
 from ._kicks import IBSAnalyticalKick, IBSKineticKick
-from ._equilibrium import compute_emittance_evolution
+from ._equilibrium import compute_equilibrium_emittances_from_sr_and_ibs
 
 __all__ = [
     "BjorkenMtingwaIBS",
     "configure_intrabeam_scattering",
     "get_intrabeam_scattering_growth_rates",
-    "compute_emittance_evolution",
+    "compute_equilibrium_emittances_from_sr_and_ibs",
     "IBSGrowthRates",
     "IBSAnalyticalKick",
     "IBSKineticKick",

diff --git a/xfields/ibs/_equilibrium.py b/xfields/ibs/_equilibrium.py
@@ -158,8 +158,10 @@ def _ibs_rates_and_emittance_derivatives(
     )
 
 
-# TODO: find a better, more explicit name for this
-def compute_emittance_evolution(
+# ----- Public API (to be integrated as method in TwissTable) ----- #
+
+
+def compute_equilibrium_emittances_from_sr_and_ibs(
     twiss: xt.TwissTable,
     formalism: Literal["Nagaitsev", "Bjorken-Mtingwa", "B&M"],
     total_beam_intensity: int,
@@ -252,22 +254,22 @@ def compute_emittance_evolution(
     xtrack.TwissTable
         The convergence calculations results. The table contains the following
         columns, as time-step by time-step quantities:
-            - time: time values at which quantities are computed, in [s]
-            - gemitt_x: horizontal geometric emittance values, in [m]
-            - gemitt_y: vertical geometric emittance values, in [m]
-            - gemitt_zeta: longitudinal geometric emittance values, in [m]
-            - Tx: horizontal IBS growth rate, in [s^-1]
-            - Ty: vertical IBS growth rate, in [s^-1]
-            - Tz: longitudinal IBS growth rate, in [s^-1]
+            - time: time values at which quantities are computed, in [s].
+            - gemitt_x: horizontal geometric emittance values, in [m].
+            - gemitt_y: vertical geometric emittance values, in [m].
+            - gemitt_zeta: longitudinal geometric emittance values, in [m].
+            - Tx: horizontal IBS growth rate, in [s^-1].
+            - Ty: vertical IBS growth rate, in [s^-1].
+            - Tz: longitudinal IBS growth rate, in [s^-1].
         The table also contains the following global quantities:
-            - damping_constants_s: radiation damping constants per second used for the calculations
-            - partition_numbers: damping partition numbers used for the calculations
-            - eq_gemitt_x: horizontal equilibrium geometric emittance from synchrotron radiation used, in [m]
-            - eq_gemitt_y: vertical equilibrium geometric emittance from synchrotron radiation used, in [m]
-            - eq_nemitt_zeta: longitudinal equilibrium normalized emittance from synchrotron radiation used, in [m]
-            - sr_ibs_eq_gemitt_x: final horizontal equilibrium geometric emittance converged to, in [m]
-            - sr_ibs_eq_gemitt_y: final vertical equilibrium geometric emittance converged to, in [m]
-            - sr_ibs_eq_gemitt_zeta: final longitudinal equilibrium geometric emittance converged to, in [m]
+            - damping_constants_s: radiation damping constants per second used.
+            - partition_numbers: damping partition numbers used.
+            - eq_gemitt_x: horizontal equilibrium geometric emittance from synchrotron radiation used, in [m].
+            - eq_gemitt_y: vertical equilibrium geometric emittance from synchrotron radiation used, in [m].
+            - eq_gemitt_zeta: longitudinal equilibrium geometric emittance from synchrotron radiation used, in [m].
+            - sr_ibs_eq_gemitt_x: final horizontal equilibrium geometric emittance converged to, in [m].
+            - sr_ibs_eq_gemitt_y: final vertical equilibrium geometric emittance converged to, in [m].
+            - sr_ibs_eq_gemitt_zeta: final longitudinal equilibrium geometric emittance converged to, in [m].
     """
     # ----------------------------------------------------------------------------------------------
     # TODO: Perform check for valid value of emittance_constraint but no value of emittance coupling factor
@@ -411,12 +413,12 @@ def compute_emittance_evolution(
         {
             "damping_constants_s": twiss.damping_constants_s,
             "partition_numbers": twiss.partition_numbers,
-            "sr_ibs_eq_gemitt_x": res_gemitt_x[-1],
-            "sr_ibs_eq_gemitt_y": res_gemitt_y[-1],
-            "sr_ibs_eq_gemitt_zeta": res_gemitt_zeta[-1],
             "eq_gemitt_x": twiss.eq_gemitt_x,
             "eq_gemitt_y": twiss.eq_gemitt_y,
             "eq_gemitt_zeta": twiss.eq_gemitt_zeta,
+            "sr_ibs_eq_gemitt_x": res_gemitt_x[-1],
+            "sr_ibs_eq_gemitt_y": res_gemitt_y[-1],
+            "sr_ibs_eq_gemitt_zeta": res_gemitt_zeta[-1],
         }
     )
     return result_table