JanaReader
Date: 2019-10-22

org.jmol.adapter.readers.xtal

## Class JanaReader

- java.lang.Object
- - org.jmol.adapter.smarter.AtomSetCollectionReader
  - - org.jmol.adapter.readers.xtal.JanaReader

- All Implemented Interfaces:
    javajs.api.GenericLineReader

      public class JanaReader
      extends AtomSetCollectionReader

  A reader for Jana M50+M40 file pairs. TODO: rigid-body rotation TLS, local symmetry, and local axes
  Author:
    Bob Hanson hansonr@stolaf.edu 8/7/2013

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static int` | `CELL`
    `(package private) static int` | `END`
    `private boolean` | `firstPosition`
    `private float[]` | `floats`
    `private boolean` | `haveM40Data`
    `private boolean` | `isLegendre`
    `(package private) static int` | `LATT`
    `private javajs.util.Lst<float[]>` | `lattvecs`
    `private javajs.util.M3` | `matR`
    `private java.lang.String` | `modAxes`
    `private javajs.util.Lst<javajs.util.P3>` | `modelMolecule`
    `private javajs.util.Lst<Atom>` | `molAtoms`
    `private boolean` | `molHasTLS`
    `private java.lang.String` | `molName`
    `private javajs.util.Lst<java.lang.Integer>` | `molTtypes`
    `(package private) static int` | `NDIM`
    `(package private) static int` | `QI`
    `private int` | `qicount`
    `(package private) static java.lang.String` | `records`
    `private javajs.util.P3` | `rho`
    `(package private) static int` | `SPG`
    `(package private) static int` | `SYM`
    `private int` | `thisSub`
    `(package private) static int` | `TITLE`
    `static java.lang.String` | `U_LIST`
    `private javajs.util.V3` | `v0Cart`
    `private javajs.util.V3` | `vR`
    `(package private) static int` | `WMATRIX`
    `private static java.lang.String[]` | `XYZ`

    - ### Fields inherited from class org.jmol.adapter.smarter.AtomSetCollectionReader

      `addedData, addedDataKey, addVibrations, allowPDBFilter, ANGSTROMS_PER_BOHR, applySymmetryToBonds, asc, baseAtomIndex, binaryDoc, bsFilter, bsModels, calculationType, continuing, debugging, desiredModelNumber, desiredSpaceGroupIndex, desiredVibrationNumber, doApplySymmetry, doCentralize, doCheckUnitCell, doConvertToFractional, doPackUnitCell, doProcessLines, doReadMolecularOrbitals, dssr, fileName, fileOffset, filePath, fileScaling, fillRange, filter, filterHetero, fixJavaFloat, forcePacked, getHeader, haveAtomFilter, haveModel, havePartialChargeFilter, htParams, ignoreFileSpaceGroupName, ignoreFileSymmetryOperators, ignoreFileUnitCell, ignoreStructure, iHaveFractionalCoordinates, iHaveSymmetryOperators, iHaveUnitCell, isBinary, isConcatenated, isDSSP1, isFinalized, isMolecular, isPrimitive, isSequential, isTrajectory, latticeCells, latticeScaling, latticeType, line, lstNCS, matUnitCellOrientation, modDim, modelNumber, ms, mustFinalizeModelSet, next, out, packingError, prevline, primitiveToCrystal, ptLine, ptSupercell, reader, readerName, requiresBSFilter, reverseModels, rotateHexCell, sgName, stateScriptVersionInt, strSupercell, symmetry, templateAtomCount, thisBiomolecule, trajectorySteps, unitCellOffset, unitCellParams, useAltNames, useFileModelNumbers, validation, vibrationNumber, vibsFractional, vwr`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JanaReader()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private void` | `addSinCos(int j, java.lang.String key, java.lang.String label, boolean isPos)` Add x, y, and z modulations as [ csin, ccos, 0 ] or, possibly Legendre [ coef, order, 0 ]
    `private void` | `adjustM40Occupancies()` M40 occupancies are divided by the site multiplicity; here we factor that back in.
    `private void` | `cartesianProduct(javajs.util.T3 vA, javajs.util.T3 vB)` dual-purpose function for cross products, proper rotations, and improper rotations
    `private void` | `cell()`
    `protected boolean` | `checkLine()`
    `private double[]` | `combineModulation(java.lang.String key, float csin, float ccos)` Retrieve cataloged displacement and add in this component, returning a new double[3].
    `private void` | `copyModulations(java.lang.String label, java.lang.String newLabel)` Create a new catalog entry for an atom's modulation components.
    `void` | `doPreSymmetry()`
    `private void` | `ensureFourier(int j)` Make sure that F_n record is present.
    `void` | `finalizeSubclassReader()` optional reader-specific method run first.
    `protected void` | `finalizeSubclassSymmetry(boolean haveSymmetry)`
    `private boolean` | `getFlag(int i)` safely get a one-character 0 or 1 as a boolean
    `private int` | `getInt(int col1, int col2)` safe int parsing of line.substring(col1, col2);
    `private java.lang.String` | `getStr(int col1, int col2)` safe string parsing of line.substring(col1, col2);
    `void` | `initializeReader()`
    `private void` | `ndim()`
    `private void` | `parseM40Floats()`
    `private void` | `processPosition(java.lang.String posName, Atom pos, boolean isAxial)` We process the Pos#n record here.
    `private void` | `qi()`
    `private float[][]` | `readAtomRecord(Atom atom, javajs.util.P3 rm, javajs.util.P3 rp, boolean isPos)` Read the atom or pos# record, including occupancy, various flags, and, especially, modulations.
    `private void` | `readM40Data(boolean haveReader)` read the M40 file, possibly as the extension of M50+M40
    `private float[][]` | `readM40FloatLines(int nLines, int nFloats)`
    `private java.lang.String` | `readM40Floats()`
    `private void` | `readM40WaveVectors()`
    `private void` | `setMolecularModulation(java.lang.String key, float csin, float ccos)` Add the modulation after applying rigid-body phase correction
    `private double[]` | `setRigidBodyPhase(java.lang.String key, double[] v)` Adjust phases to match the difference between the atom's position and the rigid molecular fragment's reference point.
    `private void` | `setRigidBodyRotations(java.lang.String label, float[][] params)` Transform unphased Fourier x,y,z cos/sin coefficients in a rigid body system based on distance from center.
    `private java.lang.String` | `skipToNextAtom()`
    `private void` | `symmetry()`

    - ### Methods inherited from class org.jmol.adapter.smarter.AtomSetCollectionReader

      `addAtomXYZSymName, addExplicitLatticeVector, addJmolScript, addSites, addSiteScript, appendLoadNote, appendUunitCellInfo, applySymmetryAndSetTrajectory, applySymTrajASCR, checkCurrentLineForScript, checkFilterKey, checkLastModel, checkLineForScript, clearUnitCell, cloneLastAtomSet, discardLinesUntilBlank, discardLinesUntilContains, discardLinesUntilContains2, discardLinesUntilNonBlank, discardLinesUntilStartsWith, discardPreviousAtoms, doGetModel, doGetVibration, fill3x3, fillDataBlock, fillDataBlockFixed, fillFloatArray, fillFrequencyData, filterAtom, filterReject, finalizeMOData, finalizeModelSet, finalizeReaderASCR, forceSymmetry, fractionalizeCoordinates, getElementSymbol, getFilter, getFortranFormatLengths, getInterface, getNewSymmetry, getStrings, getSymmetry, getTokens, getTokensFloat, initializeSymmetry, initializeSymmetryOptions, initializeTrajectoryFile, isLastModel, newAtomSet, parseFloat, parseFloatRange, parseFloatStr, parseInt, parseIntAt, parseIntRange, parseIntStr, parseToken, parseTokenNext, parseTokenRange, parseTokenStr, processBinaryDocument, processDOM, rd, read3Vectors, readDataObject, readLines, readNextLine, rejectAtomName, RL, set2D, setAtomCoord, setAtomCoordScaled, setAtomCoordTokens, setAtomCoordXYZ, setChainID, setElementAndIsotope, setFilter, setFilterAtomTypeStr, setFractionalCoordinates, setIsPDB, setLoadNote, setModelPDB, setSpaceGroupName, setSymmetryOperator, setTransform, setUnitCell, setUnitCellItem, setup, setupASCR`

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

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

