feat: implement coefficient naming switch (#252)

* docs: illustrate how to configure coefficient names
* feat: implement switches for coefficient names
* feat: make name generator in amplitude builder public

docs/usage/helicity/formalism.ipynb

@@ -142,6 +142,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    ":::{margin}\n",
+    "\n",
+    "{ref}`usage/helicity/formalism:Coefficient names` shows how to generate different coefficient names.\n",
+    "\n",
+    ":::\n",
+    "\n",
     "From {attr}`.components` and {attr}`.parameter_defaults`, we can see that the canonical formalism has a larger number of amplitudes."
    ]
   },
@@ -365,13 +371,101 @@
     "    render_selection(cano_model),\n",
     ")"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Coefficient names"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In the previous section, we saw that the {class}`.HelicityAmplitudeBuilder` by default generates coefficient names that only contain **helicities of the decay products**, while coefficients generated by the {class}`.CanonicalAmplitudeBuilder` contain only **$LS$-combinations**. It's possible to tweak this behavior with the {attr}`~.HelicityAmplitudeBuilder.naming` attribute. Here are two extreme examples, where we generate coefficient names that contain $LS$-combinations, the helicities of each parent state, and the helicity of each decay product, as well as a {class}`.HelicityModel` of which the coefficient names only contain information about the resonances:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "reaction = qrules.generate_transitions(\n",
+    "    initial_state=(\"D(1)(2420)0\", [+1]),\n",
+    "    final_state=[\"K+\", \"K-\", \"K~0\"],\n",
+    "    allowed_intermediate_particles=[\"a(1)(1260)+\"],\n",
+    "    formalism=\"canonical-helicity\",\n",
+    ")\n",
+    "builder = ampform.get_builder(reaction)\n",
+    "builder.naming.insert_parent_helicities = True\n",
+    "builder.naming.insert_child_helicities = True\n",
+    "builder.naming.insert_ls_combinations = True\n",
+    "model = builder.formulate()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    },
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "amplitudes = [c for c in model.components if c.startswith(\"A\")]\n",
+    "assert len(model.parameter_defaults) == len(amplitudes)\n",
+    "sp.Matrix(model.parameter_defaults)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "builder.naming.insert_parent_helicities = False\n",
+    "builder.naming.insert_child_helicities = False\n",
+    "builder.naming.insert_ls_combinations = False\n",
+    "model = builder.formulate()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    },
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "assert len(model.parameter_defaults) == 1\n",
+    "display(*model.parameter_defaults)"
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
    "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.8.12"
   }
  },
  "nbformat": 4,

src/ampform/helicity/__init__.py

@@ -63,6 +63,7 @@
 from .naming import (
     CanonicalAmplitudeNameGenerator,
     HelicityAmplitudeNameGenerator,
+    NameGenerator,
     generate_transition_label,
     get_helicity_angle_label,
     get_helicity_suffix,
@@ -509,7 +510,11 @@ def __init__(
                 " genenerate an amplitude model!"
             )
         self.__reaction = reaction
-        self._name_generator = HelicityAmplitudeNameGenerator(reaction)
+        self.naming: NameGenerator = HelicityAmplitudeNameGenerator(reaction)
+        """Name generator for amplitude names and coefficient names.
+
+        .. seealso:: :ref:`usage/helicity/formalism:Coefficient names`.
+        """
         self.__ingredients = _HelicityModelIngredients()
         self.__dynamics_choices = DynamicsSelector(reaction)
         self.__adapter = HelicityAdapter(reaction)
@@ -708,7 +713,7 @@ def __formulate_sequential_decay(
         expression = coefficient * sequential_amplitudes
         if prefactor is not None:
             expression = prefactor * expression
-        subscript = self._name_generator.generate_amplitude_name(transition)
+        subscript = self.naming.generate_amplitude_name(transition)
         self.__ingredients.components[f"A_{{{subscript}}}"] = expression
         return expression
 
@@ -751,9 +756,7 @@ def __generate_amplitude_coefficient(
         should check itself if it or a parity partner is already defined. If so
         a coupled coefficient is introduced.
         """
-        suffix = self._name_generator.generate_sequential_amplitude_suffix(
-            transition
-        )
+        suffix = self.naming.generate_sequential_amplitude_suffix(transition)
         symbol = sp.Symbol(f"C_{{{suffix}}}")
         value = complex(1, 0)
         self.__ingredients.parameter_defaults[symbol] = value
@@ -765,16 +768,18 @@ def __generate_amplitude_prefactor(
         prefactor = get_prefactor(transition)
         if prefactor != 1.0:
             for node_id in transition.topology.nodes:
-                raw_suffix = self._name_generator.generate_coefficient_name(
+                raw_suffix = self.naming.generate_coefficient_suffix(
                     transition, node_id
                 )
                 if (
                     raw_suffix
-                    in self._name_generator.parity_partner_coefficient_mapping
+                    in self.naming.parity_partner_coefficient_mapping
                 ):
-                    coefficient_suffix = self._name_generator.parity_partner_coefficient_mapping[
-                        raw_suffix
-                    ]
+                    coefficient_suffix = (
+                        self.naming.parity_partner_coefficient_mapping[
+                            raw_suffix
+                        ]
+                    )
                     if coefficient_suffix != raw_suffix:
                         return prefactor
         return None
@@ -861,7 +866,7 @@ class CanonicalAmplitudeBuilder(HelicityAmplitudeBuilder):
 
     def __init__(self, reaction: ReactionInfo) -> None:
         super().__init__(reaction)
-        self._name_generator = CanonicalAmplitudeNameGenerator(reaction)
+        self.naming = CanonicalAmplitudeNameGenerator(reaction)
 
     def _formulate_partial_decay(
         self, transition: StateTransition, node_id: int