Merge pull request #253 from simphony/feature-material-relation

Feature material relation

doc/source/api/cuds.rst

@@ -58,6 +58,8 @@ Pure Python implementation
    ~mesh.Cell
    ~material.Material
    ~materials.Materials
+   ~material_relations.material_relation.MaterialRelation
+
 
 .. rubric:: Functions
 
@@ -99,3 +101,17 @@ Pure Python implementation
 .. automodule:: simphony.cuds.materials
    :members:
    :undoc-members:
+
+.. automodule:: simphony.cuds.material_relations.material_relation
+   :members:
+   :undoc-members:
+
+Material relations
+------------------
+For each ``kind`` of material relation, there exists a
+subclass of :class:`~.MaterialRelation`.  See
+:ref:`list of material relations <material-relations-table>` for more details.
+
+
+.. include:: material_relations.rst
+

doc/source/api/material_relations.rst

@@ -0,0 +1,22 @@
+.. auto-generated by material_relations_generate.py script.
+.. rubric:: Material relations
+
+.. currentmodule:: simphony.cuds.material_relations
+
+.. autosummary::
+
+   ~lennard_jones.LennardJones
+   ~coulomb.Coulomb
+
+.. rubric:: Implementation
+
+
+.. automodule:: simphony.cuds.material_relations.lennard_jones
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: simphony.cuds.material_relations.coulomb
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/conf.py

@@ -110,7 +110,9 @@ def __call__(self, *args, **kwards):
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['cuba.rst']
+exclude_patterns = ['cuba.rst',
+                    'material_relations_table.rst',
+                    'api/material_relations.rst']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

doc/source/cuds_definition.rst

@@ -100,3 +100,19 @@ Materials
 In the SimPhoNy modeling framework, :class:`~.Materials` and :class:`~.Material`
 are used to describe materials and to define common material properties. Each
 low-level object (e.g. Point, Particle) can be of a certain material.
+
+MaterialRelation
+----------------
+
+.. figure:: ./images/material_relation.png
+
+   **Figure 4:** UML diagram of MaterialRelation.
+
+In the SimPhoNy modeling framework, :class:`~.MaterialRelation`
+are used to describe relationship between materials.  For each ``kind`` of
+material relation, there exists a subclasses of :class:`~.MaterialRelation`.
+See the following table for a list of each type of material relation:
+
+.. _material-relations-table:
+
+.. include:: material_relations_table.rst

doc/source/extending_simphony.rst

@@ -67,7 +67,7 @@ to see if the keyword already exists. Contact the developers at
 https://github.com/simphony/simphony-common if there are any questions.
 
 Once you have decided upon what CUBA needs to be added (or modified), edit
-`simphony/core/cuba.yml` to add the respective keyword. Ensure that all the
+``simphony/core/cuba.yml`` to add the respective keyword. Ensure that all the
 the required information is accurately provided.
 
 Developers should then use cuba_generate.py to generate four files which are
@@ -83,3 +83,31 @@ Finally, a pull request should be created and reviewed.
 Also note that the H5_FILE_VERSION version of :class:`~.H5CUDS` will usually
 have to be updated for each release of SimPhoNy when the list of CUBA keywords
 has been modified.
+
+
+Material Relationships
+----------------------
+
+:ref:`Material relations <material-relations-table>` are defined in
+``simphony/core/material_relation_definitions.yml``.
+This information is used to generate different documentation and code.
+
+Similar to extending CUBA, a script is used to generate multiple files
+based on the content of ``material_relation_definitions.yml``::
+
+   python simphony/scripts/material_relations_generate.py create_enum simphony/core/material_relation_definitions.yml simphony/core/cuds_material_relation.py
+   python simphony/scripts/material_relations_generate.py python simphony/core/material_relation_definitions.yml simphony/cuds/material_relations/
+   python simphony/scripts/material_relations_generate.py test simphony/core/material_relation_definitions.yml simphony/cuds/material_relations/tests/
+   python simphony/scripts/material_relations_generate.py material_relations_definitions_py simphony/core/material_relation_definitions.yml simphony/core/material_relation_definitions.py
+   python simphony/scripts/material_relations_generate.py table_rst simphony/core/material_relation_definitions.yml doc/source/material_relations_table.rst
+   python simphony/scripts/material_relations_generate.py create_api simphony/core/material_relation_definitions.yml doc/source/api/material_relations.rst
+
+A pull request should be created https://github.com/simphony/simphony-common
+and reviewed by the SimPhoNy developers.
+
+Note that the scripts create multiple files in ``simphony/material_relations/``.
+Take care to ensure that any new files are included in your PR.  Also note that
+the scripts will **only** create new files or update existing files in
+``simphony/material_relations/``. So if you change the name of a material
+relation, the still existing (but now outdated) file that has the old name
+should be removed.

