For comparisions of the results of the new vs. old routines, see residue-by-residue analyses
in catpi.docx.

catPiSBNow and preContactsNow are external variables (from doViewLink).

---------------------
The old code found cations and rings where the 3 key ring atoms were within 6
of ANY cations. The cations could be multiple residues, so that no single
cation residue was within 6 of all 3 key ring atoms. Result was display
of a ring with no cation.

This case showed a ring with no nearby cation.
Example: Tyr6 in 4enl.
The 3 key ring atoms in Tyr6 are within 6 of Lys4 or Arg8, but no atoms in those
cationic residues are within 6 of all 3 key ring atoms.

This case showed Arg141:A and :C unpaired with rings.

The new code finds cation candidates and then verifies each one by looping
through the nearby rings one ring at a time to see if any single ring has all 3
key atoms within 6. Unpaired residues disappeared with new code.

The trick was to learn how to loop per residue. Could be done either with *.ca
or groupindex (unique index number per residue). I chose groupindex in case of
the unlikely possibility that a residue with cation atoms might be missing
its alpha carbon. See test scripts in molvis/jmol_tests/loop-per-residue/

BUT the new code gets very slow for large structures. Thus I decided to use the old code
when >10,000 atoms, and the new code only when fewer (about 90% of entries).

                           Seconds*                      Report
             Protein  –––––––––––––––––––        ––––––––––––––––––––––––
PDBId Atoms   kDa     Old Code   New Code        Cations  Rings  NTermini
–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
6mt3    4K      42                                 10      10     1
2v61    9K     104                5.4              17      16     0
2cvo   12K     142                6.5,6.5          11      15     0
5ibx   17K     196    5.3,4.8§   15.7,12.8,13      24      32     0
                      7.5¶
7ahl   23K     220    4.9        20.4              36      33     7
                      11.2,10.6¶
6n0x   31K     216               22
–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
* With 'Report Elapsed Times' on, from "doViewLink(makeCatPiSBSpt()) starting (jcontrol.js)"
to "BUSY-OFF from scriptToJmol() (consurf/msgcall.js)".
§ Replicate measurements.
¶ With per-residue code for ends only.
FOR OTHER PDB ENTRY SIZES SEE PROTEOPEDIA JSMOL NOTES.

-------------------------------------------------------------------------
METHOD
-------------------------------------------------------------------------
The Tools tab link calls makeCatPiSBSpt() (scripts.js) and makeCatPiSBHelp() (help.js).

The detection is done by setting selectedFound to ((lys,arg) and not backbone) + N-termini
(in makeCatPiSBSpt()) and then calling makeDefineContactsSpt() which is used both for
SB/CatPi and for Contacts.

The controls in the CatPiSB help panel call renderCatPiSB() (scripts.js) which calls
makeRenderCatPiSBSpt() 

The original code for catpi detection was flawed (but fast). It detects some pairs
that are invalid and also detects some unpaired cations or rings: see example
in catpi.docx.

For FGiJ 3.0, new code fixes that bug by looping per residue. But the new code is slow.
So new code is used only when the total non-H atoms <= 12K
allAtomNonHM1C1Count <= catPiLimitNewAlgorithm

For larger models, the old buggy fast code is still used, but the help displays an option
to re-detect catpi with more accurate code, which uses reDetectCatPi() which sets
detectCatPiPerResidueOnce = true;
and then calls madeCatPiSBSpt2() NOTE THE 2.


-------------------------------------------------------------------------
OLD CODE USED PRIOR TO FGIJ 3.0 (NOW USED ONLY FOR LARGE MODELS).
-------------------------------------------------------------------------

	// CATION PI CONTACTS 
	// cation sidechains outside target
"select (~outside_contarget and (lys.ce,lys.nz,arg.cz,arg.cd) " +
"and within(6.0, (~contarget and (trp.cd2,tyr.cd1,phe.cd1))) " +
"and within(6.0, (~contarget and (trp.cz2,tyr.cd2,phe.cd2))) " +
"and within(6.0, (~contarget and (trp.cz3,tyr.cz,phe.cz))));\n" +
"define ~ocatpi0 selected;\n" +
	// ~ocatpi0 = catpi nitrogen cations.

	// pi rings
"select (~outside_contarget and (trp.cd2,tyr.cd1,phe.cd1) " +
"and within(6.0, (~contarget and (lys.ce,lys.nz,arg.cz,arg.cd)))); \
select within(group, selected);\n\
define ~ocatpi1 selected;\n" +

"select ~ocatpi1 and (trp.cz2,tyr.cd2,phe.cd2) " +
"and within(6.0, (~contarget and (lys.ce,lys.nz,arg.cz,arg.cd)));\n\
select within(group, selected);\n\
define ~ocatpi2 selected;\n" +

