Add method to set default placement method ratio

Author: nedtaylor

docs/source/tutorials/parameters_tutorial.rst

@@ -62,6 +62,54 @@ As such, it is recommended that the user implement their own convergence check i
     The convergence criterion is also not enforced even when set, it is simply a check for the user to use.
 
 
+Placement methods
+-----------------
+
+RAFFLE uses a random sampling of five placement methods to place atoms in the host structure.
+These methods are:
+- ``rand``: Randomly place atoms in the host structure.
+- ``void``: Place atoms at the point furthest from the nearest atom in the host structure.
+- ``walk``: Start from a random position and walk to a local minimum in the RAFFLE-calculated probability.
+- ``grow``: Start from the previously placed atom and walk to a local minimum in the RAFFLE-calculated probability.
+- ``min``: Place atoms at the point of highest RAFFLE-calculated probability.
+
+The ratio of these methods can be set by the user.
+This can either be done on a per-generate method basis, or as a global setting.
+
+To set the default placement method ratios, the user can use the ``set_method_ratio_default`` method.
+
+.. code-block:: python
+
+    # Set default placement method ratios
+    generator.set_method_ratio_default(
+        method_ratio = {
+            'rand': 0.1,
+            'void': 0.1,
+            'walk': 0.25,
+            'grow': 0.25,
+            'min': 1.0
+        }
+    )
+
+These defaults will then be used for all generation methods where the user does not specify a method ratio.
+
+To set the placement method ratios for a specific generation method, the user can define the method ratio ``dict`` in the ``generate`` method.
+
+.. code-block:: python
+
+    # Set placement method ratios for a specific generation method
+    generator.generate(
+        method_ratio = {
+            'rand': 0.1,
+            'void': 0.1,
+            'walk': 0.25,
+            'grow': 0.25,
+            'min': 1.0
+        },
+        # Other generation parameters
+        ...
+    )
+
 
 Energy references
 -----------------

example/python_pkg/README.md

@@ -28,7 +28,7 @@ python_pkg/
 To run a RAFFLE example and analyse the results, the following order must be performed.
 1. Move to the desired `SYSTEM_learn/DRAFFLE` directory and create a directory to work in:
    ```bash
-   cd SYSTEM_learn
+   cd SYSTEM_learn/DRAFFLE
    mkdir DOutput
    cd DOutput
    ```
@@ -41,7 +41,7 @@ To run a RAFFLE example and analyse the results, the following order must be per
 3. Go to parent directory and open the notebook `pca.ipynb`, run all the cells.
 
 NOTE: for the `C_learn/DRSS/` example, the `pca.ipynb` notebook expects that the `C_learn/DRAFFLE/` example script and notebook have been fully run first.
-This is because it attempts to use the PCA fit to the RAFFLE results to transform its data.
+This is because it attempts to use the PCA of the RAFFLE results to transform its data.
 Doing so enables the two techniques to be properly compared.
 
 The `[un]rlxd_structures_seed0.traj` files are provided (as are the `energies_[un]rlxd+seed0.txt`) as the key outputs from the `learn.py` runs.
@@ -53,4 +53,4 @@ Whilst other output files are generated during the RAFFLE runs, these are option
 - Python 3.11 or higher
 - raffle package installed (`pip install .`)
 - `ase` for handling atomic structure data
-- `CHGNet`, `MACE-0`, `VASP`, or some other `ase`-compatible calculator
+- `CHGNet`, `MACE`, `VASP`, or some other `ase`-compatible calculator

src/fortran/lib/mod_generator.f90

@@ -73,13 +73,18 @@ module raffle__generator
           walk_step_size_coarse = 1._real32, &
           walk_step_size_fine = 0.1_real32
      !! Step size for the walk and grow methods.
+     real(real32), dimension(5) :: method_ratio_default = &
+          [1.0_real32, 0.1_real32, 0.5_real32, 0.5_real32, 1.0_real32]
+     !! Default ratio of each placement method.
      real(real32), dimension(5) :: method_ratio
-     !! Ratio of each placement method.
+     !! Last used ratio of each placement method.
      type(basis_type), dimension(:), allocatable :: structures
      !! Generated structures.
    contains
      procedure, pass(this) :: init_seed
      !! Procedure to set the seed for the random number generator.
+     procedure, pass(this) :: set_method_ratio_default
+     !! Procedure to set the ratio of each placement method.
 
      procedure, pass(this) :: set_host
      !! Procedure to set the host structure.
@@ -242,6 +247,23 @@ end subroutine init_seed
 !###############################################################################
 
 
+!###############################################################################
+  subroutine set_method_ratio_default(this, method_ratio)
+    !! Set the ratio of each placement method.
+    implicit none
+
+    ! Arguments
+    class(raffle_generator_type), intent(inout) :: this
+    !! Instance of the raffle generator.
+    real(real32), dimension(5), intent(in) :: method_ratio
+    !! Ratio of each placement method.
+
+    this%method_ratio_default = method_ratio
+
+  end subroutine set_method_ratio_default
+!###############################################################################
+
+
 !###############################################################################
   subroutine set_host(this, host)
     !! Set the host structure.
