Skip to content

atomlib.mixins

AtomsIOMixin

Bases: _HasAtoms, ABC

Mix-in to add IO methods to HasAtoms.

All concrete subclasses of HasAtoms should also subclass this.

Source code in atomlib/mixins.py 
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
class AtomsIOMixin(_HasAtoms, abc.ABC):
    """
    Mix-in to add IO methods to [`HasAtoms`][atomlib.atoms.HasAtoms].

    All concrete subclasses of [`HasAtoms`][atomlib.atoms.HasAtoms] should also subclass this.
    """

    @t.overload
    @classmethod
    def read(cls: t.Type[HasAtomsT], path: FileOrPath, ty: FileType) -> HasAtomsT:
        ...

    @t.overload
    @classmethod
    def read(cls: t.Type[HasAtomsT], path: t.Union[str, Path, t.TextIO], ty: t.Literal[None] = None) -> HasAtomsT:
        ...

    @classmethod
    def read(cls: t.Type[HasAtomsT], path: FileOrPath, ty: t.Optional[FileType] = None) -> HasAtomsT:
        """
        Read a structure from a file.

        Supported types can be found in the [io][atomlib.io] module.
        If no `ty` is specified, it is inferred from the file's extension.
        """
        from .io import read
        return _cast_atoms(read(path, ty), cls)  # type: ignore

    @classmethod
    def read_cif(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, CIF, CIFDataBlock], block: t.Union[int, str, None] = None) -> HasAtomsT:
        """
        Read a structure from a CIF file.

        If `block` is specified, read data from the given block of the CIF file (index or name).
        """
        from .io import read_cif
        return _cast_atoms(read_cif(f, block), cls)

    @classmethod
    def read_xyz(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, XYZ]) -> HasAtomsT:
        """Read a structure from an XYZ file."""
        from .io import read_xyz
        return _cast_atoms(read_xyz(f), cls)

    @classmethod
    def read_xsf(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, XSF]) -> HasAtomsT:
        """Read a structure from an XSF file."""
        from .io import read_xsf
        return _cast_atoms(read_xsf(f), cls)

    @classmethod
    def read_cfg(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, CFG]) -> HasAtomsT:
        """Read a structure from a CFG file."""
        from .io import read_cfg
        return _cast_atoms(read_cfg(f), cls)

    @classmethod
    def read_lmp(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, LMP], type_map: t.Optional[t.Dict[int, t.Union[str, int]]] = None) -> HasAtomsT:
        """Read a structure from a LAAMPS data file."""
        from .io import read_lmp
        return _cast_atoms(read_lmp(f, type_map=type_map), cls)

    def write_cif(self, f: FileOrPath):
        from .io import write_cif
        write_cif(self, f)

    def write_xyz(self, f: FileOrPath, fmt: XYZFormat = 'exyz'):
        from .io import write_xyz
        write_xyz(self, f, fmt)

    def write_xsf(self, f: FileOrPath):
        from .io import write_xsf
        write_xsf(self, f)

    def write_cfg(self, f: FileOrPath):
        from .io import write_cfg
        write_cfg(self, f)

    def write_lmp(self, f: FileOrPath):
        from .io import write_lmp
        write_lmp(self, f)

    @t.overload
    def write(self, path: FileOrPath, ty: FileType):
        ...

    @t.overload
    def write(self, path: t.Union[str, Path, t.TextIO], ty: t.Literal[None] = None):
        ...

    def write(self, path: FileOrPath, ty: t.Optional[FileType] = None):
        """
        Write this structure to a file.

        A file type may be specified using `ty`.
        If no `ty` is specified, it is inferred from the path's extension.
        """
        from .io import write
        write(self, path, ty)  # type: ignore

read classmethod 

read(path: FileOrPath, ty: FileType) -> HasAtomsT

read(
    path: Union[str, Path, TextIO], ty: Literal[None] = None
) -> HasAtomsT

