Package ffx.crystal

Class Crystal

java.lang.Object
ffx.crystal.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:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    double
    Length of the cell edge in the direction of the a basis vector.
    double[][]
    Matrix to convert from Cartesian to fractional coordinates.
    double
    Entry in the A matrix.
    double
    Entry in the A matrix.
    double
    Entry in the A matrix.
    double
    Entry in the A matrix.
    double
    Entry in the A matrix.
    double
    Entry in the A matrix.
    double
    Entry in the A matrix.
    double
    Entry in the A matrix.
    double
    Entry in the A matrix.
    final double[][]
    Matrix to convert from fractional to Cartesian coordinates.
    double
    Entry in the Ai matrix.
    double
    Entry in the Ai matrix.
    double
    Entry in the Ai matrix.
    double
    Entry in the Ai matrix.
    double
    Entry in the Ai matrix.
    double
    Entry in the Ai matrix.
    double
    Entry in the Ai matrix.
    double
    Entry in the Ai matrix.
    double
    Entry in the Ai matrix.
    double
    The interaxial lattice angle between b and c.
    double
    Length of the cell edge in the direction of the b basis vector.
    double
    The interaxial lattice angle between a and c.
    double
    Length of the cell edge in the direction of the c basis vector.
    double
    Change in the volume with respect to a.
    double
    Change in the volume with respect to alpha (in Radians).
    double
    Change in the volume with respect to b.
    double
    Change in the volume with respect to beta (in Radians).
    double
    Change in the volume with respect to c.
    double
    Change in the volume with respect to gamma (in Radians).
    final double[][]
    The direct space metric matrix.
    double
    The interaxial lattice angle between a and b.
    double
    Interfacial radius in the direction of the A-axis.
    double
    Interfacial radius in the direction of the B-axis.
    double
    Interfacial radius in the direction of the C-axis.
    int[]
    Anisotropic bulk solvent B-factor scaling (0 or 1 for each component).
    int
    Number of bulk solvent B-factor components.
    The space group of the crystal.
    double
    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

    Modifier and Type
    Method
    Description
    boolean
    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
    Two crystals are equal only if all unit cell parameters are exactly the same.
    double[]
    getCellParametersFromVectors(double[][] cellVectors)
     
    boolean
     
    double
    getDensity(double mass)
    Compute the density of the system.
    int
    Return the number of symmetry operators for this crystal.
    double[]
    Create a random Cartesian translation vector.
    double
    Getter for the field specialPositionCutoff.
    double
    Getter for the field specialPositionCutoff2.
    void
    getTransformationOperator(SymOp symOp, double[][] rotmat)
    Compute the total transformation operator R = ToCart * Rot * ToFrac.
    The ReplicatesCrystal over-rides this method to return the unit cell rather than the ReplicateCell.
    int
    double
    image(double[] xyz)
    Apply the minimum image convention.
    double
    image(double[] xyz, double[] xyz2)
    Apply the minimum image convention.
    double
    image(double dx, double dy, double dz)
    Apply the minimum image convention.
    double
    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
    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
    A String containing the unit cell parameters.
    final void
    Update all Crystal variables that are a function of unit cell parameters.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • spaceGroup

      @FFXProperty(name="SpaceGroup", propertyGroup=UnitCellAndSpaceGroup, clazz=SpaceGroup.class, defaultValue="P1", description="This property defines the crystal space group used during structural manipulations and force field calculations.\n") public final SpaceGroup spaceGroup
      The space group of the crystal.
    • a

      @FFXProperty(name="a-axis", propertyGroup=UnitCellAndSpaceGroup, defaultValue="None", description="Sets the value of the a-axis length for a crystal unit cell, or, equivalently,\nthe X-axis length for a periodic box (Angstroms).\n") public double a
      Length of the cell edge in the direction of the a basis vector.
    • b

      @FFXProperty(name="b-axis", propertyGroup=UnitCellAndSpaceGroup, defaultValue="A-Axis", description="Sets the value of the b-axis length for a crystal unit cell, or, equivalently,\nthe Y-axis length for a periodic box (Angstroms).\n") public double b
      Length of the cell edge in the direction of the b basis vector.
    • c

      @FFXProperty(name="c-axis", propertyGroup=UnitCellAndSpaceGroup, defaultValue="A-Axis", description="Sets the value of the c-axis length for a crystal unit cell, or, equivalently,\nthe Z-axis length for a periodic box (Angstroms).\n") public double c
      Length of the cell edge in the direction of the c basis vector.
    • alpha

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

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

      @FFXProperty(name="gamma", propertyGroup=UnitCellAndSpaceGroup, defaultValue="Alpha", description="Sets the value of the \u03b3-angle of a crystal unit cell, i.e.,\nthe angle between the a-axis and b-axis of a unit cell, or, equivalently,\nthe angle between the X-axis and Y-axis of a periodic box.\n") 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 Details

    • 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 Details

    • 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, an exception is thrown.

      If mateX, mateY or mateZ are null or not of length n, an exception is thrown.

      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, an exception is thrown.

      If mateX, mateY or mateZ are null or not of length n, an exception is thrown.

      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, double[] xyz2)
      Apply the minimum image convention.
      Parameters:
      xyz - the coordinates of the first atom.
      xyz2 - the coordinates of the second atom.
      Returns:
      the output distance squared.
    • 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 - an 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 - an 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 - an 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 - an 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.
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • updateCrystal

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