@@ -552,9 +574,7 @@ subroutine generate(this, num_structures, &
     !! Boolean to store the suppress_warnings value.
     type(basis_type) :: basis_template
     !! Basis of the structure to generate (i.e. allocated species and atoms).
-    real(real32), dimension(5) :: &
-         method_rand_limit = &
-              [1.0_real32, 0.1_real32, 0.5_real32, 0.5_real32, 1.0_real32]
+    real(real32), dimension(5) :: method_rand_limit
     !! Default ratio of each placement method.
 
     integer, dimension(:), allocatable :: seed_arr
@@ -579,19 +599,14 @@ subroutine generate(this, num_structures, &
 
 
     !---------------------------------------------------------------------------
-    ! Set the placement method selection limit numbers
+    ! Handle placement method optional argument
     !---------------------------------------------------------------------------
-    if(verbose_.gt.0) write(*,*) "Setting method ratios"
-    if(present(method_ratio)) method_rand_limit = method_ratio
+    if(present(method_ratio))then
+       method_rand_limit = method_ratio
+    else
+       method_rand_limit = this%method_ratio_default
+    end if
     this%method_ratio = method_rand_limit
-    ratio_norm = real(sum(method_rand_limit), real32)
-    method_rand_limit = method_rand_limit / ratio_norm
-    do i = 2, 5, 1
-       method_rand_limit(i) = method_rand_limit(i) + method_rand_limit(i-1)
-    end do
-    if(verbose_.gt.0) write(*,*) &
-         "Method random limits (void, rand, walk, grow, min): ", &
-         method_rand_limit
 
 
     !---------------------------------------------------------------------------
@@ -603,6 +618,21 @@ subroutine generate(this, num_structures, &
        end if
     end if
 
+
+    !---------------------------------------------------------------------------
+    ! Set the placement method selection limit numbers
+    !---------------------------------------------------------------------------
+    if(verbose_.gt.0) write(*,*) "Setting method ratio limits"
+    ratio_norm = real(sum(method_rand_limit), real32)
+    method_rand_limit = method_rand_limit / ratio_norm
+    do i = 2, 5, 1
+       method_rand_limit(i) = method_rand_limit(i) + method_rand_limit(i-1)
+    end do
+    if(verbose_.gt.0) write(*,*) &
+         "Method random limits (void, rand, walk, grow, min): ", &
+         method_rand_limit
+
+
     !---------------------------------------------------------------------------
     ! Set the random seed
     !---------------------------------------------------------------------------

src/raffle/raffle.py

@@ -1893,6 +1893,51 @@ def init_seed(self, put: int|list[int] = None, get: list[int] = None, num_thread
             _raffle.f90wrap_generator__init_seed__binding__rgt(this=self._handle, \
                 put=put, get=get, num_threads=num_threads)
 
+        def set_method_ratio_default(self, method_ratio : dict[str, float]):
+            """
+            Set the method of the five placement methods to be used.
+
+            This will be used as the default ratio if one is not provided as an input argument to the generate() method.
+
+            Parameters
+            ----------
+            method_ratio : dict[str, float]
+                The ratio of the walk method to the void method.
+            """            # check if method_ratio is provided, if so, use it only if method_ratio is not provided
+
+            # handle other names for the methods, such as random, growth, minimum, etc.
+            if "random" in method_ratio:
+                if "rand" in method_ratio:
+                    raise ValueError("Both random and rand are provided, use only one (random or rand)")
+                method_ratio["rand"] = method_ratio.pop("random")
+            if "growth" in method_ratio:
+                if "grow" in method_ratio:
+                    raise ValueError("Both growth and grow are provided, use only one (growth or grow)")
+                method_ratio["grow"] = method_ratio.pop("growth")
+            if "minimum" in method_ratio:
+                if "min" in method_ratio:
+                    raise ValueError("Both minimum and min are provided, use only one (minimum or min)")
+                method_ratio["min"] = method_ratio.pop("minimum")
+            if "global" in method_ratio:
+                if "min" in method_ratio:
+                    raise ValueError("Both global and min are provided, use only one (global or min)")
+                method_ratio["min"] = method_ratio.pop("global")
+
+            # exit if any other method is provided
+            for key in method_ratio.keys():
+                if key not in ["void", "rand", "walk", "grow", "min"]:
+                    raise ValueError(f"Unknown method {key} provided, use only void, rand (random), walk, grow (growth), or min (minimum/global)")
+
+            method_ratio_list = []
+            method_ratio_list.append(method_ratio.get("void", 0.0))
+            method_ratio_list.append(method_ratio.get("rand", 0.0)) # or method_ratio.get("random", 0.0))
+            method_ratio_list.append(method_ratio.get("walk", 0.0))
+            method_ratio_list.append(method_ratio.get("grow", 0.0)) # or method_ratio.get("growth", 0.0))
+            method_ratio_list.append(method_ratio.get("min", 0.0))  # or method_ratio.get("minimum", 0.0) or method_ratio.get("global", 0.0))
+
+            _raffle.f90wrap_generator__set_method_ratio_default__binding__rgt(this=self._handle, \
+                method_ratio=method_ratio_list)
+
         def set_max_attempts(self, max_attempts : int):
             """
             Set the walk-method maximum attempts parameter.
@@ -2081,7 +2126,7 @@ def reset_bounds(self):
         def generate(self,
                      num_structures : int,
                     stoichiometry,
-                    method_ratio: dict = {"void": 0.0, "rand": 0.0, "walk": 0.0, "grow": 0.0, "min": 0.0},
+                    method_ratio: dict[str, float] = {"void": 0.0, "rand": 0.0, "walk": 0.0, "grow": 0.0, "min": 0.0},
                     method_probab : dict = None,
                     seed : int = None,
                     settings_out_file : str = None,
@@ -2167,7 +2212,7 @@ def generate(self,
 
             # check if all values are 0.0, if so, set them to the default of all 1.0
             if all([val < 1E-6 for val in method_ratio_list]):
-                method_ratio_list = [1.0, 0.1, 0.5, 0.5, 1.0]
+                method_ratio_list = None
 
             # if stoichiometry is a dictionary, convert it to a stoichiometry_array
             if isinstance(stoichiometry, dict):
@@ -2536,7 +2581,7 @@ def walk_step_size_fine(self, walk_step_size_fine):
         @property
         def method_ratio(self):
             """
-            The ratio of methods to employ to generate a structure.
+            The last used ratio of methods to employ to generate a structure.
             """
             array_ndim, array_type, array_shape, array_handle = \
                 _raffle.f90wrap_raffle_generator_type__array__method_ratio(self._handle)
@@ -2553,6 +2598,26 @@ def method_ratio(self):
         def method_ratio(self, method_ratio):
             self.method_ratio[...] = method_ratio
 
+        @property
+        def method_ratio_default(self):
+            """
+            The default ratio of methods to employ to generate a structure.
+            """
+            array_ndim, array_type, array_shape, array_handle = \
+                _raffle.f90wrap_raffle_generator_type__array__method_ratio_default(self._handle)
+            if array_handle in self._arrays:
+                method_ratio = self._arrays[array_handle]
+            else:
+                method_ratio = f90wrap.runtime.get_array(f90wrap.runtime.sizeof_fortran_t,
+                                        self._handle,
+                                        _raffle.f90wrap_raffle_generator_type__array__method_ratio)
+                self._arrays[array_handle] = method_ratio
+            return method_ratio
+
+        @method_ratio_default.setter
+        def method_ratio_default(self, method_ratio):
+            self.method_ratio_default[...] = method_ratio
+
         def _init_array_structures(self):
             """
             Initialise the structures array.

src/wrapper/f90wrap_mod_generator.f90

@@ -606,6 +606,29 @@ subroutine f90wrap_raffle_generator_type__array__method_ratio( &
     dshape(1:1) = shape(this_ptr%p%method_ratio)
     dloc = loc(this_ptr%p%method_ratio)
 end subroutine f90wrap_raffle_generator_type__array__method_ratio
+
+subroutine f90wrap_raffle_generator_type__array__method_ratio_default( &
+     this, nd, dtype, dshape, dloc &
+)
+    use raffle__generator, only: raffle_generator_type
+    use, intrinsic :: iso_c_binding, only : c_int
+    implicit none
+    type raffle_generator_type_ptr_type
+        type(raffle_generator_type), pointer :: p => NULL()
+    end type raffle_generator_type_ptr_type
+    integer(c_int), intent(in) :: this(2)
+    type(raffle_generator_type_ptr_type) :: this_ptr
+    integer(c_int), intent(out) :: nd
+    integer(c_int), intent(out) :: dtype
+    integer(c_int), dimension(10), intent(out) :: dshape
+    integer*8, intent(out) :: dloc
+
+    nd = 1
+    dtype = 11
+    this_ptr = transfer(this, this_ptr)
+    dshape(1:1) = shape(this_ptr%p%method_ratio_default)
+    dloc = loc(this_ptr%p%method_ratio_default)
+end subroutine f90wrap_raffle_generator_type__array__method_ratio_default
 !###############################################################################
 
 
@@ -734,6 +757,28 @@ end subroutine f90wrap_generator__raffle_generator_type_finalise
 !###############################################################################
 
 
+!###############################################################################
+! set placement method ratio
+!###############################################################################
+subroutine f90wrap_generator__set_method_ratio_default__binding__rgt( &
+     this, method_ratio &
+)
+    use raffle__generator, only: raffle_generator_type
+    implicit none
+
+    type raffle_generator_type_ptr_type
+        type(raffle_generator_type), pointer :: p => NULL()
+    end type raffle_generator_type_ptr_type
+    type(raffle_generator_type_ptr_type) :: this_ptr
+    integer, intent(in), dimension(2) :: this
+    real(4), dimension(5), intent(in) :: method_ratio
+
+    this_ptr = transfer(this, this_ptr)
+    call this_ptr%p%set_method_ratio_default(method_ratio=method_ratio)
+end subroutine f90wrap_generator__set_method_ratio_default__binding__rgt
+!###############################################################################
+
+
 !###############################################################################
 ! initialise random seed
 !###############################################################################