read(
    path: FileOrPath, ty: Optional[FileType] = None
) -> HasAtomsT

Read a structure from a file.

Supported types can be found in the io module. If no ty is specified, it is inferred from the file's extension.

Source code in atomlib/mixins.py 
62
63
64
65
66
67
68
69
70
71
@classmethod
def read(cls: t.Type[HasAtomsT], path: FileOrPath, ty: t.Optional[FileType] = None) -> HasAtomsT:
    """
    Read a structure from a file.

    Supported types can be found in the [io][atomlib.io] module.
    If no `ty` is specified, it is inferred from the file's extension.
    """
    from .io import read
    return _cast_atoms(read(path, ty), cls)  # type: ignore

read_cif classmethod 

read_cif(
    f: Union[FileOrPath, CIF, CIFDataBlock],
    block: Union[int, str, None] = None,
) -> HasAtomsT

Read a structure from a CIF file.

If block is specified, read data from the given block of the CIF file (index or name).

Source code in atomlib/mixins.py 
73
74
75
76
77
78
79
80
81
@classmethod
def read_cif(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, CIF, CIFDataBlock], block: t.Union[int, str, None] = None) -> HasAtomsT:
    """
    Read a structure from a CIF file.

    If `block` is specified, read data from the given block of the CIF file (index or name).
    """
    from .io import read_cif
    return _cast_atoms(read_cif(f, block), cls)

read_xyz classmethod 

read_xyz(f: Union[FileOrPath, XYZ]) -> HasAtomsT

Read a structure from an XYZ file.

Source code in atomlib/mixins.py 
83
84
85
86
87
@classmethod
def read_xyz(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, XYZ]) -> HasAtomsT:
    """Read a structure from an XYZ file."""
    from .io import read_xyz
    return _cast_atoms(read_xyz(f), cls)

read_xsf classmethod 

read_xsf(f: Union[FileOrPath, XSF]) -> HasAtomsT

Read a structure from an XSF file.

Source code in atomlib/mixins.py 
89
90
91
92
93
@classmethod
def read_xsf(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, XSF]) -> HasAtomsT:
    """Read a structure from an XSF file."""
    from .io import read_xsf
    return _cast_atoms(read_xsf(f), cls)

read_cfg classmethod 

read_cfg(f: Union[FileOrPath, CFG]) -> HasAtomsT

Read a structure from a CFG file.

Source code in atomlib/mixins.py 
95
96
97
98
99
@classmethod
def read_cfg(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, CFG]) -> HasAtomsT:
    """Read a structure from a CFG file."""
    from .io import read_cfg
    return _cast_atoms(read_cfg(f), cls)

read_lmp classmethod 

read_lmp(
    f: Union[FileOrPath, LMP],
    type_map: Optional[Dict[int, Union[str, int]]] = None,
) -> HasAtomsT

Read a structure from a LAAMPS data file.

Source code in atomlib/mixins.py 
101
102
103
104
105
@classmethod
def read_lmp(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, LMP], type_map: t.Optional[t.Dict[int, t.Union[str, int]]] = None) -> HasAtomsT:
    """Read a structure from a LAAMPS data file."""
    from .io import read_lmp
    return _cast_atoms(read_lmp(f, type_map=type_map), cls)

write_cif 

write_cif(f: FileOrPath)
Source code in atomlib/mixins.py 
107
108
109
def write_cif(self, f: FileOrPath):
    from .io import write_cif
    write_cif(self, f)

write_xyz 

write_xyz(f: FileOrPath, fmt: XYZFormat = 'exyz')
Source code in atomlib/mixins.py 
111
112
113
def write_xyz(self, f: FileOrPath, fmt: XYZFormat = 'exyz'):
    from .io import write_xyz
    write_xyz(self, f, fmt)

write_xsf 

write_xsf(f: FileOrPath)
Source code in atomlib/mixins.py 
115
116
117
def write_xsf(self, f: FileOrPath):
    from .io import write_xsf
    write_xsf(self, f)

