Package ffx.xray.refine

Class RefinedOccupancy

java.lang.Object
ffx.xray.refine.RefinedParameter
ffx.xray.refine.RefinedOccupancy
public class RefinedOccupancy extends RefinedParameter
The RefinableOccupancy class represents an atom and manages its occupancy value along with any constrained atoms that share the same occupancy constraints. It allows setting and retrieving the occupancy value, ensuring that all constrained atoms are synchronized with the primary atom's occupancy.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final List<Atom>
    complementList
    A collection of atoms that are constrained in relation to a primary Atom.
    protected final List<Atom>
    complementScatterList
    A collection of Atom instances that are both constrained with respect to a primary Atom and directly contribute to experimental scattering.

    Fields inherited from class ffx.xray.refine.RefinedParameter

    atom, constrainedAtoms, constrainedAtomsThatScatter, index

  • Constructor Summary

    Constructors
    Constructor
    Description
    RefinedOccupancy(Atom atom)
    Constructs a RefinableOccupancy instance for managing the specified atom.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addConstrainedAtom(Atom atom)
    Adds an atom to the list of constrained atoms for the given primary atom.
    void
    addConstrainedAtomComplement(Atom atom)
    Adds an atom constrained to this RefinedOccupancy instance.
    void
    addConstrainedAtomThatScatters(Atom atom)
    Adds an atom to the list of constrained atoms that contribute to experimental scattering.
    void
    addConstrainedAtomThatScattersComplement(Atom atom)
    Adds an atom constrained to this RefinedOccupancy instance as a complementary, scattering atom.
    void
    getAcceleration(double[] acceleration)
    Updates the specified acceleration array with the occupancy acceleration of the primary atom managed by this instance at the relevant index.
    void
    getGradient(double[] gradient)
    Updates the specified gradient array with the occupancy gradients of the primary atom and any constrained atoms that scatter.
    void
    getMass(double[] mass, double defaultMass)
    Updates the specified mass array with the default mass value at the relevant index.
    int
    getNumberOfParameters()
    Retrieves the number of parameters associated with this refineable.
    double
    getOccupancy()
    Retrieves the occupancy value of the primary atom managed by this instance.
    void
    getParameters(double[] parameters)
    Updates the specified parameters array with the occupancy value of the primary atom managed by this instance at the specified index.
    void
    getPreviousAcceleration(double[] previousAcceleration)
    Updates the specified previous acceleration array with the occupancy acceleration of the primary atom managed by this instance at the relevant index.
    void
    getVelocity(double[] velocity)
    Updates the specified parameters array with the occupancy velocity of the primary atom managed by this instance at the specified index.
    void
    setAcceleration(double[] acceleration)
    Sets the occupancy acceleration for the primary atom based on the specified array.
    void
    setOccupancy(double occupancy)
    Sets the occupancy value for the primary atom and any constrained atoms, ensuring that all atoms share the same occupancy value.
    void
    setOptimizationScaling(double[] optimizationScaling)
    Sets the optimization scaling factors for this RefinedParameter instance.
    void
    setParameters(double[] parameters)
    Sets the occupancy value for the primary atom and any constrained atoms using a specified index within the parameters array.
    void
    setPreviousAcceleration(double[] previousAcceleration)
    Sets the occupancy previous acceleration for the primary atom based on the specified array.
    void
    setVelocity(double[] velocity)
    Updates the occupancy velocity for the primary atom managed by this instance using a specified value from the parameters array at the specified index.
    String
    toString()
     
    void
    zeroGradient()
    Resets the occupancy gradient associated with the primary atom and any constrained atoms to zero.

    Methods inherited from class ffx.xray.refine.RefinedParameter

    getIndex, setIndex

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • complementList

      protected final List<Atom> complementList
      A collection of atoms that are constrained in relation to a primary Atom. These constrained atoms are defined as part of the experimental refinement process and are related to the primary atom based on specific refinement requirements.

      The refined parameter(s) will be applied to the constrained Atoms, but because these atoms do not contribute to experimental scattering, their partial derivatives do not need to be considered.

      The occupancy of these atoms will be set to 1.0 - occupancy of this parameter.

    • complementScatterList

      protected final List<Atom> complementScatterList
      A collection of Atom instances that are both constrained with respect to a primary Atom and directly contribute to experimental scattering.

      The partial derivative of the experimental refinement target with respect to this parameter(s) is contributed to by each constrained atom that scatters.

      The occupancy of these atoms will be set to 1.0 - occupancy of this parameter. There contribution to the gradient will be negated.

  • Constructor Details

    • RefinedOccupancy

      public RefinedOccupancy(Atom atom)
      Constructs a RefinableOccupancy instance for managing the specified atom.
      Parameters:
      atom - the primary atom whose occupancy value will be managed and potentially constrained to synchronize with other atoms

  • Method Details

    • addConstrainedAtom

      public void addConstrainedAtom(Atom atom)
      Description copied from class: RefinedParameter
      Adds an atom to the list of constrained atoms for the given primary atom. This method defines the relationship between the primary atom and other atoms that are constrained or related as part of the refinement process.
      Specified by:
      addConstrainedAtom in class RefinedParameter
      Parameters:
      atom - the atom to be added as a constrained atom associated with the primary atom.

    • addConstrainedAtomThatScatters

      public void addConstrainedAtomThatScatters(Atom atom)
      Description copied from class: RefinedParameter
      Adds an atom to the list of constrained atoms that contribute to experimental scattering.
      Specified by:
      addConstrainedAtomThatScatters in class RefinedParameter
      Parameters:
      atom - the atom to be added as a constrained atom that has scattering contributions.

    • addConstrainedAtomComplement

      public void addConstrainedAtomComplement(Atom atom)
      Adds an atom constrained to this RefinedOccupancy instance. The specified atom will have its active status enabled and its occupancy value set to complement the occupancy of the primary atom managed by this instance.
      Parameters:
      atom - the atom to be added as a complementary, constrained atom. Its occupancy will be adjusted to ensure it complements the occupancy of the primary atom.

    • addConstrainedAtomThatScattersComplement

      public void addConstrainedAtomThatScattersComplement(Atom atom)
      Adds an atom constrained to this RefinedOccupancy instance as a complementary, scattering atom. The specified atom will have its active status enabled and its occupancy value set to complement the occupancy of the primary atom managed by this instance. Additionally, the atom will be added to the complementScatterList.
      Parameters:
      atom - the atom to be added as a complementary, constrained, scattering atom. Its occupancy will be adjusted to ensure it complements the occupancy of the primary atom.

    • getNumberOfParameters

      public int getNumberOfParameters()
      Description copied from class: RefinedParameter
      Retrieves the number of parameters associated with this refineable. Concrete implementations define how the parameters are determined and counted.
      Specified by:
      getNumberOfParameters in class RefinedParameter
      Returns:
      the number of parameters related to this refinement process.

    • getOccupancy

      public double getOccupancy()
      Retrieves the occupancy value of the primary atom managed by this instance. The occupancy represents the fractional occupancy of the atom in the molecular structure.
      Returns:
      the occupancy value of the primary atom as a double

    • setOccupancy

      public void setOccupancy(double occupancy)
      Sets the occupancy value for the primary atom and any constrained atoms, ensuring that all atoms share the same occupancy value. The occupancy represents the fractional occupancy of the atom in the molecular structure.
      Parameters:
      occupancy - the new occupancy value to be assigned to the primary atom and all constrained atoms

    • getParameters

      public void getParameters(double[] parameters)
      Updates the specified parameters array with the occupancy value of the primary atom managed by this instance at the specified index.
      Specified by:
      getParameters in class RefinedParameter
      Parameters:
      parameters - an array of doubles representing the parameters to be updated.

    • setParameters

      public void setParameters(double[] parameters)
      Sets the occupancy value for the primary atom and any constrained atoms using a specified index within the parameters array.
      Specified by:
      setParameters in class RefinedParameter
      Parameters:
      parameters - an array of doubles containing all refined parameters.

    • getVelocity

      public void getVelocity(double[] velocity)
      Updates the specified parameters array with the occupancy velocity of the primary atom managed by this instance at the specified index. The velocity represents the rate of change of the atom's occupancy with units of degrees per picosecond.
      Specified by:
      getVelocity in class RefinedParameter
      Parameters:
      velocity - an array of doubles to be updated with the atom's occupancy velocity.

    • setVelocity

      public void setVelocity(double[] velocity)
      Updates the occupancy velocity for the primary atom managed by this instance using a specified value from the parameters array at the specified index.
      Specified by:
      setVelocity in class RefinedParameter
      Parameters:
      velocity - an array of doubles representing refined parameters, where the relevant velocity value is extracted and applied.

    • getAcceleration

      public void getAcceleration(double[] acceleration)
      Updates the specified acceleration array with the occupancy acceleration of the primary atom managed by this instance at the relevant index. The acceleration represents the second derivative of the atom's occupancy with respect to time.
      Specified by:
      getAcceleration in class RefinedParameter
      Parameters:
      acceleration - an array of doubles to be updated with the atom's occupancy acceleration.

    • setAcceleration

      public void setAcceleration(double[] acceleration)
      Sets the occupancy acceleration for the primary atom based on the specified array. This method updates the occupancy acceleration of the atom managed by this instance using the value at the specified index.
      Specified by:
      setAcceleration in class RefinedParameter
      Parameters:
      acceleration - an array of doubles representing the acceleration values to be used for updating the atom's occupancy acceleration.

    • getPreviousAcceleration

      public void getPreviousAcceleration(double[] previousAcceleration)
      Updates the specified previous acceleration array with the occupancy acceleration of the primary atom managed by this instance at the relevant index. The previous acceleration represents the second derivative of the atom's occupancy with respect to time.
      Specified by:
      getPreviousAcceleration in class RefinedParameter
      Parameters:
      previousAcceleration - an array of doubles to be updated with the atom's occupancy acceleration.

    • setPreviousAcceleration

      public void setPreviousAcceleration(double[] previousAcceleration)
      Sets the occupancy previous acceleration for the primary atom based on the specified array. This method updates the occupancy previous acceleration of the atom managed by this instance using the value at the specified index.
      Specified by:
      setPreviousAcceleration in class RefinedParameter
      Parameters:
      previousAcceleration - an array of doubles representing the previous acceleration values to be used for updating the atom's occupancy acceleration.

    • setOptimizationScaling

      public void setOptimizationScaling(double[] optimizationScaling)
      Description copied from class: RefinedParameter
      Sets the optimization scaling factors for this RefinedParameter instance. The scaling factors are typically used to adjust the magnitude of parameter updates during optimization processes, ensuring appropriate convergence behavior.
      Specified by:
      setOptimizationScaling in class RefinedParameter
      Parameters:
      optimizationScaling - an array of double values representing the scaling factors for each optimization parameter.

    • zeroGradient

      public void zeroGradient()
      Resets the occupancy gradient associated with the primary atom and any constrained atoms to zero. This method ensures that the occupancy gradient for the primary atom, constrained atoms, and constrained atoms that scatter are all reset to a value of 0.0.

      The occupancy gradient represents the partial derivative of the energy with respect to the atom's occupancy, and this reset is part of the gradient update process.

      Specified by:
      zeroGradient in class RefinedParameter

    • getGradient

      public void getGradient(double[] gradient)
      Updates the specified gradient array with the occupancy gradients of the primary atom and any constrained atoms that scatter.
      Specified by:
      getGradient in class RefinedParameter
      Parameters:
      gradient - an array of doubles representing the gradient to be updated.

    • getMass

      public void getMass(double[] mass, double defaultMass)
      Updates the specified mass array with the default mass value at the relevant index.
      Specified by:
      getMass in class RefinedParameter
      Parameters:
      mass - an array of doubles representing the mass values to be updated.
      defaultMass - a double representing the default mass value to assign.

    • toString

      public String toString()
      Overrides:
      toString in class Object