ModulationSet
Date: 2019-10-22

org.jmol.util

## Class ModulationSet

- java.lang.Object
- - javajs.util.T3
  - - javajs.util.V3
    - - org.jmol.util.Vibration
      - - org.jmol.util.ModulationSet

- All Implemented Interfaces:
    java.io.Serializable, javajs.api.JSONEncodable, JmolModulationSet

      public class ModulationSet
      extends Vibration
      implements JmolModulationSet

  A class to group a set of modulations for an atom as a "vibration" Extends V3 so that it will be a displacement, and its value will be an occupancy
  Author:
    Bob Hanson hansonr@stolaf.edu 8/9/2013
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) float[]` | `axesLengths` unit cell axes -- used in Modulation for calculating magnetic modulations
    `private boolean` | `enabled` indicates state of modulated or unmodulated
    `private double` | `fileOcc`
    `private javajs.util.M3` | `gammaE`
    `private javajs.util.Matrix` | `gammaIinv`
    `java.util.Map<java.lang.String,java.lang.Float>` | `htUij` current value of anisotropic parameter modulation
    `(package private) java.lang.String` | `id` an identifier for this modulation
    `private int` | `iop` the symmetry operation used to generate this atom
    `private boolean` | `isCommensurate` commensurate modulations cannot be "undone" and they cannot be turned off
    `private boolean` | `isQ`
    `private boolean` | `isSubsystem` subsystems can deliver their own unique unit cell; they are commensurate
    `private ModulationSet` | `modCalc` modCalc is used for calculations independent of what the current setting is
    `private javajs.util.Lst<Modulation>` | `mods` the list of all modulations associated with this atom
    `javajs.util.V3` | `mxyz` the modulated magnetic spin
    `private int` | `nOps` the number of operators in this space group -- needed for occupancy calculation
    `(package private) boolean` | `occAbsolute` for Crenels (simple occupational modulation or Legendre displacement modulation, the value determined here is absolute (0 or 1), not an adjustment; set in calculate() by one of the modulations
    `private double[]` | `occParams`
    `private double` | `occSiteMultiplicity`
    `private float` | `occValue` final occupancy value -- absolute; in range [0,1]
    `(package private) javajs.util.P3` | `ptTemp`
    `private javajs.util.P3` | `qtOffset`
    `private javajs.util.P3` | `r0` the unmodulated original position of this atom; note that x,y,z extended from Vibration(V3) is the current displacement modulation itself
    `private javajs.util.Matrix` | `rI`
    `private javajs.util.Matrix` | `rsvs` the matrix representation for this atom's symmetry operation
    `private float` | `scale` an adjustable scaling factor, as for vibrations
    `private javajs.util.Matrix` | `sigma`
    `private float` | `spinOp` the spin operation for this atom: +1/0/-1
    `private java.lang.String` | `strop` a string description of the atom's symmetry operator
    `private SymmetryInterface` | `symmetry` the space group appropriate to this atom
    `private javajs.util.Matrix` | `tau`
    `private javajs.util.Matrix` | `tFactorInv`
    `private javajs.util.V3` | `v0`
    `Vibration` | `vib` vib is a spin vector when the model has modulation; otherwise an unmodulated vibration.
    `float` | `vOcc` the current value of the occupancy modulation

    - ### Fields inherited from class org.jmol.util.Vibration

      `modDim, modScale, showTrace, tracePt, twoPI, TYPE_SPIN, TYPE_VIBRATION`

    - ### Fields inherited from class javajs.util.T3

      `x, y, z`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ModulationSet()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addTo(javajs.util.T3 a, float scale)`
    `void` | `addUTens(java.lang.String utens, float v)`
    `ModulationSet` | `calculate(javajs.util.T3 tuv, boolean isQ)` Calculate r_I internal d-space coordinate of an atom.
    `void` | `getInfo(java.util.Map<java.lang.String,java.lang.Object> info)`
    `private ModulationSet` | `getModCalc()`
    `javajs.util.T3` | `getModPoint(boolean asEnabled)`
    `java.lang.Object` | `getModulation(char type, javajs.util.T3 tuv)`
    `private float` | `getOccupancy()`
    `int` | `getOccupancy100(boolean isTemp)`
    `float` | `getScale()`
    `java.lang.String` | `getState()`
    `SymmetryInterface` | `getSubSystemUnitCell()`
    `javajs.util.V3` | `getV3()`
    `Vibration` | `getVibration(boolean forceNew)`
    `boolean` | `isEnabled()`
    `boolean` | `isNonzero()`
    `void` | `scaleVibration(float m)`
    `javajs.util.T3` | `setCalcPoint(javajs.util.T3 pt, javajs.util.T3 t456, float vibScale, float scale)` get updated value for offset vector and for occupancy
    `ModulationSet` | `setMod(java.lang.String id, javajs.util.P3 r00, javajs.util.P3 r0, int d, javajs.util.Lst<Modulation> mods, javajs.util.M3 gammaE, javajs.util.Matrix[] factors, SymmetryInterface symmetry, int nOps, int iop, Vibration v, boolean isCommensurate)` A collection of modulations for a specific atom.
    `void` | `setModTQ(javajs.util.T3 a, boolean isOn, javajs.util.T3 qtOffset, boolean isQ, float scale)` Set modulation "t" value, which sets which unit cell in sequence we are looking at; d=1 only.
    `void` | `setMoment()`
    `float` | `setOccupancy(double[] pt, double foccupancy, double siteMult)` get the occupancy, first from the reader, then from renderer
    `private void` | `setVib(boolean isReset, float modulationScale)`
    `void` | `setXYZ(javajs.util.T3 v)`

    - ### Methods inherited from class org.jmol.util.Vibration

      `addTracePt, clone, setType, startTrace`

    - ### Methods inherited from class javajs.util.V3

      `angle, new3, newV, newVsub`

    - ### Methods inherited from class javajs.util.T3

      `add, add2, add3, ave, cross, distance, distanceSquared, dot, equals, floatToIntBits, hashCode, length, lengthSquared, normalize, scale, scaleAdd2, scaleT, set, setA, setT, sub, sub2, toJSON, toString`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### id

          java.lang.String id

      an identifier for this modulation

    - #### r0

          private javajs.util.P3 r0

      the unmodulated original position of this atom; note that x,y,z extended from Vibration(V3) is the current displacement modulation itself

    - #### symmetry

          private SymmetryInterface symmetry

      the space group appropriate to this atom

    - #### axesLengths

          float[] axesLengths

      unit cell axes -- used in Modulation for calculating magnetic modulations

    - #### nOps

          private int nOps

      the number of operators in this space group -- needed for occupancy calculation

    - #### iop

          private int iop

      the symmetry operation used to generate this atom

    - #### strop

          private java.lang.String strop

      a string description of the atom's symmetry operator

    - #### spinOp

          private float spinOp

      the spin operation for this atom: +1/0/-1

    - #### rsvs

          private javajs.util.Matrix rsvs

      the matrix representation for this atom's symmetry operation

    - #### vib

          public Vibration vib

      vib is a spin vector when the model has modulation; otherwise an unmodulated vibration.

    - #### mods

          private javajs.util.Lst<Modulation> mods

      the list of all modulations associated with this atom

    - #### isSubsystem

          private boolean isSubsystem

      subsystems can deliver their own unique unit cell; they are commensurate

    - #### isCommensurate

          private boolean isCommensurate

      commensurate modulations cannot be "undone" and they cannot be turned off

    - #### fileOcc

          private double fileOcc

    - #### occParams

          private double[] occParams

    - #### occSiteMultiplicity

          private double occSiteMultiplicity

    - #### occAbsolute

          boolean occAbsolute

      for Crenels (simple occupational modulation or Legendre displacement modulation, the value determined here is absolute (0 or 1), not an adjustment; set in calculate() by one of the modulations

    - #### modCalc

          private ModulationSet modCalc

      modCalc is used for calculations independent of what the current setting is

    - #### mxyz

          public javajs.util.V3 mxyz

      the modulated magnetic spin

    - #### htUij

          public java.util.Map<java.lang.String,java.lang.Float> htUij

      current value of anisotropic parameter modulation

    - #### vOcc

          public float vOcc

      the current value of the occupancy modulation

    - #### occValue

          private float occValue

      final occupancy value -- absolute; in range [0,1]

    - #### qtOffset

          private javajs.util.P3 qtOffset

    - #### isQ

          private boolean isQ

    - #### enabled

          private boolean enabled

      indicates state of modulated or unmodulated

    - #### scale

          private float scale

      an adjustable scaling factor, as for vibrations

    - #### gammaE

          private javajs.util.M3 gammaE

    - #### gammaIinv

          private javajs.util.Matrix gammaIinv

    - #### sigma

          private javajs.util.Matrix sigma

    - #### tau

          private javajs.util.Matrix tau

    - #### rI

          private javajs.util.Matrix rI

    - #### tFactorInv

          private javajs.util.Matrix tFactorInv

    - #### ptTemp

          javajs.util.P3 ptTemp

    - #### v0

          private javajs.util.V3 v0

  - ### Constructor Detail

    - #### ModulationSet

          public ModulationSet()

  - ### Method Detail

    - #### getSubSystemUnitCell

          public SymmetryInterface getSubSystemUnitCell()

      Specified by:
        `getSubSystemUnitCell` in interface `JmolModulationSet`

    - #### isEnabled

          public boolean isEnabled()

      Specified by:
        `isEnabled` in interface `JmolModulationSet`

    - #### getScale

          public float getScale()

      Specified by:
        `getScale` in interface `JmolModulationSet`

    - #### setMod

          public ModulationSet setMod(java.lang.String id,
                                      javajs.util.P3 r00,
                                      javajs.util.P3 r0,
                                      int d,
                                      javajs.util.Lst<Modulation> mods,
                                      javajs.util.M3 gammaE,
                                      javajs.util.Matrix[] factors,
                                      SymmetryInterface symmetry,
                                      int nOps,
                                      int iop,
                                      Vibration v,
                                      boolean isCommensurate)

      A collection of modulations for a specific atom.
      Parameters:
        `id` -
        `r00` - originating atom position prior to application of symmetry
        `r0` - unmodulated (average) position after application of symmetry
        `d` -
        `mods` -
        `gammaE` -
        `factors` - including sigma and tFactor
        `symmetry` -
        `iop` -
        `nOps` -
        `v` - TODO
        `isCommensurate` - TODO
      Returns:
        this

    - #### calculate

          public ModulationSet calculate(javajs.util.T3 tuv,
                                         boolean isQ)

      Calculate r_I internal d-space coordinate of an atom.
      Parameters:
        `tuv` -
        `isQ` -
      Returns:
        this ModulationSet, with this.rI set to the coordinate

    - #### addUTens

          public void addUTens(java.lang.String utens,
                               float v)

    - #### setModTQ

          public void setModTQ(javajs.util.T3 a,
                               boolean isOn,
                               javajs.util.T3 qtOffset,
                               boolean isQ,
                               float scale)

      Set modulation "t" value, which sets which unit cell in sequence we are looking at; d=1 only.
      Specified by:
        `setModTQ` in interface `JmolModulationSet`
      Parameters:
        `isOn` -
        `qtOffset` -
        `isQ` -
        `scale` -

    - #### addTo

          public void addTo(javajs.util.T3 a,
                            float scale)

      Specified by:
        `addTo` in interface `JmolModulationSet`

    - #### setVib

          private void setVib(boolean isReset,
                              float modulationScale)

    - #### getState

          public java.lang.String getState()

      Specified by:
        `getState` in interface `JmolModulationSet`

    - #### getModPoint

          public javajs.util.T3 getModPoint(boolean asEnabled)

      Specified by:
        `getModPoint` in interface `JmolModulationSet`

    - #### getModulation

          public java.lang.Object getModulation(char type,
                                                javajs.util.T3 tuv)

      Specified by:
        `getModulation` in interface `JmolModulationSet`

    - #### setCalcPoint

          public javajs.util.T3 setCalcPoint(javajs.util.T3 pt,
                                             javajs.util.T3 t456,
                                             float vibScale,
                                             float scale)

      get updated value for offset vector and for occupancy
      Overrides:
        `setCalcPoint` in class `Vibration`
      Returns:
        pt

    - #### getModCalc

          private ModulationSet getModCalc()

    - #### getInfo

          public void getInfo(java.util.Map<java.lang.String,java.lang.Object> info)

      Overrides:
        `getInfo` in class `Vibration`

    - #### setXYZ

          public void setXYZ(javajs.util.T3 v)

      Overrides:
        `setXYZ` in class `Vibration`

    - #### getVibration

          public Vibration getVibration(boolean forceNew)

      Specified by:
        `getVibration` in interface `JmolModulationSet`

    - #### getV3

          public javajs.util.V3 getV3()

      Specified by:
        `getV3` in interface `JmolModulationSet`

    - #### scaleVibration

          public void scaleVibration(float m)

      Specified by:
        `scaleVibration` in interface `JmolModulationSet`

    - #### setMoment

          public void setMoment()

      Specified by:
        `setMoment` in interface `JmolModulationSet`

    - #### isNonzero

          public boolean isNonzero()

      Overrides:
        `isNonzero` in class `Vibration`

    - #### setOccupancy

          public float setOccupancy(double[] pt,
                                    double foccupancy,
                                    double siteMult)

      get the occupancy, first from the reader, then from renderer
      Parameters:
        `pt` -
        `foccupancy` -
        `siteMult` - or 0 is this is not relevant
      Returns:
        occupancy on [0,1]

    - #### getOccupancy100

          public int getOccupancy100(boolean isTemp)

      Overrides:
        `getOccupancy100` in class `Vibration`
      Parameters:
        `isTemp` - used only in ModulationSet
      Returns:
        Integer.MIN_VALUE if not applicable, occupancy if enabled, -occupancy if not enabled

    - #### getOccupancy

          private float getOccupancy()