"select ~ocatpi2 and (trp.cz3,tyr.cz,phe.cz) " +
"and within(6.0, (~contarget and (lys.ce,lys.nz,arg.cz,arg.cd)));\n" +
"select within(group, selected);\n" +
"define ~ocatpi3 selected;\n" +


	// catpi aromatic residues are now selected.
	// Next, restrict selection to 6-carbon rings.

"select selected and (trp.cd2,trp.ce?,trp.cz?,trp.ch?, " +
"phe.cg,phe.cd?,phe.ce?,phe.cz, " +
"tyr.cg,tyr.cd?,tyr.ce?,tyr.cz);\n\
select selected or ~ocatpi0;\n\
define ~cont_catpi_noends selected;\n" +

-------------------------------------------------------------------------

	// CATION PI TARGETS
	// cation sidechains in target
"select (~contarget and (lys.ce,lys.nz,arg.cz,arg.cd) " +
"and within(6.0, (~outside_contarget and (trp.cd2,tyr.cd1,phe.cd1))) " +
"and within(6.0, (~outside_contarget and (trp.cz2,tyr.cd2,phe.cd2))) " +
"and within(6.0, (~outside_contarget and (trp.cz3,tyr.cz,phe.cz))));\n" +
"define ~tcatpi0 selected;\n" +

	// pi rings
"select (~contarget and (trp.cd2,tyr.cd1,phe.cd1) " +
"and within(6.0, (~outside_contarget and (lys.ce,lys.nz,arg.cz,arg.cd)))); \
select within(group, selected);\n\
define ~tcatpi1 selected;\n" +

"select ~tcatpi1 and (trp.cz2,tyr.cd2,phe.cd2) " +
"and within(6.0, (~outside_contarget and (lys.ce,lys.nz,arg.cz,arg.cd)));\n\
select within(group, selected);\n\
define ~tcatpi2 selected;\n" +

"select ~tcatpi2 and (trp.cz3,tyr.cz,phe.cz) " +
"and within(6.0, (~outside_contarget and (lys.ce,lys.nz,arg.cz,arg.cd)));\n\
select within(group, selected);\n" +
"define ~tcatpi3 selected;\n" +


	// target ring residues selected
	// next narrow to 6 carbon rings

"select selected and (trp.cd2,trp.ce?,trp.cz?,trp.ch?, " +
"phe.cg,phe.cd?,phe.ce?,phe.cz, " +
"tyr.cg,tyr.cd?,tyr.ce?,tyr.cz);\n\
select selected or ~tcatpi0;\n\
define ~targ_catpi_noends selected;\n" +

	// GATHER CATPI GROUPS
"select ~cont_catpi_noends, ~cont_catpi_nterm, ~cont_catpi_endrings;\n" +
"define ~cont_catpi selected;\n" +
"define ~catpi_rings selected;\n" +
"select ~targ_catpi_noends, ~targ_catpi_nterm, ~targ_catpi_endrings;\n" +
"define ~targ_catpi selected;\n" +
"define ~catpi_cations selected;\n" +

"select within(group, (~catpi_cations, ~catpi_rings));\n" +
"define ~catpi_amino_acids selected;\n";

-------------------------------------------------------------------------
ENDS

// End-N to rings
"select ~chargedEndNitrogens " +
"and within(6.0, (trp.cd2,tyr.cd1,phe.cd1)) " +
"and within(6.0, (trp.cz2,tyr.cd2,phe.cd2)) " +
"and within(6.0, (trp.cz3,tyr.cz,phe.cz));\n" +
"define ~cont_catpi_nterm (selected and ~outside_contarget);\n" +
"define ~targ_catpi_nterm (selected and ~contarget);\n" +
"define ~catpi_nterm selected;\n" +

// Rings to end-N
"select (trp.cd2,tyr.cd1,phe.cd1) and within (6.0, ~catpi_nterm);\n" +
"select within(group, selected);\n" +
"select selected and (trp.cz2,tyr.cd2,phe.cd2) and within (6.0, ~catpi_nterm);\n" +
"select within(group, selected);\n" +
"select selected and (trp.cz3,tyr.cz,phe.cz) and within (6.0, ~catpi_nterm);\n" +
"select within(group, selected);\n" +

	// Ring to End-N CatPi residues are now selected. Next restrict to ring 6-carbons.
"select selected and (trp.cd2,trp.ce?,trp.cz?,trp.ch?, " +
"phe.cg,phe.cd?,phe.ce?,phe.cz, " +
"tyr.cg,tyr.cd?,tyr.ce?,tyr.cz);\n" +

	//Define targ and cont rings
"define ~catpi_endrings selected;\n" +
"define ~cont_catpi_endrings (~catpi_endrings and ~outside_contarget);\n" +
"define ~targ_catpi_endrings (~catpi_endrings and ~contarget);\n";


-------------------------------------------------------------------------
-------------------------------------------------------------------------
