Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

mention XtalConverter as top-level API, and other links to API #150

Merged
merged 2 commits into from
Jul 7, 2022
Merged

mention XtalConverter as top-level API, and other links to API #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7ff2224
mention XtalConverter as top-level API, and point to certain places i…
sgbaird Jul 7, 2022
02af1d0
fixup :func: syntax
sgbaird Jul 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,15 @@ After getting preliminary results, you get to decide whether it's worth it to yo
conda create -n xtal2png -c conda-forge xtal2png m3gnet
conda activate xtal2png
```
> NOTE: `m3gnet` is an optional dependency that performs surrogate DFT relaxation.
> NOTE: [`m3gnet`](https://github.com/materialsvirtuallab/m3gnet) is an optional dependency that performs surrogate DFT relaxation.

### Example

Here, we use the top-level
[`XtalConverter`](https://xtal2png.readthedocs.io/en/latest/api/xtal2png.html#xtal2png.core.XtalConverter)
class with and without optional relaxation via
[`m3gnet`](https://github.com/materialsvirtuallab/m3gnet).

```python
# example_structures is a list of `pymatgen.core.structure.Structure` objects
from xtal2png import XtalConverter, example_structures
Expand Down Expand Up @@ -121,10 +127,11 @@ The before and after structures match within an expected tolerance; note the rou
## Limitations and Design Considerations

There are some limitations and design considerations for `xtal2png`. While the round-off
error is a necessary evil for encoding to a PNG file format, the unrounded NumPy arrays
can be used directly instead if supported by the image model of interest. We choose a
error is a necessary evil for encoding to a [PNG file format](https://en.wikipedia.org/wiki/Portable_Network_Graphics), the unrounded NumPy arrays
can be used directly instead if supported by the image model of interest via
[`structures_to_arrays`](https://xtal2png.readthedocs.io/en/latest/api/xtal2png.html#xtal2png.core.XtalConverter.structures_to_arrays) and [`arrays_to_structures`](https://xtal2png.readthedocs.io/en/latest/api/xtal2png.html#xtal2png.XtalConverter.arrays_to_structures). We choose a
$64\times64$ representation by default which supports up to 52 sites within a unit cell.
The maximum number of sites can be adjusted which changes the size of the
The maximum number of sites [`max_sites`](https://xtal2png.readthedocs.io/en/latest/api/xtal2png.html#xtal2png.core.XtalConverter) can be adjusted which changes the size of the
representation. A square representation is used for greater compatibility with the
common limitation of image-based models supporting only square image arrays. The choice
of the default sidelength as a base-2 number (i.e. $2^6$) reflects common conventions of
Expand All @@ -141,6 +148,8 @@ particular crystal structures. In a future implementation, we plan to reconstruc
Euclidean coordinates from the distance matrices and homogenize (e.g. via weighted
averaging) the explicit fractional coordinates with the reconstructed coordinates.

See the docs for the full list of customizable parameters that `XtalConverter` takes.

## Installation

### Anaconda (`conda`) installation (recommended)
Expand Down
12 changes: 6 additions & 6 deletions src/xtal2png/core.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,16 +137,16 @@ class XtalConverter:
max_sites : int, optional
Maximum number of sites to accomodate in encoding, by default 52
save_dir : Union[str, 'PathLike[str]']
Directory to save PNG files via :func:``xtal2png``,
Directory to save PNG files via :func:`xtal2png`,
by default path.join("data", "interim")
symprec : Union[float, Tuple[float, float]], optional
The symmetry precision to use when decoding `pymatgen` structures via
``func:pymatgen.symmetry.analyzer.SpaceGroupAnalyzer.get_refined_structure``. If
:func:`pymatgen.symmetry.analyzer.SpaceGroupAnalyzer.get_refined_structure`. If
specified as a tuple, then ``symprec[0]`` applies to encoding and ``symprec[1]``
applies to decoding. By default 0.1.
angle_tolerance : Union[float, int, Tuple[float, float], Tuple[int, int]], optional
The angle tolerance (degrees) to use when decoding `pymatgen` structures via
``func:pymatgen.symmetry.analyzer.SpaceGroupAnalyzer.get_refined_structure``. If
:func:`pymatgen.symmetry.analyzer.SpaceGroupAnalyzer.get_refined_structure`. If
specified as a tuple, then ``angle_tolerance[0]`` applies to encoding and
``angle_tolerance[1]`` applies to decoding. By default 5.0.
encode_cell_type : Optional[str], optional
Expand All @@ -164,10 +164,10 @@ class XtalConverter:
channels : int, optional
Number of channels, a positive integer. Typically choices would be 1 (grayscale)
or 3 (RGB), and are the only compatible choices when using
func:``XtalConverter().xtal2png`` and func:``XtalConverter().png2xtal``. For
:func:`XtalConverter().xtal2png` and :func:`XtalConverter().png2xtal`. For
positive integers other than 1 or 3, use
func:``XtalConverter().structures_to_arrays`` and
func:``XtalConverter().arrays_to_structures`` directly instead.
:func:`XtalConverter().structures_to_arrays` and
:func:`XtalConverter().arrays_to_structures` directly instead.
verbose: bool, optional
Whether to print verbose debugging information or not.
element_encoding : str
Expand Down