write_cfg 

write_cfg(f: FileOrPath)
Source code in atomlib/mixins.py 
119
120
121
def write_cfg(self, f: FileOrPath):
    from .io import write_cfg
    write_cfg(self, f)

write_lmp 

write_lmp(f: FileOrPath)
Source code in atomlib/mixins.py 
123
124
125
def write_lmp(self, f: FileOrPath):
    from .io import write_lmp
    write_lmp(self, f)

write 

write(path: FileOrPath, ty: FileType)

write(
    path: Union[str, Path, TextIO], ty: Literal[None] = None
)

write(path: FileOrPath, ty: Optional[FileType] = None)

Write this structure to a file.

A file type may be specified using ty. If no ty is specified, it is inferred from the path's extension.

Source code in atomlib/mixins.py 
135
136
137
138
139
140
141
142
143
def write(self, path: FileOrPath, ty: t.Optional[FileType] = None):
    """
    Write this structure to a file.

    A file type may be specified using `ty`.
    If no `ty` is specified, it is inferred from the path's extension.
    """
    from .io import write
    write(self, path, ty)  # type: ignore

AtomCellIOMixin

Bases: _HasAtomCell, AtomsIOMixin

Mix-in to add IO methods to HasAtomCell.

All concrete subclasses of HasAtomCell should also subclass this.

Source code in atomlib/mixins.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
class AtomCellIOMixin(_HasAtomCell, AtomsIOMixin):
    """
    Mix-in to add IO methods to [`HasAtomCell`][atomlib.atomcell.HasAtomCell].

    All concrete subclasses of [`HasAtomCell`][atomlib.atomcell.HasAtomCell] should also subclass this.
    """

    def write_mslice(self, f: BinaryFileOrPath, template: t.Optional[MSliceFile] = None, *,
                 slice_thickness: t.Optional[float] = None,  # angstrom
                 scan_points: t.Optional[ArrayLike] = None,
                 scan_extent: t.Optional[ArrayLike] = None,
                 noise_sigma: t.Optional[float] = None,  # angstrom
                 conv_angle: t.Optional[float] = None,  # mrad
                 energy: t.Optional[float] = None,  # keV
                 defocus: t.Optional[float] = None,  # angstrom
                 tilt: t.Optional[t.Tuple[float, float]] = None,  # (mrad, mrad)
                 tds: t.Optional[bool] = None,
                 n_cells: t.Optional[ArrayLike] = None):
        """
        Write a structure to an mslice file.

        `template` may be a file, path, or `ElementTree` containing an existing mslice file.
        Its structure will be modified to make the final output. If not specified, a default
        template will be used.

        Additional options modify simulation properties. If an option is not specified, the
        template's properties are used.
        """
        from .io import write_mslice
        return write_mslice(self, f, template, slice_thickness=slice_thickness,
                            scan_points=scan_points, scan_extent=scan_extent,
                            conv_angle=conv_angle, energy=energy, defocus=defocus,
                            noise_sigma=noise_sigma, tilt=tilt, tds=tds, n_cells=n_cells)

    def write_qe(self, f: FileOrPath, pseudo: t.Optional[t.Mapping[str, str]] = None):
        """
        Write a structure to a Quantum Espresso pw.x file.

        Args:
          f: File or path to write to
          pseudo: Mapping from atom symbol
        """
        from .io import write_qe
        write_qe(self, f, pseudo)

read classmethod 

read(path: FileOrPath, ty: FileType) -> HasAtomsT

read(
    path: Union[str, Path, TextIO], ty: Literal[None] = None
) -> HasAtomsT

read(
    path: FileOrPath, ty: Optional[FileType] = None
) -> HasAtomsT

Read a structure from a file.

Supported types can be found in the io module. If no ty is specified, it is inferred from the file's extension.

