refactor: rename particles argument to particle_db (#50)

This naming was introduced for check_reaction_violations (#40) and
makes more sense to the reader

docs/usage/particle.ipynb

@@ -57,7 +57,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In {doc}`reaction`, we made use of the {class}`.StateTransitionManager`. By default, if you do not specify the `particles` argument, the {class}`.StateTransitionManager` calls the function {func}`.load_default_particles`. This functions returns a {class}`.ParticleCollection` instance with {class}`.Particle` definitions from the [PDG](https://pdg.lbl.gov), along with additional definitions that are provided in the file {download}`additional_definitions.yml <../../src/qrules/additional_definitions.yml>`.\n",
+    "In {doc}`reaction`, we made use of the {class}`.StateTransitionManager`. By default, if you do not specify the `particle_db` argument, the {class}`.StateTransitionManager` calls the function {func}`.load_default_particles`. This functions returns a {class}`.ParticleCollection` instance with {class}`.Particle` definitions from the [PDG](https://pdg.lbl.gov), along with additional definitions that are provided in the file {download}`additional_definitions.yml <../../src/qrules/additional_definitions.yml>`.\n",
     "\n",
     "Here, we call this method directly to illustrate what happens (we use {func}`.load_pdg`, which loads a subset):"
    ]

src/qrules/__init__.py

@@ -208,7 +208,7 @@ def check_edge_qn_conservation() -> Set[FrozenSet[str]]:
 
     initial_facts = create_initial_facts(
         topology=topology,
-        particles=particle_db,
+        particle_db=particle_db,
         initial_state=initial_state,
         final_state=final_state,
     )
@@ -284,7 +284,7 @@ def generate_transitions(  # pylint: disable=too-many-arguments
     allowed_intermediate_particles: Optional[List[str]] = None,
     allowed_interaction_types: Optional[Union[str, List[str]]] = None,
     formalism_type: str = "helicity",
-    particles: Optional[ParticleCollection] = None,
+    particle_db: Optional[ParticleCollection] = None,
     mass_conservation_factor: Optional[float] = 3.0,
     max_angular_momentum: int = 2,
     max_spin_magnitude: float = 2.0,
@@ -318,7 +318,7 @@ def generate_transitions(  # pylint: disable=too-many-arguments
         formalism_type (`str`, optional): Formalism that you intend to use in
             the eventual amplitude model.
 
-        particles (`.ParticleCollection`, optional): The particles that you
+        particle_db (`.ParticleCollection`, optional): The particles that you
             want to be involved in the reaction. Uses `.load_pdg` by default.
             It's better to use a subset for larger reactions, because of
             the computation times. This argument is especially useful when you
@@ -354,7 +354,7 @@ def generate_transitions(  # pylint: disable=too-many-arguments
     ...     allowed_intermediate_particles=["a(0)(980)", "a(2)(1320)-"],
     ...     allowed_interaction_types="ew",
     ...     formalism_type="helicity",
-    ...     particles=q.load_pdg(),
+    ...     particle_db=q.load_pdg(),
     ...     topology_building="isobar",
     ... )
     >>> len(result.transitions)
@@ -369,7 +369,7 @@ def generate_transitions(  # pylint: disable=too-many-arguments
     stm = StateTransitionManager(
         initial_state=initial_state,  # type: ignore
         final_state=final_state,
-        particles=particles,
+        particle_db=particle_db,
         allowed_intermediate_particles=allowed_intermediate_particles,
         formalism_type=formalism_type,
         mass_conservation_factor=mass_conservation_factor,
@@ -432,8 +432,8 @@ def load_default_particles() -> ParticleCollection:
     :download:`additional_definitions.yml
     </../src/qrules/additional_definitions.yml>`.
     """
-    particles = load_pdg()
+    particle_db = load_pdg()
     additional_particles = io.load(ADDITIONAL_PARTICLES_DEFINITIONS_PATH)
     assert isinstance(additional_particles, ParticleCollection)
-    particles.update(additional_particles)
-    return particles
+    particle_db.update(additional_particles)
+    return particle_db

src/qrules/_system_control.py

@@ -82,7 +82,7 @@ def create_node_properties(
 
 
 def create_particle(
-    edge_props: GraphEdgePropertyMap, particles: ParticleCollection
+    edge_props: GraphEdgePropertyMap, particle_db: ParticleCollection
 ) -> ParticleWithSpin:
     """Create a Particle with spin projection from a qn dictionary.
 
@@ -91,16 +91,16 @@ def create_particle(
 
     Args:
         edge_props: The quantum number dictionary.
-        particles: A `.ParticleCollection` which is used to retrieve a
-          reference particle instance to lower the memory footprint.
+        particle_db: A `.ParticleCollection` which is used to retrieve a
+          reference `.particle` to lower the memory footprint.
 
     Raises:
         KeyError: If the edge properties do not contain the pid information or
           no particle with the same pid is found in the `.ParticleCollection`.
 
         ValueError: If the edge properties do not contain spin projection info.
     """
-    particle = particles.find(int(edge_props[EdgeQuantumNumbers.pid]))
+    particle = particle_db.find(int(edge_props[EdgeQuantumNumbers.pid]))
     if EdgeQuantumNumbers.spin_projection not in edge_props:
         raise ValueError(
             "GraphEdgePropertyMap does not contain a spin projection!"

src/qrules/combinatorics.py

@@ -230,7 +230,7 @@ def fill_groupings(
 
 def create_initial_facts(  # pylint: disable=too-many-locals
     topology: Topology,
-    particles: ParticleCollection,
+    particle_db: ParticleCollection,
     initial_state: Sequence[StateDefinition],
     final_state: Sequence[StateDefinition],
     final_state_groupings: Optional[
@@ -253,15 +253,15 @@ def embed_in_list(some_list: List[Any]) -> List[List[Any]]:
 
     kinematic_permutation_graphs = _generate_kinematic_permutations(
         topology=topology,
-        particles=particles,
+        particle_db=particle_db,
         initial_state=initial_state,
         final_state=final_state,
         allowed_kinematic_groupings=allowed_kinematic_groupings,
     )
     edge_initial_facts = list()
     for kinematic_permutation in kinematic_permutation_graphs:
         spin_permutations = _generate_spin_permutations(
-            kinematic_permutation, particles
+            kinematic_permutation, particle_db
         )
         edge_initial_facts.extend(
             [InitialFacts(edge_props=x) for x in spin_permutations]
@@ -271,7 +271,7 @@ def embed_in_list(some_list: List[Any]) -> List[List[Any]]:
 
 def _generate_kinematic_permutations(
     topology: Topology,
-    particles: ParticleCollection,
+    particle_db: ParticleCollection,
     initial_state: Sequence[StateDefinition],
     final_state: Sequence[StateDefinition],
     allowed_kinematic_groupings: Optional[
@@ -301,10 +301,10 @@ def is_allowed_grouping(
         return False
 
     initial_state_with_projections = _safe_set_spin_projections(
-        initial_state, particles
+        initial_state, particle_db
     )
     final_state_with_projections = _safe_set_spin_projections(
-        final_state, particles
+        final_state, particle_db
     )
 
     initial_facts_combinations: List[Dict[int, StateWithSpins]] = list()

src/qrules/io/_dot.py

@@ -224,7 +224,7 @@ def _get_particle_graphs(
     """Strip `list` of `.StateTransitionGraph` s of the spin projections.
 
     Extract a `list` of `.StateTransitionGraph` instances with only
-    particles on the edges.
+    `.Particle` instances on the edges.
 
     .. seealso:: :doc:`/usage/visualize`
     """

src/qrules/settings.py

@@ -95,7 +95,7 @@ class InteractionType(Enum):
 
 def create_interaction_settings(  # pylint: disable=too-many-locals,too-many-arguments
     formalism_type: str,
-    particles: ParticleCollection,
+    particle_db: ParticleCollection,
     nbody_topology: bool = False,
     mass_conservation_factor: Optional[float] = 3.0,
     max_angular_momentum: int = 2,
@@ -109,7 +109,7 @@ def create_interaction_settings(  # pylint: disable=too-many-locals,too-many-arg
             spin_validity,
         },
         rule_priorities=EDGE_RULE_PRIORITIES,
-        qn_domains=_create_domains(particles),
+        qn_domains=_create_domains(particle_db),
     )
     formalism_node_settings = NodeSettings(
         rule_priorities=CONSERVATION_LAW_PRIORITIES
@@ -235,7 +235,7 @@ def __get_spin_magnitudes(
     return _halves_domain(0, max_spin_magnitude)
 
 
-def _create_domains(particles: ParticleCollection) -> Dict[Any, list]:
+def _create_domains(particle_db: ParticleCollection) -> Dict[Any, list]:
     domains: Dict[Any, list] = {
         EdgeQN.electron_lepton_number: [-1, 0, +1],
         EdgeQN.muon_lepton_number: [-1, 0, +1],
@@ -253,17 +253,17 @@ def _create_domains(particles: ParticleCollection) -> Dict[Any, list]:
         EdgeQN.bottomness: lambda p: p.bottomness,
     }.items():
         domains[edge_qn] = __extend_negative(
-            __positive_int_domain(particles, getter)
+            __positive_int_domain(particle_db, getter)
         )
 
     domains[EdgeQN.spin_magnitude] = __positive_halves_domain(
-        particles, lambda p: p.spin
+        particle_db, lambda p: p.spin
     )
     domains[EdgeQN.spin_projection] = __extend_negative(
         domains[EdgeQN.spin_magnitude]
     )
     domains[EdgeQN.isospin_magnitude] = __positive_halves_domain(
-        particles,
+        particle_db,
         lambda p: 0 if p.isospin is None else p.isospin.magnitude,
     )
     domains[EdgeQN.isospin_projection] = __extend_negative(
@@ -273,16 +273,16 @@ def _create_domains(particles: ParticleCollection) -> Dict[Any, list]:
 
 
 def __positive_halves_domain(
-    particles: ParticleCollection, attr_getter: Callable[[Particle], Any]
+    particle_db: ParticleCollection, attr_getter: Callable[[Particle], Any]
 ) -> List[float]:
-    values = set(map(attr_getter, particles))
+    values = set(map(attr_getter, particle_db))
     return _halves_domain(0, max(values))
 
 
 def __positive_int_domain(
-    particles: ParticleCollection, attr_getter: Callable[[Particle], Any]
+    particle_db: ParticleCollection, attr_getter: Callable[[Particle], Any]
 ) -> List[int]:
-    values = set(map(attr_getter, particles))
+    values = set(map(attr_getter, particle_db))
     return _int_domain(0, max(values))
 
 

src/qrules/transition.py

@@ -255,7 +255,7 @@ def __init__(  # pylint: disable=too-many-arguments, too-many-branches, too-many
         self,
         initial_state: Sequence[StateDefinition],
         final_state: Sequence[StateDefinition],
-        particles: Optional[ParticleCollection] = None,
+        particle_db: Optional[ParticleCollection] = None,
         allowed_intermediate_particles: Optional[List[str]] = None,
         interaction_type_settings: Dict[
             InteractionType, Tuple[EdgeSettings, NodeSettings]
@@ -283,8 +283,8 @@ def __init__(  # pylint: disable=too-many-arguments, too-many-branches, too-many
             )
         self.__formalism_type = str(formalism_type)
         self.__particles = ParticleCollection()
-        if particles is not None:
-            self.__particles = particles
+        if particle_db is not None:
+            self.__particles = particle_db
         if number_of_threads is None:
             self.number_of_threads = multiprocessing.cpu_count()
         else:
@@ -335,7 +335,7 @@ def __init__(  # pylint: disable=too-many-arguments, too-many-branches, too-many
         if not self.interaction_type_settings:
             self.interaction_type_settings = create_interaction_settings(
                 formalism_type,
-                particles=self.__particles,
+                particle_db=self.__particles,
                 nbody_topology=use_nbody_topology,
                 mass_conservation_factor=mass_conservation_factor,
                 max_angular_momentum=max_angular_momentum,
@@ -415,7 +415,7 @@ def create_problem_sets(self) -> Dict[float, List[ProblemSet]]:
         for topology in self.__topologies:
             for initial_facts in create_initial_facts(
                 topology=topology,
-                particles=self.__particles,
+                particle_db=self.__particles,
                 initial_state=self.initial_state,
                 final_state=self.final_state,
                 final_state_groupings=self.final_state_groupings,

tests/channels/test_jpsi_to_gamma_pi0_pi0.py

@@ -30,7 +30,7 @@ def test_number_of_solutions(
     result = q.generate_transitions(
         initial_state=("J/psi(1S)", [-1, +1]),
         final_state=["gamma", "pi0", "pi0"],
-        particles=particle_database,
+        particle_db=particle_database,
         allowed_interaction_types="strong and EM",
         allowed_intermediate_particles=allowed_intermediate_particles,
         number_of_threads=1,
@@ -45,7 +45,7 @@ def test_id_to_particle_mappings(particle_database):
     result = q.generate_transitions(
         initial_state=("J/psi(1S)", [-1, +1]),
         final_state=["gamma", "pi0", "pi0"],
-        particles=particle_database,
+        particle_db=particle_database,
         allowed_interaction_types="strong",
         allowed_intermediate_particles=["f(0)(980)"],
         number_of_threads=1,

tests/channels/test_y_to_d0_d0bar_pi0_pi0.py

@@ -15,7 +15,7 @@ def test_simple(formalism_type, n_solutions, particle_database):
     result = q.generate_transitions(
         initial_state=[("Y(4260)", [-1, +1])],
         final_state=["D*(2007)0", "D*(2007)~0"],
-        particles=particle_database,
+        particle_db=particle_database,
         formalism_type=formalism_type,
         allowed_interaction_types="strong",
         number_of_threads=1,
@@ -35,7 +35,7 @@ def test_full(formalism_type, n_solutions, particle_database):
     stm = StateTransitionManager(
         initial_state=[("Y(4260)", [-1, +1])],
         final_state=["D0", "D~0", "pi0", "pi0"],
-        particles=particle_database,
+        particle_db=particle_database,
         allowed_intermediate_particles=["D*"],
         formalism_type=formalism_type,
         number_of_threads=1,

tests/unit/test_combinatorics.py

@@ -44,7 +44,7 @@ def test_initialize_graph(
         three_body_decay,
         initial_state=[("J/psi(1S)", [-1, +1])],
         final_state=["gamma", "pi0", "pi0"],
-        particles=particle_database,
+        particle_db=particle_database,
         final_state_groupings=final_state_groupings,
     )
     assert len(initial_facts) == 4
@@ -176,7 +176,7 @@ def test_generate_permutations(
         three_body_decay,
         initial_state=[("J/psi(1S)", [-1, +1])],
         final_state=["gamma", "pi0", "pi0"],
-        particles=particle_database,
+        particle_db=particle_database,
         allowed_kinematic_groupings=[_KinematicRepresentation(["pi0", "pi0"])],
     )
     assert len(permutations) == 1
@@ -185,7 +185,7 @@ def test_generate_permutations(
         three_body_decay,
         initial_state=[("J/psi(1S)", [-1, +1])],
         final_state=["gamma", "pi0", "pi0"],
-        particles=particle_database,
+        particle_db=particle_database,
     )
     assert len(permutations) == 2
     graph0_final_state_node1 = [

tests/unit/test_settings.py

@@ -13,8 +13,8 @@
 
 def test_create_domains(particle_database: ParticleCollection):
     pdg = particle_database
-    particles = pdg.filter(lambda p: p.name.startswith("pi"))
-    domains = _create_domains(particles)
+    pions = pdg.filter(lambda p: p.name.startswith("pi"))
+    domains = _create_domains(pions)
     assert len(domains) == 15
     assert domains[EdgeQN.baryon_number] == [0]
     assert domains[EdgeQN.strangeness] == [0]
@@ -43,7 +43,7 @@ def test_create_interaction_settings(
 ):
     settings = create_interaction_settings(
         formalism_type,
-        particles=particle_database,
+        particle_db=particle_database,
         nbody_topology=nbody_topology,
     )
     assert set(settings) == set(InteractionType)