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 * Retrieves the primary atom associated with this RefinedParameter instance.
64 * The returned atom serves as the central reference in the refinement process.
65 *
66 * @return the primary {@link Atom} associated with this RefinedParameter.
67 */
68 public Atom getAtom() {
69 return atom;
70 }
71
72 /**
73 * Sets the index for this RefinedParameter instance.
74 *
75 * @param index the integer value to set as the index
76 */
77 public void setIndex(int index) {
78 this.index = index;
79 }
80
81 /**
82 * Retrieves the index value associated with this RefinedParameter instance.
83 *
84 * @return the integer index value of this RefinedParameter
85 */
86 public int getIndex() {
87 return index;
88 }
89
90 /**
91 * Adds an atom to the list of constrained atoms for the given primary atom.
92 * This method defines the relationship between the primary atom and other atoms
93 * that are constrained or related as part of the refinement process.
94 *
95 * @param atom the atom to be added as a constrained atom associated with the primary atom.
96 */
97 public abstract void addConstrainedAtom(Atom atom);
98
99 /**
100 * Adds an atom to the list of constrained atoms that contribute to experimental scattering.
101 *
102 * @param atom the atom to be added as a constrained atom that has scattering contributions.
103 */
104 public abstract void addConstrainedAtomThatScatters(Atom atom);
105
106 /**
107 * Retrieves the number of parameters associated with this refineable.
108 * Concrete implementations define how the parameters are determined and counted.
109 *
110 * @return the number of parameters related to this refinement process.
111 */
112 public abstract int getNumberOfParameters();
113
114 /**
115 * Get parameters from this RefinedParameter instance.
116 * Concrete implementations define how the given parameter values are processed
117 * and associated with the refinement process.
118 *
119 * @param parameters an array of double values representing all refined parameters.
120 */
121 public abstract void getParameters(double[] parameters);
122
123 /**
124 * Set parameter values into this RefinedParameter instance.
125 *
126 * @param parameters an array of double values representing all refined parameters.
127 */
128 public abstract void setParameters(double[] parameters);
129
130 /**
131 * Retrieves the velocities associated with the refined parameters.
132 *
133 * @param velocity an array of double values where the velocities of
134 * the refined parameters will be stored.
135 */
136 public abstract void getVelocity(double[] velocity);
137
138 /**
139 * Sets the velocities for the refined parameters.
140 *
141 * @param velocity an array of double values representing the velocities for each refined parameter
142 */
143 public abstract void setVelocity(double[] velocity);
144
145 /**
146 * Retrieves the acceleration values associated with the refined parameters.
147 * Concrete implementations define how the acceleration data is retrieved and processed.
148 *
149 * @param acceleration an array of double values where the accelerations of
150 * the refined parameters will be stored
151 */
152 public abstract void getAcceleration(double[] acceleration);
153
154 /**
155 * Sets the acceleration values for the refined parameters.
156 * This method updates the acceleration for each refined parameter based on the provided array.
157 *
158 * @param acceleration an array of double values representing the acceleration for each refined parameter
159 */
160 public abstract void setAcceleration(double[] acceleration);
161
162 /**
163 * Retrieves the previous acceleration values associated with the refined parameters.
164 * Concrete implementations define how the previous acceleration data is retrieved and processed.
165 *
166 * @param acceleration an array of double values where the previous accelerations of
167 * the refined parameters will be stored
168 */
169 public abstract void getPreviousAcceleration(double[] acceleration);
170
171 /**
172 * Sets the previous acceleration values for the refined parameters.
173 * This method updates the previous acceleration for each refined parameter based on the provided array.
174 *
175 * @param acceleration an array of double values representing the previous acceleration for each refined parameter
176 */
177 public abstract void setPreviousAcceleration(double[] acceleration);
178
179 /**
180 * Sets the optimization scaling factors for this RefinedParameter instance.
181 * The scaling factors are typically used to adjust the magnitude of parameter
182 * updates during optimization processes, ensuring appropriate convergence behavior.
183 *
184 * @param optimizationScaling an array of double values representing the scaling
185 * factors for each optimization parameter.
186 */
187 public abstract void setOptimizationScaling(double[] optimizationScaling);
188
189 /**
190 * Zero out the gradient for this RefinedParameter.
191 */
192 public abstract void zeroGradient();
193
194 /**
195 * Load the gradient for this RefinedParameter.
196 */
197 public abstract void getGradient(double[] gradient);
198
199 /**
200 * Mass for extended Lagrangian
201 *
202 * @param mass Store the mass to use for this parameter.
203 * @param defaultMass The default mass to use for this parameter.
204 */
205 public abstract void getMass(double[] mass, double defaultMass);
206 }