Source code in atomlib/mixins.py 
62
63
64
65
66
67
68
69
70
71
@classmethod
def read(cls: t.Type[HasAtomsT], path: FileOrPath, ty: t.Optional[FileType] = None) -> HasAtomsT:
    """
    Read a structure from a file.

    Supported types can be found in the [io][atomlib.io] module.
    If no `ty` is specified, it is inferred from the file's extension.
    """
    from .io import read
    return _cast_atoms(read(path, ty), cls)  # type: ignore

read_cif classmethod 

read_cif(
    f: Union[FileOrPath, CIF, CIFDataBlock],
    block: Union[int, str, None] = None,
) -> HasAtomsT

Read a structure from a CIF file.

If block is specified, read data from the given block of the CIF file (index or name).

Source code in atomlib/mixins.py 
73
74
75
76
77
78
79
80
81
@classmethod
def read_cif(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, CIF, CIFDataBlock], block: t.Union[int, str, None] = None) -> HasAtomsT:
    """
    Read a structure from a CIF file.

    If `block` is specified, read data from the given block of the CIF file (index or name).
    """
    from .io import read_cif
    return _cast_atoms(read_cif(f, block), cls)

read_xyz classmethod 

read_xyz(f: Union[FileOrPath, XYZ]) -> HasAtomsT

Read a structure from an XYZ file.

Source code in atomlib/mixins.py 
83
84
85
86
87
@classmethod
def read_xyz(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, XYZ]) -> HasAtomsT:
    """Read a structure from an XYZ file."""
    from .io import read_xyz
    return _cast_atoms(read_xyz(f), cls)

read_xsf classmethod 

read_xsf(f: Union[FileOrPath, XSF]) -> HasAtomsT

Read a structure from an XSF file.

Source code in atomlib/mixins.py 
89
90
91
92
93
@classmethod
def read_xsf(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, XSF]) -> HasAtomsT:
    """Read a structure from an XSF file."""
    from .io import read_xsf
    return _cast_atoms(read_xsf(f), cls)

read_cfg classmethod 

read_cfg(f: Union[FileOrPath, CFG]) -> HasAtomsT

Read a structure from a CFG file.

Source code in atomlib/mixins.py 
95
96
97
98
99
@classmethod
def read_cfg(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, CFG]) -> HasAtomsT:
    """Read a structure from a CFG file."""
    from .io import read_cfg
    return _cast_atoms(read_cfg(f), cls)

read_lmp classmethod 

read_lmp(
    f: Union[FileOrPath, LMP],
    type_map: Optional[Dict[int, Union[str, int]]] = None,
) -> HasAtomsT

Read a structure from a LAAMPS data file.

Source code in atomlib/mixins.py 
101
102
103
104
105
@classmethod
def read_lmp(cls: t.Type[HasAtomsT], f: t.Union[FileOrPath, LMP], type_map: t.Optional[t.Dict[int, t.Union[str, int]]] = None) -> HasAtomsT:
    """Read a structure from a LAAMPS data file."""
    from .io import read_lmp
    return _cast_atoms(read_lmp(f, type_map=type_map), cls)

write_cif 

write_cif(f: FileOrPath)
Source code in atomlib/mixins.py 
107
108
109
def write_cif(self, f: FileOrPath):
    from .io import write_cif
    write_cif(self, f)

write_xyz 

write_xyz(f: FileOrPath, fmt: XYZFormat = 'exyz')
Source code in atomlib/mixins.py 
111
112
113
def write_xyz(self, f: FileOrPath, fmt: XYZFormat = 'exyz'):
    from .io import write_xyz
    write_xyz(self, f, fmt)

write_xsf 

write_xsf(f: FileOrPath)
Source code in atomlib/mixins.py 
115
116
117
def write_xsf(self, f: FileOrPath):
    from .io import write_xsf
    write_xsf(self, f)

write_cfg 

write_cfg(f: FileOrPath)
Source code in atomlib/mixins.py 
119
120
121
def write_cfg(self, f: FileOrPath):
    from .io import write_cfg
    write_cfg(self, f)

