35 proposal make failed generate output structures (#36)

* Update ignore list

* Swap order of placement list

* Fix shuffle for both dimensions

* Improve error handling

* Add procedures to remove atoms

* Change void placement grid handling

* Update generate error handling and structure output

* Add calculator option

* Add example host structures

* Update tutorials

* Update learning scripts

* Fix unit tests

* Fix indentation

* Fix indentation

Author: nedtaylor

.gitignore

@@ -50,4 +50,5 @@ DVASP_MACE_comparison/
 pca_model*.pkl
 .benchmarks/
 .local-pre-commit-config.yaml
-*.tgz
+*.tgz
+.ipynb_checkpoints

app/inputs.f90

@@ -126,7 +126,7 @@ subroutine set_global_vars()
              write(0,'("&
                   &ERROR: No input filename supplied, &
                   &but the flag ''-f'' was used&
-                  &")')
+             &")')
              infilename_do: do j = 1, 3
                 write(6,'("Please supply an input filename:")')
                 read(5,'(A)') input_file
@@ -157,7 +157,7 @@ subroutine set_global_vars()
           write(6,'("-----------------FILE-NAME-FLAGS-----------------")')
           write(6,'(2X,"-f<STR>         : Input structure file name (&
                &Default = (empty)&
-               &).")')
+          &).")')
           stop
        end if
     end do flagloop

docs/source/index.rst

@@ -15,8 +15,10 @@ An example
 
 .. code-block:: python
 
-    # A simple example of how to use RAFFLE to generate 10 structures of diamond
+    # A simple example of how to use RAFFLE to generate 10 structures of diamond and write them to a single file
     from ase import Atoms
+    from ase.io import write
+    from ase.calculators.singlepoint import SinglePointCalculator
     from raffle.generator import raffle_generator
     from mace.calculators import mace_mp
 
@@ -41,6 +43,16 @@ An example
         generator.distributions.update(structures[num_structures_old:])
         num_structures_old = len(structures)
 
+    structures = generator.get_structures(calc)
+    for structure in structures:
+        structure.calc = SinglePointCalculator(
+            structure,
+            energy=structure.get_potential_energy(),
+            forces=structure.get_forces()
+        )
+ 
+    write('structures.traj', structures)
+
 .. toctree::
    :maxdepth: 3
    :caption: Contents:

docs/source/tutorials/BaTiO3_tutorial.rst

@@ -0,0 +1,116 @@
+.. si-ge:
+
+========================
+Si|Ge interface tutorial
+========================
+
+This tutorial will guide you through the process of performing RAFFLE-based structure search for an Si|Ge interface.
+
+The tutorial is designed to show how a RAFFLE generator given no prior knowledge can learn bonding and statistically available interface configurations.
+Statistically available configurations are those that are likely to exist due to energetic values close to the ground state, within thermal and entropy conditions.
+
+The example script can be found in the following directory:
+
+.. code-block:: bash
+
+    raffle/example/python_pkg/Si-Ge_learn/learn.py
+
+We recommend reading through the file and running it to understand the process of learning and generating structures.
+However, we will provide a brief overview of the script here.
+
+First, we must import the required packages:
+
+.. code-block:: python
+
+    from ase import Atoms
+    from raffle.generator import raffle_generator
+    from mace.calculators import mace_mp
+    import numpy as np
+
+Next, we need to set up the RAFFLE generator and the calculator to calculate the energies of the structures.
+In this example, we use the CHGNet calculator:
+
+.. code-block:: python
+
+    generator = raffle_generator()
+
+    calc = mace_mp(model="mace-mpa-0-medium.model")
+
+Note, choice of calculator is important.
+The calculator should be valid within and near the chemical environment of the structures being generated; in this case, Si and Ge bonding.
+If this is the case, it can accurately identify local minima and provide a good representation of the energy landscape.
+For this example, we use the [MACE-MPA-0 calculator](https://github.com/ACEsuit/mace-mp/releases/tag/mace_mpa_0), which, from preliminary testing, has been found to be suitable for Si and Ge bonding.
+To use the MACE-MPA-0 calculator, you will need to download the model file from the link provided and place it in the same directory as the script (and install the MACE package using `pip install mace-torch`, version 0.3.10 or later).
+The CHGNet calculator was not found to be suitable for Si and Ge interface bonding.
+
+Then, we need to create the host structure.
+Here, an abrupt Si|Ge interface is generated.
+This is the base structure that will be added to in order to generate the structures.
+A vacuum region of 5.54 Å is set up between the Si and Ge regions, in which the atoms will be placed by RAFFLE.
+
+.. code-block:: python
+
+    Si_bulk = build.bulk("Si", crystalstructure="diamond", a=5.43)
+    Si_cubic = build.make_supercell(Si_bulk, [[-1, 1, 1], [1, -1, 1], [1, 1, -1]])
+    Ge_bulk = build.bulk("Ge", crystalstructure="diamond", a=5.65)
+    Ge_cubic = build.make_supercell(Ge_bulk, [[-1, 1, 1], [1, -1, 1], [1, 1, -1]])
+
+    Si_supercell = build.make_supercell(Si_cubic, [[2, 0, 0], [0, 2, 0], [0, 0, 1]])
+    Ge_supercell = build.make_supercell(Ge_cubic, [[2, 0, 0], [0, 2, 0], [0, 0, 1]])
+
+    Si_surface = build.surface(Si_supercell, indices=(0, 0, 1), layers=2)
+    Ge_surface = build.surface(Ge_supercell, indices=(0, 0, 1), layers=2)
+
+    host = build.stack(Si_surface, Ge_surface, axis=2, distance= 5.43/2 + 5.65/2)
+    cell[2, 2] -= 3.8865
+    host.set_cell(cell, scale_atoms=False)
+
+
+The script then sets parameters for the generator and provides an initial database.
+Note, this database only contains prior information of Si-Si and Ge-Ge bonding, and no information about Si-Ge bonding.
+This is to demonstrate the ability of RAFFLE to learn from scratch.
+
+.. code-block:: python
+
+    Si_bulk.calc = calc
+    Ge_bulk.calc = calc
+    generator.distributions.set_element_energies(
+        {
+            'Si': Si_bulk.get_potential_energy() / len(Si_bulk),
+            'Ge': Ge_bulk.get_potential_energy() / len(Ge_bulk),
+        }
+    )
+
+    # set energy scale
+    generator.distributions.set_kBT(0.2)
+
+    # set the distribution function widths (2-body, 3-body, 4-body)
+    generator.distributions.set_width([0.04, np.pi/160.0, np.pi/160.0])
+
+    # set the initial database
+    initial_database = [Si_bulk, Ge_bulk]
+    generator.distributions.create(initial_database)
+
+Finally, the script generates structures using the generator.
+The generator is given the host structures.
+Finally, the generator is run for each host structure, providing a unique stoichiometry each time and using a custom method ratio.
+The 
+
+.. code-block:: python
+
+    generator.set_host(host)
+    generator.set_bounds([[0, 0, 0.34], [1, 1, 0.52]])
+    for iter in range(40):
+        # generate the structures
+        structures, exit_code = generator.generate(
+            num_structures = 5,
+            stoichiometry = { 'Si': 16, 'Ge': 16 },
+            seed = iter,
+            method_ratio = {"void": 0.1, "rand": 0.01, "walk": 0.25, "grow": 0.25, "min": 1.0},
+            verbose = 0,
+            calc = calc
+        )
+        generator.distributions.update(structures)
+
+    structures = generator.get_structures()
+    write('structures.traj', structures)

docs/source/tutorials/C-MgO_tutorial.rst

@@ -0,0 +1,86 @@
+.. aluminium:
+
+==================
+Aluminium tutorial
+==================
+
+This tutorial will guide you through the process of performing RAFFLE-based structure search for the bulk phases of aluminium.
+
+The tutorial is designed to show how a RAFFLE generator given no prior knowledge can learn bonding and identify known phases.
+This is not an expected use-case of RAFFLE due to its application to a bulk system, but still demonstrates the expected workflow and capabilities.
+
+The example script can be found in the following directory:
+
+.. code-block:: bash
+
+    raffle/example/python_pkg/Al_learn/learn.py
+
+We recommend reading through the file and running it to understand the process of learning and generating structures.
+However, we will provide a brief overview of the script here.
+
+First, we must import the required packages:
+
+.. code-block:: python
+
+    from ase import Atoms
+    from raffle.generator import raffle_generator
+    from chgnet.model import CHGNetCalculator
+    import numpy as np
+
+Next, we need to set up the RAFFLE generator and the calculator to calculate the energies of the structures.
+In this example, we use the CHGNet calculator:
+
+.. code-block:: python
+
+    generator = raffle_generator()
+
+    calc = CHGNetCalculator()
+
+Then, we need to create the host structure.
+Here, a set of host cells are generated to represent the multiple potential bulk phases of aluminium.
+These are then used to generate the structures.
+
+.. code-block:: python
+
+    crystal_structures = ['orthorhombic', 'hcp']
+    hosts = []
+    for crystal_structure in crystal_structures:
+        for a in np.linspace(3.1, 5.4, num=6):
+            atom = build.bulk(
+                    name = 'Al',
+                    crystalstructure = crystal_structure,
+                    a = a, b = a, c = a,
+            )
+            hosts.append(Atoms(
+                'Al',
+                positions = [(0, 0, 0)],
+                cell = atom.get_cell(),
+                pbc = True,
+                calculator = calc
+            ))
+
+The script then sets parameters for the generator and provides an initial database.
+Note, this database is effectively empty, as it only contains a single structure, which is an isolated aluminium atom.
+
+.. code-block:: python
+
+    initial_database = [Atoms('Al', positions=[(0, 0, 0)], cell=[8, 8, 8], pbc=True)]
+    initial_database[0].calc = calc
+    generator.distributions.create(initial_database)
+
+Finally, the script generates structures using the generator.
+The generator is given the host structures.
+Finally, the generator is run for each host structure, providing a unique stoichiometry each time and using a custom method ratio.
+
+.. code-block:: python
+
+    for host in hosts:
+        generator.set_host(host)
+        generator.generate(
+            num_structures = 5,
+            stoichiometry = { 'Al': num_atoms },
+            method_ratio = {"void": 0.5, "rand": 0.001, "walk": 0.5, "grow": 0.0, "min": 1.0},
+        )
+
+    structures = generator.get_structures()
+    write('structures.traj', structures)

docs/source/tutorials/Si-Ge_tutorial.rst

@@ -61,7 +61,6 @@ This is the base structure that will be added to in order to generate the struct
                 3.5607451090903233, 3.5607451090903233, 7.1214902182
             ], pbc=True
         )
-    )
 
     host.calc = calc
     generator.set_host(host)
@@ -121,12 +120,12 @@ We are now ready to generate structures using the database of structures.
 .. code-block:: python
 
     num_structures_old = 0
-    generator.generate(
+    structures, exit_code = generator.generate(
         num_structures = 1,
         stoichiometry = { 'C': 8 },
         method_ratio = {"void":0.0001, "min":1.0},
+        calc = calc
     )
-    structures = generator.get_structures(calc)
 
 We should now have a structure of diamond.
 This structure can be visualised using the ASE package.