Improve support for ASE's io library (#238)

1. Changes keyword argument in `from_multii_systems` for
file format from `fmt` to `ase_fmt` to not collide with the
keyword argument name used in `MultiSystems.from_file`.
2. Adds documentation to the main README and ASE plugin class

Co-authored-by: Han Wang <[email protected]>
Co-authored-by: Han Wang <[email protected]>

Author: 3 people

README.md

@@ -82,14 +82,15 @@ The `System` or `LabeledSystem` can be constructed from the following file forma
 | Gromacs | gro         | True         | False   | System        | 'gromacs/gro'        |
 | ABACUS  | STRU        | False        | True    | LabeledSystem | 'abacus/scf'         |
 | ABACUS  | cif         | True         | True    | LabeledSystem | 'abacus/md'          |
+| ase     | structure   | True         | True    | MultiSystems  | 'ase/structure'      |
 
 
 The Class `dpdata.MultiSystems`  can read data  from a dir which may contains many files of different systems, or from single xyz file which contains different systems.
 
 Use `dpdata.MultiSystems.from_dir` to read from a  directory, `dpdata.MultiSystems` will walk in the directory 
 Recursively  and  find all file with specific file_name. Supports all the file formats that `dpdata.LabeledSystem` supports.
 
-Use  `dpdata.MultiSystems.from_file` to read from single file. Now only support quip/gap/xyz  format file.
+Use  `dpdata.MultiSystems.from_file` to read from single file. Single-file support is available for the `quip/gap/xyz` and `ase/structure` formats.
 
 For example, for `quip/gap xyz` files, single .xyz file may contain many different configurations with different atom numbers and atom type.
 

dpdata/plugins/ase.py

@@ -9,11 +9,20 @@
 
 @Format.register("ase/structure")
 class ASEStructureFormat(Format):
+    """Format for the `Atomic Simulation Environment <https://wiki.fysik.dtu.dk/ase/>`_ (ase).
+
+    ASE supports parsing a few dozen of data formats. As described in i
+    `the documentation <ihttps://wiki.fysik.dtu.dk/ase/ase/io/io.html>`_,
+    many of these formats can be determined automatically.
+    Use the `ase_fmt` keyword argument to supply the format if
+    automatic detection fails.
+    """
+
     def from_labeled_system(self, data, **kwargs):
         return data
 
-    def from_multi_systems(self, file_name, begin=None, end=None, step=None, fmt='traj', **kwargs):
-        frames = ase.io.read(file_name, format=fmt, index=slice(begin, end, step))
+    def from_multi_systems(self, file_name, begin=None, end=None, step=None, ase_fmt=None, **kwargs):
+        frames = ase.io.read(file_name, format=ase_fmt, index=slice(begin, end, step))
         for atoms in frames:
             symbols = atoms.get_chemical_symbols()
             atom_names = list(set(symbols))