Package ffx.crystal

Class Crystal

  • Direct Known Subclasses:
    NCSCrystal, ReplicatesCrystal

    public class Crystal
    extends Object
    The Crystal class encapsulates the lattice parameters and space group that describe the geometry and symmetry of a crystal. Methods are available to apply the minimum image convention and space group symmetry operators.
    Since:
    1.0
    Author:
    Michael J. Schnieders
    See Also:
    ReplicatesCrystal
    • Field Summary

      Fields 
      Modifier and Type Field Description
      double a
      Length of the cell edge in the direction of the a basis vector.
      double[][] A
      Matrix to convert from Cartesian to fractional coordinates.
      double A00
      Entry in the A matrix.
      double A01
      Entry in the A matrix.
      double A02
      Entry in the A matrix.
      double A10
      Entry in the A matrix.
      double A11
      Entry in the A matrix.
      double A12
      Entry in the A matrix.
      double A20
      Entry in the A matrix.
      double A21
      Entry in the A matrix.
      double A22
      Entry in the A matrix.
      double[][] Ai
      Matrix to convert from fractional to Cartesian coordinates.
      double Ai00
      Entry in the Ai matrix.
      double Ai01
      Entry in the Ai matrix.
      double Ai02
      Entry in the Ai matrix.
      double Ai10
      Entry in the Ai matrix.
      double Ai11
      Entry in the Ai matrix.
      double Ai12
      Entry in the Ai matrix.
      double Ai20
      Entry in the Ai matrix.
      double Ai21
      Entry in the Ai matrix.
      double Ai22
      Entry in the Ai matrix.
      double alpha
      The interaxial lattice angle between b and c.
      double b
      Length of the cell edge in the direction of the b basis vector.
      double beta
      The interaxial lattice angle between a and c.
      double c
      Length of the cell edge in the direction of the c basis vector.
      double dVdA
      Change in the volume with respect to a.
      double dVdAlpha
      Change in the volume with respect to alpha (in Radians).
      double dVdB
      Change in the volume with respect to b.
      double dVdBeta
      Change in the volume with respect to beta (in Radians).
      double dVdC
      Change in the volume with respect to c.
      double dVdGamma
      Change in the volume with respect to gamma (in Radians).
      double[][] G
      The direct space metric matrix.
      double gamma
      The interaxial lattice angle between a and b.
      double interfacialRadiusA
      Interfacial radius in the direction of the A-axis.
      double interfacialRadiusB
      Interfacial radius in the direction of the B-axis.
      double interfacialRadiusC
      Interfacial radius in the direction of the C-axis.
      int[] scaleB
      Anisotropic bulk solvent B-factor scaling (0 or 1 for each component).
      int scaleN
      Number of bulk solvent B-factor components.
      SpaceGroup spaceGroup
      The space group of the crystal.
      double volume
      The crystal unit cell volume.
    • Constructor Summary

      Constructors 
      Constructor Description
      Crystal​(double a, double b, double c, double alpha, double beta, double gamma, int sgNumber)
      The Crystal class encapsulates the lattice parameters and space group.
      Crystal​(double a, double b, double c, double alpha, double beta, double gamma, String sg)
      The Crystal class encapsulates the lattice parameters and space group.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean aperiodic()
      aperiodic
      void applySymOp​(double[] xyz, double[] mate, SymOp symOp)
      Apply a fractional symmetry operator to one set of cartesian coordinates.
      void applySymOp​(int n, double[] x, double[] y, double[] z, double[] mateX, double[] mateY, double[] mateZ, SymOp symOp)
      Apply a fractional symmetry operator to an array of Cartesian coordinates.
      void applySymRot​(double[] xyz, double[] mate, SymOp symOp)
      Apply a fractional symmetry operator to one set of cartesian coordinates.
      void applyTransSymRot​(int n, double[] x, double[] y, double[] z, double[] mateX, double[] mateY, double[] mateZ, SymOp symOp, double[][] rotmat)
      Apply the transpose of a symmetry rotation to an array of Cartesian coordinates.
      void averageTensor​(double[][] m, double[][] r)
      averageTensor
      void averageTensor​(double[] v, double[][] r)
      averageTensor
      boolean changeUnitCellParameters​(double a, double b, double c, double alpha, double beta, double gamma)
      This method should be called to update the unit cell parameters of a crystal.
      boolean changeUnitCellParametersAndVolume​(double a, double b, double c, double alpha, double beta, double gamma, double targetAUVolume)
      This method should be called to update the unit cell parameters of a crystal.
      static Crystal checkProperties​(org.apache.commons.configuration2.CompositeConfiguration properties)
      checkProperties
      boolean equals​(Object o)
      Two crystals are equal only if all unit cell parameters are exactly the same.
      double[] getCellParametersFromVectors​(double[][] cellVectors)  
      boolean getCheckRestrictions()  
      double getDensity​(double mass)
      Compute the density of the system.
      int getNumSymOps()
      Return the number of symmetry operators for this crystal.
      double[] getRandomCartTranslation()
      Create a random Cartesian translation vector.
      double getSpecialPositionCutoff()
      Getter for the field specialPositionCutoff.
      double getSpecialPositionCutoff2()
      Getter for the field specialPositionCutoff2.
      void getTransformationOperator​(SymOp symOp, double[][] rotmat)
      Compute the total transformation operator R = ToCart * Rot * ToFrac.
      Crystal getUnitCell()
      The ReplicatesCrystal over-rides this method to return the unit cell rather than the ReplicateCell.
      int hashCode()
      double image​(double[] xyz)
      Apply the minimum image convention.
      double image​(double dx, double dy, double dz)
      Apply the minimum image convention.
      double invressq​(HKL hkl)
      invressq
      double minDistOverSymOps​(double[] xyzA, double[] xyzB)
      Minimum distance between two coordinates over all symmetry operators.
      boolean perturbCellVectors​(double[][] dStrain)
      Strain the unit cell vectors.
      boolean randomParameters​(double dens, double mass)  
      double res​(HKL hkl)
      res
      void setAperiodic​(boolean aperiodic)
      Is this a finite system without periodic boundary conditions.
      boolean setCellVectors​(double[][] cellVectors)
      Set the unit cell vectors.
      boolean setCellVectorsAndVolume​(double[][] cellVectors, double targetAUVolume)
      Set the unit cell vectors.
      void setCheckRestrictions​(boolean checkRestrictions)  
      void setDensity​(double dens, double mass)  
      void setSpecialPositionCutoff​(double cutoff)
      Setter for the field specialPositionCutoff.
      void toCartesianCoordinates​(double[] xf, double[] x)
      toCartesianCoordinates
      void toCartesianCoordinates​(int n, double[] frac, double[] cart)
      toCartesianCoordinates
      void toCartesianCoordinates​(int n, double[] xf, double[] yf, double[] zf, double[] x, double[] y, double[] z)
      toCartesianCoordinates
      String toCRYST1()
      Return a CRYST1 record useful for writing a PDB file.
      void toFractionalCoordinates​(double[] x, double[] xf)
      toFractionalCoordinates
      void toFractionalCoordinates​(int n, double[] cart, double[] frac)
      toFractionalCoordinates
      void toFractionalCoordinates​(int n, double[] x, double[] y, double[] z, double[] xf, double[] yf, double[] zf)
      toFractionalCoordinates
      void toPrimaryCell​(double[] in, double[] out)
      toPrimaryCell
      String toShortString()
      A String containing the unit cell parameters.
      String toString()
      void updateCrystal()
      Update all Crystal variables that are a function of unit cell parameters.
    • Field Detail

      • alpha

        @FFXKeyword(name="alpha",
                    keywordGroup=UnitCellAndSpaceGroup,
                    defaultValue="90.0",
                    description="Sets the value of the \u03b1-angle of a crystal unit cell, i.e., the angle between the b-axis and c-axis of a unit cell, or, equivalently, the angle between the Y-axis and Z-axis of a periodic box.")
        public double alpha
        The interaxial lattice angle between b and c.
      • beta

        @FFXKeyword(name="beta",
                    keywordGroup=UnitCellAndSpaceGroup,
                    defaultValue="Alpha",
                    description="Sets the value of the \u03b2-angle of a crystal unit cell, i.e., the angle between the a-axis and c-axis of a unit cell, or, equivalently, the angle between the X-axis and Z-axis of a periodic box.")
        public double beta
        The interaxial lattice angle between a and c.
      • gamma

        @FFXKeyword(name="gamma",
                    keywordGroup=UnitCellAndSpaceGroup,
                    defaultValue="Alpha",
                    description="Sets the value of the \u03b3-angle of a crystal unit cell, i.e., the angle between the a-axis and b-axis of a unit cell, or, equivalently, the angle between the X-axis and Y-axis of a periodic box.")
        public double gamma
        The interaxial lattice angle between a and b.
      • Ai

        public final double[][] Ai
        Matrix to convert from fractional to Cartesian coordinates.
        a-axis vector is the first row of A^(-1).
        b-axis vector is the second row of A^(-1).
        c-axis vector is the third row of A^(-1).
      • G

        public final double[][] G
        The direct space metric matrix.
      • volume

        public double volume
        The crystal unit cell volume.
      • A

        public double[][] A
        Matrix to convert from Cartesian to fractional coordinates.
      • A00

        public double A00
        Entry in the A matrix.
      • A01

        public double A01
        Entry in the A matrix.
      • A02

        public double A02
        Entry in the A matrix.
      • A10

        public double A10
        Entry in the A matrix.
      • A11

        public double A11
        Entry in the A matrix.
      • A12

        public double A12
        Entry in the A matrix.
      • A20

        public double A20
        Entry in the A matrix.
      • A21

        public double A21
        Entry in the A matrix.
      • A22

        public double A22
        Entry in the A matrix.
      • interfacialRadiusA

        public double interfacialRadiusA
        Interfacial radius in the direction of the A-axis.
      • interfacialRadiusB

        public double interfacialRadiusB
        Interfacial radius in the direction of the B-axis.
      • interfacialRadiusC

        public double interfacialRadiusC
        Interfacial radius in the direction of the C-axis.
      • scaleB

        public int[] scaleB
        Anisotropic bulk solvent B-factor scaling (0 or 1 for each component).
      • scaleN

        public int scaleN
        Number of bulk solvent B-factor components.
      • Ai00

        public double Ai00
        Entry in the Ai matrix.
      • Ai01

        public double Ai01
        Entry in the Ai matrix.
      • Ai02

        public double Ai02
        Entry in the Ai matrix.
      • Ai10

        public double Ai10
        Entry in the Ai matrix.
      • Ai11

        public double Ai11
        Entry in the Ai matrix.
      • Ai12

        public double Ai12
        Entry in the Ai matrix.
      • Ai20

        public double Ai20
        Entry in the Ai matrix.
      • Ai21

        public double Ai21
        Entry in the Ai matrix.
      • Ai22

        public double Ai22
        Entry in the Ai matrix.
      • dVdA

        public double dVdA
        Change in the volume with respect to a.
      • dVdB

        public double dVdB
        Change in the volume with respect to b.
      • dVdC

        public double dVdC
        Change in the volume with respect to c.
      • dVdAlpha

        public double dVdAlpha
        Change in the volume with respect to alpha (in Radians). This is set to zero if alpha is fixed.
      • dVdBeta

        public double dVdBeta
        Change in the volume with respect to beta (in Radians). This is set to zero if beta is fixed.
      • dVdGamma

        public double dVdGamma
        Change in the volume with respect to gamma (in Radians). This is set to zero if gamma is fixed.
    • Constructor Detail

      • Crystal

        public Crystal​(double a,
                       double b,
                       double c,
                       double alpha,
                       double beta,
                       double gamma,
                       int sgNumber)
        The Crystal class encapsulates the lattice parameters and space group. Methods are available to apply the minimum image convention and to apply space group operators.
        Parameters:
        a - The a-axis length.
        b - The b-axis length.
        c - The c-axis length.
        alpha - The alpha angle.
        beta - The beta angle.
        gamma - The gamma angle.
        sgNumber - The space group number.
      • Crystal

        public Crystal​(double a,
                       double b,
                       double c,
                       double alpha,
                       double beta,
                       double gamma,
                       String sg)
        The Crystal class encapsulates the lattice parameters and space group. Methods are available to apply the minimum image convention and to apply space group operators.
        Parameters:
        a - The a-axis length.
        b - The b-axis length.
        c - The c-axis length.
        alpha - The alpha angle.
        beta - The beta angle.
        gamma - The gamma angle.
        sg - The space group symbol.
    • Method Detail

      • checkProperties

        public static Crystal checkProperties​(org.apache.commons.configuration2.CompositeConfiguration properties)
        checkProperties
        Parameters:
        properties - a CompositeConfiguration object.
        Returns:
        a Crystal object.
      • invressq

        public double invressq​(HKL hkl)
        invressq
        Parameters:
        hkl - a HKL object.
        Returns:
        a double.
      • res

        public double res​(HKL hkl)
        res
        Parameters:
        hkl - a HKL object.
        Returns:
        a double.
      • aperiodic

        public boolean aperiodic()
        aperiodic
        Returns:
        a boolean.
      • applySymOp

        public void applySymOp​(int n,
                               double[] x,
                               double[] y,
                               double[] z,
                               double[] mateX,
                               double[] mateY,
                               double[] mateZ,
                               SymOp symOp)
        Apply a fractional symmetry operator to an array of Cartesian coordinates. If the arrays x, y or z are null or not of length n, the method returns immediately. If mateX, mateY or mateZ are null or not of length n, new arrays are allocated.
        Parameters:
        n - Number of atoms.
        x - Input fractional x-coordinates.
        y - Input fractional y-coordinates.
        z - Input fractional z-coordinates.
        mateX - Output fractional x-coordinates.
        mateY - Output fractional y-coordinates.
        mateZ - Output fractional z-coordinates.
        symOp - The fractional symmetry operator.
      • applySymOp

        public void applySymOp​(double[] xyz,
                               double[] mate,
                               SymOp symOp)
        Apply a fractional symmetry operator to one set of cartesian coordinates.
        Parameters:
        xyz - Input cartesian coordinates.
        mate - Symmetry mate cartesian coordinates.
        symOp - The fractional symmetry operator.
      • applySymRot

        public void applySymRot​(double[] xyz,
                                double[] mate,
                                SymOp symOp)
        Apply a fractional symmetry operator to one set of cartesian coordinates.
        Parameters:
        xyz - Input cartesian coordinates.
        mate - Symmetry mate cartesian coordinates.
        symOp - The fractional symmetry operator.
      • applyTransSymRot

        public void applyTransSymRot​(int n,
                                     double[] x,
                                     double[] y,
                                     double[] z,
                                     double[] mateX,
                                     double[] mateY,
                                     double[] mateZ,
                                     SymOp symOp,
                                     double[][] rotmat)
        Apply the transpose of a symmetry rotation to an array of Cartesian coordinates. If the arrays x, y or z are null or not of length n, the method returns immediately. If mateX, mateY or mateZ are null or not of length n, new arrays are allocated.
        Parameters:
        n - Number of atoms.
        x - Input x-coordinates.
        y - Input y-coordinates.
        z - Input z-coordinates.
        mateX - Output x-coordinates.
        mateY - Output y-coordinates.
        mateZ - Output z-coordinates.
        symOp - The symmetry operator.
        rotmat - an array of double.
      • averageTensor

        public void averageTensor​(double[][] m,
                                  double[][] r)
        averageTensor
        Parameters:
        m - an array of double.
        r - an array of double.
      • averageTensor

        public void averageTensor​(double[] v,
                                  double[][] r)
        averageTensor
        Parameters:
        v - an array of double.
        r - an array of double.
      • changeUnitCellParameters

        public boolean changeUnitCellParameters​(double a,
                                                double b,
                                                double c,
                                                double alpha,
                                                double beta,
                                                double gamma)
        This method should be called to update the unit cell parameters of a crystal. The proposed parameters will only be accepted if symmetry restrictions are satisfied. If so, all Crystal variables that depend on the unit cell parameters will be updated.
        Parameters:
        a - length of the a-axis.
        b - length of the b-axis.
        c - length of the c-axis.
        alpha - Angle between b-axis and c-axis.
        beta - Angle between a-axis and c-axis.
        gamma - Angle between a-axis and b-axis.
        Returns:
        The method return true if the parameters are accepted, false otherwise.
      • changeUnitCellParametersAndVolume

        public boolean changeUnitCellParametersAndVolume​(double a,
                                                         double b,
                                                         double c,
                                                         double alpha,
                                                         double beta,
                                                         double gamma,
                                                         double targetAUVolume)
        This method should be called to update the unit cell parameters of a crystal. The proposed parameters will only be accepted if symmetry restrictions are satisfied. If so, all Crystal variables that depend on the unit cell parameters will be updated.

        If the new parameters are accepted, the target asymmetric unit volume is achieved by uniformly scaling all lattice lengths.

        Parameters:
        a - length of the a-axis.
        b - length of the b-axis.
        c - length of the c-axis.
        alpha - Angle between b-axis and c-axis.
        beta - Angle between a-axis and c-axis.
        gamma - Angle between a-axis and b-axis.
        targetAUVolume - Target asymmetric unit volume.
        Returns:
        The method return true if the parameters are accepted, false otherwise.
      • equals

        public boolean equals​(Object o)
        Two crystals are equal only if all unit cell parameters are exactly the same.
        Overrides:
        equals in class Object
        Parameters:
        o - the Crystal to compare to.
        Returns:
        true if all unit cell parameters are exactly the same.
      • getCheckRestrictions

        public boolean getCheckRestrictions()
      • setCheckRestrictions

        public void setCheckRestrictions​(boolean checkRestrictions)
      • getDensity

        public double getDensity​(double mass)
        Compute the density of the system.
        Parameters:
        mass - The total mass of the asymmetric unit.
        Returns:
        The density (g/cc)
      • getNumSymOps

        public int getNumSymOps()
        Return the number of symmetry operators for this crystal.
        Returns:
        The number of symmetry operators.
      • getRandomCartTranslation

        public double[] getRandomCartTranslation()
        Create a random Cartesian translation vector.

        First, a random fractional translation is created. Second, the random fractional operator is converted to Cartesian coordinates.

        Returns:
        A random Cartesian translation vector.
      • getSpecialPositionCutoff

        public double getSpecialPositionCutoff()
        Getter for the field specialPositionCutoff.
        Returns:
        a double.
      • getSpecialPositionCutoff2

        public double getSpecialPositionCutoff2()
        Getter for the field specialPositionCutoff2.
        Returns:
        a double.
      • setSpecialPositionCutoff

        public void setSpecialPositionCutoff​(double cutoff)
        Setter for the field specialPositionCutoff.
        Parameters:
        cutoff - a double.
      • getTransformationOperator

        public void getTransformationOperator​(SymOp symOp,
                                              double[][] rotmat)
        Compute the total transformation operator R = ToCart * Rot * ToFrac.
        Parameters:
        symOp - Symmetry operator to apply.
        rotmat - Resulting transformation operator R.
      • getUnitCell

        public Crystal getUnitCell()
        The ReplicatesCrystal over-rides this method to return the unit cell rather than the ReplicateCell.
        Returns:
        The unit cell Crystal instance.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • image

        public double image​(double[] xyz)
        Apply the minimum image convention.
        Parameters:
        xyz - input distances that are over-written.
        Returns:
        the output distance squared.
      • image

        public double image​(double dx,
                            double dy,
                            double dz)
        Apply the minimum image convention.
        Parameters:
        dx - x-distance
        dy - y-distance
        dz - z-distance
        Returns:
        the output distance squared.
      • minDistOverSymOps

        public double minDistOverSymOps​(double[] xyzA,
                                        double[] xyzB)
        Minimum distance between two coordinates over all symmetry operators.
        Parameters:
        xyzA - Coordinate A
        xyzB - Coordinate B
        Returns:
        Minimum distance in crystal
      • perturbCellVectors

        public boolean perturbCellVectors​(double[][] dStrain)
        Strain the unit cell vectors.
        Parameters:
        dStrain - a 3x3 matrix of unitless Strain percentages.
        Returns:
        True if the perturbation of cell vectors succeeds.
      • randomParameters

        public boolean randomParameters​(double dens,
                                        double mass)
      • setAperiodic

        public void setAperiodic​(boolean aperiodic)
        Is this a finite system without periodic boundary conditions.
        Parameters:
        aperiodic - a boolean.
      • getCellParametersFromVectors

        public double[] getCellParametersFromVectors​(double[][] cellVectors)
      • setCellVectors

        public boolean setCellVectors​(double[][] cellVectors)
        Set the unit cell vectors.
        Parameters:
        cellVectors - 3x3 matrix of cell vectors.
        Returns:
        True if the perturbation of cell vectors succeeds.
      • setCellVectorsAndVolume

        public boolean setCellVectorsAndVolume​(double[][] cellVectors,
                                               double targetAUVolume)
        Set the unit cell vectors. Scale lattice lengths if necessary to hit the target volume.
        Parameters:
        cellVectors - 3x3 matrix of cell vectors.
        targetAUVolume - the target volume for the new cell Vectors.
        Returns:
        True if the perturbation of cell vectors succeeds.
      • setDensity

        public void setDensity​(double dens,
                               double mass)
      • toCRYST1

        public String toCRYST1()
        Return a CRYST1 record useful for writing a PDB file.
        Returns:
        The CRYST1 record.
      • toCartesianCoordinates

        public void toCartesianCoordinates​(int n,
                                           double[] xf,
                                           double[] yf,
                                           double[] zf,
                                           double[] x,
                                           double[] y,
                                           double[] z)
        toCartesianCoordinates
        Parameters:
        n - a int.
        xf - an array of double for fractional x-coordinates.
        yf - an array of double for fractional y-coordinates.
        zf - an array of double for fractional z-coordinates.
        x - an array of double for cartesian x-coordinates.
        y - an array of double for cartesian y-coordinates.
        z - an array of double for cartesian z-coordinates.
      • toCartesianCoordinates

        public void toCartesianCoordinates​(int n,
                                           double[] frac,
                                           double[] cart)
        toCartesianCoordinates
        Parameters:
        n - a int.
        frac - an array of double for fractional coordinates.
        cart - an array of double for cartesian coordinates.
      • toCartesianCoordinates

        public void toCartesianCoordinates​(double[] xf,
                                           double[] x)
        toCartesianCoordinates
        Parameters:
        xf - an array of double for fractional coordinate.
        x - an array of double for cartesian coordinate.
      • toFractionalCoordinates

        public void toFractionalCoordinates​(int n,
                                            double[] x,
                                            double[] y,
                                            double[] z,
                                            double[] xf,
                                            double[] yf,
                                            double[] zf)
        toFractionalCoordinates
        Parameters:
        n - a int.
        x - an array of double for cartesian x-coordinates.
        y - an array of double for cartesian y-coordinates.
        z - an array of double for cartesian z-coordinates.
        xf - an array of double for fractional x-coordinates.
        yf - an array of double for fractional y-coordinates.
        zf - an array of double for fractional z-coordinates.
      • toFractionalCoordinates

        public void toFractionalCoordinates​(int n,
                                            double[] cart,
                                            double[] frac)
        toFractionalCoordinates
        Parameters:
        n - a int.
        cart - an array of double for cartesian coordinates.
        frac - an array of double for fractional coordinates.
      • toFractionalCoordinates

        public void toFractionalCoordinates​(double[] x,
                                            double[] xf)
        toFractionalCoordinates
        Parameters:
        x - an array of double for cartesian coordinate.
        xf - an array of double for fractional coordinate.
      • toPrimaryCell

        public void toPrimaryCell​(double[] in,
                                  double[] out)
        toPrimaryCell
        Parameters:
        in - an array of double.
        out - an array of double.
      • toShortString

        public String toShortString()
        A String containing the unit cell parameters.
        Returns:
        A string with the unit cell parameters.
      • updateCrystal

        public void updateCrystal()
        Update all Crystal variables that are a function of unit cell parameters.