doc/source/material_relations_table.rst

@@ -0,0 +1,8 @@
+.. auto-generated by material_relations_generate.py script.
+
+=============  =======================  ================================================================================================================================  ==============================  =======================================================================
+Key            Class                    Description                                                                                                                       Allowed lengths of materials    Supported parameters
+=============  =======================  ================================================================================================================================  ==============================  =======================================================================
+LENNARD_JONES  :class:`~.LennardJones`  Approximated potential energy of interaction between a pair of neutral atoms or molecules based on their distance of separation.  [1, 2]                          CUBA.CUTOFF_DISTANCE, CUBA.ENERGY_WELL_DEPTH, CUBA.VAN_DER_WAALS_RADIUS
+COULOMB        :class:`~.Coulomb`       Effective potential energy of the interaction between a pair of point charges.                                                    [1, 2]                          CUBA.CUTOFF_DISTANCE, CUBA.DIELECTRIC_CONSTANT
+=============  =======================  ================================================================================================================================  ==============================  =======================================================================

doc/source/uml/material_relation.txt

@@ -0,0 +1,11 @@
+@startuml
+class MaterialRelation {
+   kind: CUDSMaterialRelation
+   name: str
+   materials: uuid.UUID[]
+   parameters: DataContainer
+   description: str
+   supported_parameters: CUBA[]
+   allowed_number_materials: int[]
+}
+@enduml

simphony/core/cuba.py

@@ -72,3 +72,7 @@ class CUBA(IntEnum):
     ROLLING_FRICTION = 66
     VOLUME_FRACTION = 67
     MATERIAL = 68
+    CUTOFF_DISTANCE = 69
+    ENERGY_WELL_DEPTH = 70
+    VAN_DER_WAALS_RADIUS = 71
+    DIELECTRIC_CONSTANT = 72

simphony/core/cuba.yml

@@ -480,4 +480,33 @@
   name: Material
   number: 68
   shape: [1]
-  type: uuid
+  type: uuid
+- description: Distance where force is no longer taken into account.
+  domain: []
+  key: CUTOFF_DISTANCE
+  name: CutoffDistance
+  number: 69
+  shape: [1]
+  type: double
+- description: Measurement of how strongly the two particles attract each other.
+  domain: []
+  key: ENERGY_WELL_DEPTH
+  name: EnergyWellDepth
+  number: 70
+  shape: [1]
+  type: double
+- description: Distance at which the intermolecular potential between the two particles is zero.
+  domain: []
+  key: VAN_DER_WAALS_RADIUS
+  name: VanDerWaalsRadius
+  number: 71
+  shape: [1]
+  type: double
+- description: Ratio of the permittivity of a substance to the permittivity of free space or vacuum
+  domain: []
+  key: DIELECTRIC_CONSTANT
+  name: DielectricConstant
+  number: 72
+  shape: [1]
+  type: double
+

simphony/core/cuds_material_relation.py

@@ -0,0 +1,9 @@
+# auto-generated by the material_relations_generate.py script.
+from enum import IntEnum, unique
+
+
+@unique
+class CUDSMaterialRelation(IntEnum):
+
+    LENNARD_JONES = 1
+    COULOMB = 2

simphony/core/keywords.py

@@ -563,4 +563,36 @@
         number=68,
         shape=[1],
         dtype=uuid.UUID),
+    'CUTOFF_DISTANCE': Keyword(
+        name='CutoffDistance',
+        description='Distance where force is no longer taken into account.',  # noqa
+        domain=[],
+        key='CUTOFF_DISTANCE',
+        number=69,
+        shape=[1],
+        dtype=numpy.float64),
+    'ENERGY_WELL_DEPTH': Keyword(
+        name='EnergyWellDepth',
+        description='Measurement of how strongly the two particles attract each other.',  # noqa
+        domain=[],
+        key='ENERGY_WELL_DEPTH',
+        number=70,
+        shape=[1],
+        dtype=numpy.float64),
+    'VAN_DER_WAALS_RADIUS': Keyword(
+        name='VanDerWaalsRadius',
+        description='Distance at which the intermolecular potential between the two particles is zero.',  # noqa
+        domain=[],
+        key='VAN_DER_WAALS_RADIUS',
+        number=71,
+        shape=[1],
+        dtype=numpy.float64),
+    'DIELECTRIC_CONSTANT': Keyword(
+        name='DielectricConstant',
+        description='Ratio of the permittivity of a substance to the permittivity of free space or vacuum',  # noqa
+        domain=[],
+        key='DIELECTRIC_CONSTANT',
+        number=72,
+        shape=[1],
+        dtype=numpy.float64),
 }

simphony/core/material_relation_definitions.py