write_lmp 

write_lmp(f: FileOrPath)
Source code in atomlib/mixins.py 
123
124
125
def write_lmp(self, f: FileOrPath):
    from .io import write_lmp
    write_lmp(self, f)

write 

write(path: FileOrPath, ty: FileType)

write(
    path: Union[str, Path, TextIO], ty: Literal[None] = None
)

write(path: FileOrPath, ty: Optional[FileType] = None)

Write this structure to a file.

A file type may be specified using ty. If no ty is specified, it is inferred from the path's extension.

Source code in atomlib/mixins.py 
135
136
137
138
139
140
141
142
143
def write(self, path: FileOrPath, ty: t.Optional[FileType] = None):
    """
    Write this structure to a file.

    A file type may be specified using `ty`.
    If no `ty` is specified, it is inferred from the path's extension.
    """
    from .io import write
    write(self, path, ty)  # type: ignore

write_mslice 

write_mslice(
    f: BinaryFileOrPath,
    template: Optional[MSliceFile] = None,
    *,
    slice_thickness: Optional[float] = None,
    scan_points: Optional[ArrayLike] = None,
    scan_extent: Optional[ArrayLike] = None,
    noise_sigma: Optional[float] = None,
    conv_angle: Optional[float] = None,
    energy: Optional[float] = None,
    defocus: Optional[float] = None,
    tilt: Optional[Tuple[float, float]] = None,
    tds: Optional[bool] = None,
    n_cells: Optional[ArrayLike] = None
)

Write a structure to an mslice file.

template may be a file, path, or ElementTree containing an existing mslice file. Its structure will be modified to make the final output. If not specified, a default template will be used.

Additional options modify simulation properties. If an option is not specified, the template's properties are used.

Source code in atomlib/mixins.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def write_mslice(self, f: BinaryFileOrPath, template: t.Optional[MSliceFile] = None, *,
             slice_thickness: t.Optional[float] = None,  # angstrom
             scan_points: t.Optional[ArrayLike] = None,
             scan_extent: t.Optional[ArrayLike] = None,
             noise_sigma: t.Optional[float] = None,  # angstrom
             conv_angle: t.Optional[float] = None,  # mrad
             energy: t.Optional[float] = None,  # keV
             defocus: t.Optional[float] = None,  # angstrom
             tilt: t.Optional[t.Tuple[float, float]] = None,  # (mrad, mrad)
             tds: t.Optional[bool] = None,
             n_cells: t.Optional[ArrayLike] = None):
    """
    Write a structure to an mslice file.

    `template` may be a file, path, or `ElementTree` containing an existing mslice file.
    Its structure will be modified to make the final output. If not specified, a default
    template will be used.

    Additional options modify simulation properties. If an option is not specified, the
    template's properties are used.
    """
    from .io import write_mslice
    return write_mslice(self, f, template, slice_thickness=slice_thickness,
                        scan_points=scan_points, scan_extent=scan_extent,
                        conv_angle=conv_angle, energy=energy, defocus=defocus,
                        noise_sigma=noise_sigma, tilt=tilt, tds=tds, n_cells=n_cells)

write_qe 

write_qe(
    f: FileOrPath,
    pseudo: Optional[Mapping[str, str]] = None,
)

Write a structure to a Quantum Espresso pw.x file.

PARAMETER DESCRIPTION
f

File or path to write to

TYPE: FileOrPath

pseudo

Mapping from atom symbol

TYPE: Optional[Mapping[str, str]] DEFAULT: None

Source code in atomlib/mixins.py 
180
181
182
183
184
185
186
187
188
189
def write_qe(self, f: FileOrPath, pseudo: t.Optional[t.Mapping[str, str]] = None):
    """
    Write a structure to a Quantum Espresso pw.x file.

    Args:
      f: File or path to write to
      pseudo: Mapping from atom symbol
    """
    from .io import write_qe
    write_qe(self, f, pseudo)