allomorph
=========

.. py:module:: allomorph

.. autoapi-nested-parse::

   Nanoparticle structure generation toolkit.

   A package for generating monometallic to trimetallic nanoparticle structural
   datasets for machine learning applications.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/allomorph/__main__/index
   /autoapi/allomorph/cli/index
   /autoapi/allomorph/constants/index
   /autoapi/allomorph/init_struct/index


Attributes
----------

.. autoapisummary::

   allomorph.__version__
   allomorph.BNP_DIR
   allomorph.BNP_DISTRIB_LIST
   allomorph.DIAMETER_LIST
   allomorph.ELE_DICT
   allomorph.GOLDEN_RATIO
   allomorph.LMP_DATA_DIR
   allomorph.MNP_DIR
   allomorph.RANDOM_DISTRIB_NO
   allomorph.RATIO_LIST
   allomorph.SHAPE_LIST
   allomorph.TNP_DIR
   allomorph.TNP_DISTRIB_LIST
   allomorph.VACUUM_THICKNESS


Functions
---------

.. autoapisummary::

   allomorph.load_ele_dict_from_file
   allomorph.parse_ele_comb
   allomorph.validate_ele_dict
   allomorph.gen_bnp
   allomorph.write_bnp
   allomorph.gen_hard_core_shell
   allomorph.write_hard_core_shell
   allomorph.gen_mnp
   allomorph.write_mnp
   allomorph.gen_tnp
   allomorph.write_tnp


Package Contents
----------------

.. py:data:: __version__
   :value: '0.1.0'


.. py:data:: BNP_DIR
   :value: 'BNP'


.. py:data:: BNP_DISTRIB_LIST
   :value: ['L10', 'RAL', 'RCS']


.. py:data:: DIAMETER_LIST
   :value: [10, 15, 20]


.. py:data:: ELE_DICT

.. py:data:: GOLDEN_RATIO

.. py:data:: LMP_DATA_DIR
   :value: '.'


.. py:data:: MNP_DIR
   :value: 'MNP'


.. py:data:: RANDOM_DISTRIB_NO
   :value: 3


.. py:data:: RATIO_LIST
   :value: [20, 40]


.. py:data:: SHAPE_LIST
   :value: ['OT', 'SP', 'IC', 'CU', 'DH', 'TH', 'RD', 'TO', 'CO']


.. py:data:: TNP_DIR
   :value: 'TNP'


.. py:data:: TNP_DISTRIB_LIST
   :value: ['L10R', 'CS', 'CL10S', 'CRALS', 'RRAL', 'CSRAL', 'CSL10', 'CRSR', 'LL10']


.. py:data:: VACUUM_THICKNESS
   :value: 40.0


.. py:function:: load_ele_dict_from_file(path)

   Load an element dictionary from a JSON file.

   :param path: Path to a JSON file containing the element dictionary.

   :returns: Validated element dictionary.


.. py:function:: parse_ele_comb(ele_comb, ele_dict=None)

   Parse a concatenated element combination string into individual symbols.

   :param ele_comb: String like 'AuPtPd' or 'CuAgAu'.
   :param ele_dict: Optional element dictionary to use for matching. If None,
                    the built-in ELE_DICT is used.

   :returns: List of element symbols, e.g. ['Au', 'Pt', 'Pd'].

   :raises ValueError: If the string cannot be parsed.


.. py:function:: validate_ele_dict(ele_dict)

   Validate a user-supplied element dictionary.

   :param ele_dict: Dictionary mapping element symbols to property dicts.

   :returns: The validated dictionary.

   :raises ValueError: If required keys are missing or invalid.


.. py:function:: gen_bnp(obj, element1, element2, shape, ratio2, distrib, rseed, ele_dict=None)

   Generates a BNP alloy structure based on specified distribution type.


.. py:function:: write_bnp(element1, element2, diameter, shape, ratio2, distrib, replace=False, vis=False, ele_dict=None)

   Generates and writes a specific BNP alloy structure.


.. py:function:: gen_hard_core_shell(shell_atoms, core_atoms, del_cutoff)

   Generate a hard core-shell structure by combining shell and core atoms.
   Shell atoms overlapping with core atoms within del_cutoff are deleted.


.. py:function:: write_hard_core_shell(replace=False, vis=False, ele_dict=None)

   Orchestrates the generation of hard core-shell BNPs.
   Iterates through elements, sizes, and shapes.


.. py:function:: gen_mnp(shape, diameter, element, latConst, custom_shapes=None)

   Generates a monometallic nanoparticle structure based on specified shape.


.. py:function:: write_mnp(element, diameter, lat_const, shape, replace=False, vis=False, custom_shapes=None)

   Write a monometallic nanoparticle to LAMMPS data and XYZ files.


.. py:function:: gen_tnp(obj, element1, element2, element3, ele1Ratio, ele2Ratio, ele3Ratio, distrib1, distrib2, rseed=0, shape=None, ele_dict=None)

   Generates a TNP alloy structure based on specified distribution types.


.. py:function:: write_tnp(element1, element2, element3, diameter, shape, ele1Ratio, ele2Ratio, ele3Ratio, distrib1, distrib2, rep1=0, replace=False, vis=False, ele_dict=None)

   Generates and writes TNP alloy structures.