README: add usage examples

Author: benoistlaurent

README.md

@@ -35,6 +35,9 @@ uv sync
 # Analyze a structure file
 uv run grodecoder path/to/structure.gro
 
+# Analyze a pair topology file + coordinates
+uv run grodecoder path/to/topology.psf /path/to/coordinates.coor
+
 # Output to stdout with compact format
 uv run grodecoder structure.pdb --compact --stdout
 
@@ -101,6 +104,40 @@ GROdecoder produces detailed JSON inventories with the following structure:
 
 ## 🔧 Advanced Features
 
+### Read back a Grodecoder inventory file
+
+Reading a Grodecoder inventory file is essential to be able to access the different parts of a system
+without having to identify them again:
+
+```python
+from grodecoder import read_grodecoder_output
+
+gro_results = read_grodecoder_output("1BRS_grodecoder.json")
+
+# Print the sequence of protein segment only.
+for segment in gro_results.decoded.inventory.segments:
+    if segment.is_protein():
+        print(segment.sequence)
+```
+
+In conjunction with the structure file, we can use the grodecoder output file to access the different
+parts of the system, as identified by grodecoder:
+
+```python
+import MDAnalysis
+from grodecoder import read_grodecoder_output
+
+
+universe = MDAnalysis.Universe("tests/data/1BRS.pdb")
+gro_results = read_grodecoder_output("1BRS_grodecoder.json")
+
+# Prints the center of mass of each protein segment.
+for segment in gro_results.decoded.inventory.segments:
+    if segment.is_protein():
+        seg: MDAnalysis.AtomGroup = universe.atoms[segment.atoms]
+        print(seg.center_of_mass())
+```
+
 ### Chain Detection
 GROdecoder uses sophisticated distance-based algorithms to detect protein and nucleic acid chains:
 

src/grodecoder/models.py

@@ -114,11 +114,36 @@ def serialize(self, handler: SerializerFunctionWrapHandler, info: SerializationI
         return self_data
 
 
-class SmallMolecule(FrozenWithAtoms):
+class MolecularTypeMixin:
+    molecular_type: MolecularType
+
+    def is_ion(self) -> bool:
+        return self.molecular_type == MolecularType.ION
+
+    def is_lipid(self) -> bool:
+        return self.molecular_type == MolecularType.LIPID
+
+    def is_solvent(self) -> bool:
+        return self.molecular_type == MolecularType.SOLVENT
+
+    def is_unknown(self) -> bool:
+        return self.molecular_type == MolecularType.UNKNOWN
+
+    def is_other(self) -> bool:
+        """Alias for MolecularTypeMixin.is_unknown()"""
+        return self.is_unknown()
+
+    def is_protein(self) -> bool:
+        return self.molecular_type == MolecularType.PROTEIN
+
+    def is_nucleic(self) -> bool:
+        return self.molecular_type == MolecularType.NUCLEIC
+
+
+class SmallMolecule(MolecularTypeMixin, FrozenWithAtoms):
     """Small molecules are defined as residues with a single residue name."""
 
     description: str
-    molecular_type: MolecularType
 
     @computed_field
     @property
@@ -127,11 +152,9 @@ def name(self) -> str:
         return self.atoms.residues[0].resname
 
 
-class Segment(FrozenWithAtoms):
+class Segment(MolecularTypeMixin, FrozenWithAtoms):
     """A segment is a group of atoms that are connected."""
 
-    molecular_type: MolecularType  # likely to be protein or nucleic acid
-
     @computed_field
     @property
     def sequence(self) -> str:
@@ -191,15 +214,13 @@ def check_number_of_atoms_is_valid(self):
         return self
 
 
-class SmallMoleculeRead(BaseModelWithAtomsRead):
+class SmallMoleculeRead(MolecularTypeMixin, BaseModelWithAtomsRead):
     name: str
     description: str
-    molecular_type: MolecularType
 
 
-class SegmentRead(BaseModelWithAtomsRead):
+class SegmentRead(MolecularTypeMixin, BaseModelWithAtomsRead):
     sequence: str
-    molecular_type: MolecularType
 
 
 class InventoryRead(FrozenModel):