@@ -0,0 +1,42 @@
+# code auto-generated by the material_relations_generate.py script.
+from collections import namedtuple
+
+from simphony.core.cuba import CUBA
+from simphony.core.cuds_material_relation import CUDSMaterialRelation
+
+
+ATTRIBUTES = [
+    "number", "class_name", "allowed_number_materials",
+    "doc_description", "supported_parameters"]
+Material_Relation_Definition = namedtuple("Material_Relation_Definition",
+                                          ATTRIBUTES)
+
+Parameter = namedtuple("Parameter", ["cuba_key", "default_value"])
+
+
+MATERIAL_RELATION_DEFINITIONS = {
+    CUDSMaterialRelation.LENNARD_JONES: Material_Relation_Definition(
+        class_name='LennardJones',
+        number=1,
+        allowed_number_materials=[1, 2],
+        doc_description='Approximated potential energy of interaction between a pair of neutral atoms or molecules based on their distance of separation.',  # noqa
+        supported_parameters=[
+             Parameter(cuba_key=CUBA.CUTOFF_DISTANCE,
+                       default_value=1.0),
+             Parameter(cuba_key=CUBA.ENERGY_WELL_DEPTH,
+                       default_value=1.0),
+             Parameter(cuba_key=CUBA.VAN_DER_WAALS_RADIUS,
+                       default_value=1.0), ]
+     ),
+    CUDSMaterialRelation.COULOMB: Material_Relation_Definition(
+        class_name='Coulomb',
+        number=2,
+        allowed_number_materials=[1, 2],
+        doc_description='Effective potential energy of the interaction between a pair of point charges.',  # noqa
+        supported_parameters=[
+             Parameter(cuba_key=CUBA.CUTOFF_DISTANCE,
+                       default_value=1.0),
+             Parameter(cuba_key=CUBA.DIELECTRIC_CONSTANT,
+                       default_value=1.0), ]
+     ),
+}

simphony/core/material_relation_definitions.yml

@@ -0,0 +1,22 @@
+- key: LENNARD_JONES
+  number: 1
+  class_name : LennardJones
+  allowed_number_materials: [1, 2]
+  doc_description: Approximated potential energy of interaction between a pair of neutral atoms or molecules based on their distance of separation.
+  supported_parameters:
+  - cuba: CUBA.CUTOFF_DISTANCE
+    default: 1.0
+  - cuba: CUBA.ENERGY_WELL_DEPTH
+    default: 1.0
+  - cuba: CUBA.VAN_DER_WAALS_RADIUS
+    default: 1.0
+- key: COULOMB
+  number: 2
+  class_name : Coulomb
+  allowed_number_materials: [1, 2]
+  doc_description: Effective potential energy of the interaction between a pair of point charges.
+  supported_parameters:
+  - cuba: CUBA.CUTOFF_DISTANCE
+    default: 1.0
+  - cuba: CUBA.DIELECTRIC_CONSTANT
+    default: 1.0

simphony/cuds/material_relations/coulomb.py

@@ -0,0 +1,57 @@
+# code auto-generated by material_relations_generate.py
+from simphony.cuds.material_relations.material_relation import (
+    MaterialRelation)
+from simphony.core.cuba import CUBA
+from simphony.core.cuds_material_relation import CUDSMaterialRelation
+from simphony.core.data_container import DataContainer
+
+
+class Coulomb(MaterialRelation):
+
+    """ A Coulomb material-relation
+
+    Effective potential energy of the interaction between a pair of point charges.
+
+    Attributes
+    ----------
+    cutoff_distance : <type 'numpy.float64'>
+        Distance where force is no longer taken into account.
+    dielectric_constant : <type 'numpy.float64'>
+        Ratio of the permittivity of a substance to the permittivity of free space or vacuum
+
+    """  # noqa
+
+    def __init__(
+        self,
+        name,
+        materials,
+        description="",
+        cutoff_distance=1.0,
+        dielectric_constant=1.0
+    ):
+        super(Coulomb, self).__init__(
+            name=name,
+            description=description,
+            kind=CUDSMaterialRelation.COULOMB,
+            materials=materials,
+            parameters=DataContainer({
+                CUBA.CUTOFF_DISTANCE: cutoff_distance,
+                CUBA.DIELECTRIC_CONSTANT: dielectric_constant,
+            })
+        )
+
+    @property
+    def cutoff_distance(self):
+        return self._parameters[CUBA.CUTOFF_DISTANCE]
+
+    @cutoff_distance.setter
+    def cutoff_distance(self, value):
+        self._parameters[CUBA.CUTOFF_DISTANCE] = value
+
+    @property
+    def dielectric_constant(self):
+        return self._parameters[CUBA.DIELECTRIC_CONSTANT]
+
+    @dielectric_constant.setter
+    def dielectric_constant(self, value):
+        self._parameters[CUBA.DIELECTRIC_CONSTANT] = value