1 package ffx.xray.refine;
2
3 import ffx.potential.bonded.Atom;
4
5 import java.util.ArrayList;
6 import java.util.List;
7
8 /**
9 * Represents a parameter that can be refined in an experimental refinement process.
10 * Encapsulates a primary {@link Atom} and a collection of constrained atoms that are
11 * related to this primary atom based on the specific refinement requirement.
12 * The concrete behavior and details of the refinement process are defined by subclasses.
13 */
14 public abstract class RefinedParameter {
15
16 /**
17 * The primary {@link Atom} that serves as the central reference in a refinement process.
18 * This atom is the focal point around which constrained atoms are defined or managed.
19 */
20 protected final Atom atom;
21
22 /**
23 * The index of this parameter in the overall parameter array. If this parameter is
24 * described by more than one variable, the index is for the first variable.
25 */
26 protected int index;
27
28 /**
29 * A collection of atoms that are constrained in relation to a primary {@link Atom}.
30 * These constrained atoms are defined as part of the experimental refinement process
31 * and are related to the primary atom based on specific refinement requirements.
32 * <p>
33 * The refined parameter(s) will be applied to the constrained Atoms, but because these
34 * atoms do not contribute to experimental scattering, their partial derivatives do not
35 * need to be considered.
36 */
37 protected final List<Atom> constrainedAtoms;
38
39 /**
40 * A collection of {@link Atom} instances that are both constrained with respect to a primary {@link Atom}
41 * and directly contribute to experimental scattering.
42 * <p>
43 * The partial derivative of the experimental refinement target with respect to this
44 * parameter(s) is contributed to by each constrained atom that scatters.
45 */
46 protected final List<Atom> constrainedAtomsThatScatter;
47
48 /**
49 * Constructs a new RefinedParameters object for the specified primary {@link Atom}.
50 * The primary atom is set to active, and initialized lists are created for constrained
51 * atoms and constrained atoms that contribute to scattering in the refinement process.
52 *
53 * @param atom the primary {@link Atom} that serves as the central reference in the refinement process.
54 */
55 public RefinedParameter(Atom atom) {
56 this.atom = atom;
57 this.atom.setActive(true);
58 this.constrainedAtoms = new ArrayList<>();
59 this.constrainedAtomsThatScatter = new ArrayList<>();
60 }
61
62 /**
63 * Sets the index for this RefinedParameter instance.
64 *
65 * @param index the integer value to set as the index
66 */
67 public void setIndex(int index) {
68 this.index = index;
69 }
70
71 /**
72 * Retrieves the index value associated with this RefinedParameter instance.
73 *
74 * @return the integer index value of this RefinedParameter
75 */
76 public int getIndex() {
77 return index;
78 }
79
80 /**
81 * Adds an atom to the list of constrained atoms for the given primary atom.
82 * This method defines the relationship between the primary atom and other atoms
83 * that are constrained or related as part of the refinement process.
84 *
85 * @param atom the atom to be added as a constrained atom associated with the primary atom.
86 */
87 public abstract void addConstrainedAtom(Atom atom);
88
89 /**
90 * Adds an atom to the list of constrained atoms that contribute to experimental scattering.
91 *
92 * @param atom the atom to be added as a constrained atom that has scattering contributions.
93 */
94 public abstract void addConstrainedAtomThatScatters(Atom atom);
95
96 /**
97 * Retrieves the number of parameters associated with this refineable.
98 * Concrete implementations define how the parameters are determined and counted.
99 *
100 * @return the number of parameters related to this refinement process.
101 */
102 public abstract int getNumberOfParameters();
103
104 /**
105 * Get parameters from this RefinedParameter instance.
106 * Concrete implementations define how the given parameter values are processed
107 * and associated with the refinement process.
108 *
109 * @param parameters an array of double values representing all refined parameters.
110 */
111 public abstract void getParameters(double[] parameters);
112
113 /**
114 * Set parameter values into this RefinedParameter instance.
115 *
116 * @param parameters an array of double values representing all refined parameters.
117 */
118 public abstract void setParameters(double[] parameters);
119
120 /**
121 * Retrieves the velocities associated with the refined parameters.
122 *
123 * @param velocity an array of double values where the velocities of
124 * the refined parameters will be stored.
125 */
126 public abstract void getVelocity(double[] velocity);
127
128 /**
129 * Sets the velocities for the refined parameters.
130 *
131 * @param velocity an array of double values representing the velocities for each refined parameter
132 */
133 public abstract void setVelocity(double[] velocity);
134
135 /**
136 * Retrieves the acceleration values associated with the refined parameters.
137 * Concrete implementations define how the acceleration data is retrieved and processed.
138 *
139 * @param acceleration an array of double values where the accelerations of
140 * the refined parameters will be stored
141 */
142 public abstract void getAcceleration(double[] acceleration);
143
144 /**
145 * Sets the acceleration values for the refined parameters.
146 * This method updates the acceleration for each refined parameter based on the provided array.
147 *
148 * @param acceleration an array of double values representing the acceleration for each refined parameter
149 */
150 public abstract void setAcceleration(double[] acceleration);
151
152 /**
153 * Retrieves the previous acceleration values associated with the refined parameters.
154 * Concrete implementations define how the previous acceleration data is retrieved and processed.
155 *
156 * @param acceleration an array of double values where the previous accelerations of
157 * the refined parameters will be stored
158 */
159 public abstract void getPreviousAcceleration(double[] acceleration);
160
161 /**
162 * Sets the previous acceleration values for the refined parameters.
163 * This method updates the previous acceleration for each refined parameter based on the provided array.
164 *
165 * @param acceleration an array of double values representing the previous acceleration for each refined parameter
166 */
167 public abstract void setPreviousAcceleration(double[] acceleration);
168
169 /**
170 * Sets the optimization scaling factors for this RefinedParameter instance.
171 * The scaling factors are typically used to adjust the magnitude of parameter
172 * updates during optimization processes, ensuring appropriate convergence behavior.
173 *
174 * @param optimizationScaling an array of double values representing the scaling
175 * factors for each optimization parameter.
176 */
177 public abstract void setOptimizationScaling(double[] optimizationScaling);
178
179 /**
180 * Zero out the gradient for this RefinedParameter.
181 */
182 public abstract void zeroGradient();
183
184 /**
185 * Load the gradient for this RefinedParameter.
186 */
187 public abstract void getGradient(double[] gradient);
188
189 /**
190 * Mass for extended Lagrangian
191 *
192 * @param mass Store the mass to use for this parameter.
193 * @param defaultMass The default mass to use for this parameter.
194 */
195 public abstract void getMass(double[] mass, double defaultMass);
196 }