- - ### Field Detail

    - #### lattvecs

          private javajs.util.Lst<float[]> lattvecs

    - #### thisSub

          private int thisSub

    - #### modAxes

          private java.lang.String modAxes

    - #### haveM40Data

          private boolean haveM40Data

    - #### records

          static final java.lang.String records

      See Also:
        Constant Field Values

    - #### TITLE

          static final int TITLE

      See Also:
        Constant Field Values

    - #### CELL

          static final int CELL

      See Also:
        Constant Field Values

    - #### NDIM

          static final int NDIM

      See Also:
        Constant Field Values

    - #### QI

          static final int QI

      See Also:
        Constant Field Values

    - #### LATT

          static final int LATT

      See Also:
        Constant Field Values

    - #### SYM

          static final int SYM

      See Also:
        Constant Field Values

    - #### SPG

          static final int SPG

      See Also:
        Constant Field Values

    - #### END

          static final int END

      See Also:
        Constant Field Values

    - #### WMATRIX

          static final int WMATRIX

      See Also:
        Constant Field Values

    - #### qicount

          private int qicount

    - #### molName

          private java.lang.String molName

    - #### molAtoms

          private javajs.util.Lst<Atom> molAtoms

    - #### molTtypes

          private javajs.util.Lst<java.lang.Integer> molTtypes

    - #### modelMolecule

          private javajs.util.Lst<javajs.util.P3> modelMolecule

    - #### molHasTLS

          private boolean molHasTLS

    - #### matR

          private javajs.util.M3 matR

    - #### rho

          private javajs.util.P3 rho

    - #### firstPosition

          private boolean firstPosition

    - #### vR

          private javajs.util.V3 vR

    - #### v0Cart

          private javajs.util.V3 v0Cart

    - #### isLegendre

          private boolean isLegendre

    - #### U_LIST

          public static final java.lang.String U_LIST

      See Also:
        Constant Field Values

    - #### XYZ

          private static java.lang.String[] XYZ

    - #### floats

          private float[] floats

  - ### Constructor Detail

    - #### JanaReader

          public JanaReader()

  - ### Method Detail

    - #### initializeReader

          public void initializeReader()
                                throws java.lang.Exception

      Overrides:
        `initializeReader` in class `AtomSetCollectionReader`
      Throws:
        `java.lang.Exception`

    - #### checkLine

          protected boolean checkLine()
                               throws java.lang.Exception

      Overrides:
        `checkLine` in class `AtomSetCollectionReader`
      Returns:
        true if need to read new line
      Throws:
        `java.lang.Exception`

    - #### doPreSymmetry

          public void doPreSymmetry()
                             throws java.lang.Exception

      Overrides:
        `doPreSymmetry` in class `AtomSetCollectionReader`
      Throws:
        `java.lang.Exception`

    - #### finalizeSubclassReader

          public void finalizeSubclassReader()
                                      throws java.lang.Exception

      Description copied from class: `AtomSetCollectionReader`
      optional reader-specific method run first.
      Overrides:
        `finalizeSubclassReader` in class `AtomSetCollectionReader`
      Throws:
        `java.lang.Exception`

    - #### finalizeSubclassSymmetry

          protected void finalizeSubclassSymmetry(boolean haveSymmetry)
                                           throws java.lang.Exception

      Overrides:
        `finalizeSubclassSymmetry` in class `AtomSetCollectionReader`
      Throws:
        `java.lang.Exception`

    - #### cell

          private void cell()
                     throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### ndim

          private void ndim()
                     throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### qi

          private void qi()
                   throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### symmetry

          private void symmetry()
                         throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### readM40Data

          private void readM40Data(boolean haveReader)
                            throws java.lang.Exception

      read the M40 file, possibly as the extension of M50+M40
      Parameters:
        `haveReader` -
      Throws:
        `java.lang.Exception`

    - #### getInt

          private int getInt(int col1,
                             int col2)

      safe int parsing of line.substring(col1, col2);
      Parameters:
        `col1` -
        `col2` -
      Returns:
        value or 0

    - #### getStr

          private java.lang.String getStr(int col1,
                                          int col2)

      safe string parsing of line.substring(col1, col2);
      Parameters:
        `col1` -
        `col2` -
      Returns:
        value or ""

    - #### getFlag

          private boolean getFlag(int i)

      safely get a one-character 0 or 1 as a boolean
      Parameters:
        `i` -
      Returns:
        true if it was a 1

    - #### skipToNextAtom

          private java.lang.String skipToNextAtom()
                                           throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### readM40WaveVectors

          private void readM40WaveVectors()
                                   throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### processPosition

          private void processPosition(java.lang.String posName,
                                       Atom pos,
                                       boolean isAxial)
                                throws java.lang.Exception

      We process the Pos#n record here. This involves cloning the free atoms, translating and rotating them to the proper locations, and copying the modulations. Jmol uses the alternative location PDB option (%1, %2,...) to specify the group, enabling the Jmol command DISPLAY configuration=1, for example. We also set a flag to prevent autobonding between alt-loc sets. This is not perfect, as in some cases "pos#2" would be better than "pos#1" in terms of bonding. At this point we only support systType=1 (basic coordinates)
      Parameters:
        `posName` -
        `pos` -
        `isAxial` -
      Throws:
        `java.lang.Exception`

    - #### cartesianProduct

          private void cartesianProduct(javajs.util.T3 vA,
                                        javajs.util.T3 vB)

      dual-purpose function for cross products, proper rotations, and improper rotations
      Parameters:
        `vA` -
        `vB` -

    - #### readAtomRecord

          private float[][] readAtomRecord(Atom atom,
                                           javajs.util.P3 rm,
                                           javajs.util.P3 rp,
                                           boolean isPos)
                                    throws java.lang.Exception

      Read the atom or pos# record, including occupancy, various flags, and, especially, modulations. Not implemented: TLS, space groups, and local position rotation axes.
      Parameters:
        `atom` -
        `rm` - // rotation vector/point not implemented
        `rp` - // rotation point not implemented
        `isPos` -
      Returns:
        pos# record's rotational displacement data
      Throws:
        `java.lang.Exception`

    - #### addSinCos

          private void addSinCos(int j,
                                 java.lang.String key,
                                 java.lang.String label,
                                 boolean isPos)
                          throws java.lang.Exception

      Add x, y, and z modulations as [ csin, ccos, 0 ] or, possibly Legendre [ coef, order, 0 ]
      Parameters:
        `j` -
        `key` -
        `label` -
        `isPos` -
      Throws:
        `java.lang.Exception`

    - #### ensureFourier

          private void ensureFourier(int j)

      Make sure that F_n record is present.
      Parameters:
        `j` -

    - #### readM40Floats

          private java.lang.String readM40Floats()
                                          throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### parseM40Floats

          private void parseM40Floats()

    - #### readM40FloatLines

          private float[][] readM40FloatLines(int nLines,
                                              int nFloats)
                                       throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### adjustM40Occupancies

          private void adjustM40Occupancies()

      M40 occupancies are divided by the site multiplicity; here we factor that back in.

    - #### copyModulations

          private void copyModulations(java.lang.String label,
                                       java.lang.String newLabel)

      Create a new catalog entry for an atom's modulation components. Just occupation and displacement here.
      Parameters:
        `label` -
        `newLabel` -

    - #### setRigidBodyPhase

          private double[] setRigidBodyPhase(java.lang.String key,
                                             double[] v)

      Adjust phases to match the difference between the atom's position and the rigid molecular fragment's reference point. We have: a' = g + vR Here we want just the local rotational part, vR
      Parameters:
        `key` -
        `v` -
      Returns:
        phase-adjusted parameters

    - #### setRigidBodyRotations

          private void setRigidBodyRotations(java.lang.String label,
                                             float[][] params)

      Transform unphased Fourier x,y,z cos/sin coefficients in a rigid body system based on distance from center. We have: a' = g + vR = g + R(v0) Here we need just the original atom offset from the reference point, v0, as a Cartesian vector.
      Parameters:
        `label` - ";atomName"
        `params` - block of [nDisp][6] rotational parameters

    - #### combineModulation

          private double[] combineModulation(java.lang.String key,
                                             float csin,
                                             float ccos)

      Retrieve cataloged displacement and add in this component, returning a new double[3].
      Parameters:
        `key` -
        `csin` -
        `ccos` -
      Returns:
        new array

    - #### setMolecularModulation

          private void setMolecularModulation(java.lang.String key,
                                              float csin,
                                              float ccos)

      Add the modulation after applying rigid-body phase correction
      Parameters:
        `key` -
        `csin` -
        `ccos` -