CCP4 Coordinate Library Project

RWBROOK interface functions: Data Exchange Between the Channels and Application.
Exchange of Crystallographic Data.


INDEX:
RBFrac3
WBSpGrp1
RBSpGrp1
WBCell1
RBCell1
RBCell2
RBRORF2n
RBFRO1n
CvAnisou1


subroutine RBFrac3 ( iUnit,a,b,c,alpha,beta,gamma,
                     OrthCode,iRet )
PURPOSE:
Sets the crystal cell properties and calculates the orthogonal-fractional transformation matrices for channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

real*4 a,b,c
cell parameters a, b and c (angstroms).

real*4 alpha,beta,gamma
cell parameters alpha, beta and gamma (degrees).

integer OrthCode
the orthogonalization code, which specifies the way of calculation the orthogonalizing matrices. Valid values include:
Code Description
1 orthogonal axes are defined to have a parallel to Xo, c* parallel to Zo
2 orthogonal axes are defined to have b parallel to Xo, a* parallel to Zo
3 orthogonal axes are defined to have c parallel to Xo, b* parallel to Zo
4 orthogonal axes are defined to have a+b parallel to Xo, c* parallel to Zo
5 orthogonal axes are defined to have a* parallel to Xo, c parallel to Zo
6 orthogonal axes are defined to have a parallel to Xo, b* parallel to Yo

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. RBFrac3 may return RWBERR_NoChannel, RWBERR_NoFile, RWBERR_Disagreement, RWBERR_NoOrthCode and RWBERR_NoChaeck. The last three returns would rather indicate an internal problem in the Library.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

RBFrac3 substitutes the RBFrac2 function from former rwbrook.f. The only difference between these two is that RBFrac3 has channel number iUnit as a first parameter. It is important to note here that crystallographic information in RWBROOK interface is local to every channel, while in former rwbrook.f it was global for all channels. Read more details about this here.

An attention should be given to the length of real-type parameters. As a meter of standard, 4-byte real values are assumed. This is determined by the definition of apireal found in file mmdb_rwbrook.h of the Library. More likely than not, a mismatch in the length of real-type parameters passed between application and Library will lead to a crash.

 


subroutine WBSpGrp1 ( iUnit,spGroup,iRet )

PURPOSE:
Sets the space group identifier for the channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

character*(*) spGroup
space group identifier, e.g. 'P 21 21 21'.

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. WBSpGrp1 may return RWBERR_NoChannel and RWBERR_NoFile.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

WBSpGrp1 substitutes the WBSpGrp function from former rwbrook.f. The space group identifier is merely stored in the channel; no calculations are performed.

WBSpGrp1 has two more parameters over that of WBSpGrp from former rwbrook.f: the channel number iUnit and return code iRet. It is important to note here that crystallographic information in RWBROOK interface is local to every channel, while in former rwbrook.f it was global for all channels. Read more details about this here.

 


subroutine RBSpGrp1 ( iUnit,spGroup,iRet )

PURPOSE:
Reads the space group identifier from the channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

character*(*) spGroup
a buffer for the space group identifier.

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. RBSpGrp1 may return RWBERR_NoChannel and RWBERR_NoFile.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

RBSpGrp1 substitutes the RBSpGrp function from former rwbrook.f. It performs exactly opposite to WBSpGrp1 action; the space group identifier is merely retrieved from the channel; no calculations are performed.

RBSpGrp1 has two more parameters over that of RBSpGrp from former rwbrook.f: the channel number iUnit and return code iRet. It is important to note here that crystallographic information in RWBROOK interface is local to every channel, while in former rwbrook.f it was global for all channels. Read more details about this here.

 


subroutine WBCell1 ( iUnit,celld,OrthCode,iRet )

PURPOSE:
Sets the crystal cell properties and calculates the orthogonal-fractional transformation matrices for channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

real*4 celld(6)
array of cell parameters:
celld(1) = a (angstroms)
celld(2) = b (angstroms)
celld(3) = c (angstroms)
celld(4) = alpha (degrees)
celld(5) = beta (degrees)
celld(6) = gamma (degrees)

integer OrthCode
the orthogonalization code, which specifies the way of calculation the orthogonalizing matrices. This parameter has exactly the same meaning as in RBFrac3, see its valid values and their meaning here.

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. WBCell1 may return RWBERR_NoChannel and RWBERR_NoFile.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

WBCell1 substitutes the WBCell function from former rwbrook.f, which performed an immediate output of crystallographic infomration (PDB records 'CRYST1' and 'SCALEn') into output file. Since RWBROOK interface keeps all data in computer's RAM until explicit purging it all at once into a file, actions of WBCell1 and RBFrac3 appear nearly the same. The difference is that WBCell1, unlike RBFrac3, assigns a definite matrix, corresponding to the given orthogonalization code, to what is physically output on cards 'SCALEn'.

WBCell1 has an additional parameter -- the return code iRet -- as compared to WBCell from former rwbrook.f.

An attention should be given to the length of real-type parameters. As a meter of standard, 4-byte real values are assumed. This is determined by the definition of apireal found in file mmdb_rwbrook.h of the Library. More likely than not, a mismatch in the length of real-type parameters passed between application and Library will lead to a crash.

 


subroutine RBCell1 ( iUnit,celld,cvol,iRet )

PURPOSE:
Retrieves the crystal cell properties from channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

real*4 celld(6)
array to accept the cell parameters:
celld(1) = a (angstroms)
celld(2) = b (angstroms)
celld(3) = c (angstroms)
celld(4) = alpha (degrees)
celld(5) = beta (degrees)
celld(6) = gamma (degrees)

real*4 cvol
returns volume of the cell.

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. RBCell1 may return RWBERR_NoChannel, RWBERR_NoFile, RWBERR_NoCellParameters, RWBERR_NoOrthCode and RWBERR_NoCheck.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

RBCell1 substitutes the RBCell function from former rwbrook.f. The information is merely retrieved from the channel, no calculations are made.

RBCell1 has two more parameters over that of RBCell from former rwbrook.f: the channel number iUnit and return code iRet. It is important to note here that crystallographic information in RWBROOK interface is local to every channel, while in former rwbrook.f it was global for all channels. Read more details about this here.

An attention should be given to the length of real-type parameters. As a meter of standard, 4-byte real values are assumed. This is determined by the definition of apireal found in file mmdb_rwbrook.h of the Library. More likely than not, a mismatch in the length of real-type parameters passed between application and Library will lead to a crash.

 


subroutine RBCell2 ( iUnit,celld,cvol,OrthCode,iRet )

PURPOSE:
Retrieves the crystal cell properties and orthogonalization code from channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

real*4 celld(6)
array to accept the cell parameters:
celld(1) = a (angstroms)
celld(2) = b (angstroms)
celld(3) = c (angstroms)
celld(4) = alpha (degrees)
celld(5) = beta (degrees)
celld(6) = gamma (degrees)

real*4 cvol
returns volume of the cell.

real*4 OrthCode
returns the orthogonalization code, which specifies the way of calculation the orthogonalizing matrices. This parameter has exactly the same meaning as in RBFrac3, see its valid values and their meaning here.

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. RBCell1 may return RWBERR_NoChannel, RWBERR_NoFile, RWBERR_NoCellParameters, RWBERR_NoOrthCode and RWBERR_NoCheck.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

RBCell2 acts exactly like RBCell1 plus returns the orthogonalization code. See remarks for RBCell1.

 


subroutine RBRORF2n ( iUnit,RO,RF,OrthCode,iRet )

PURPOSE:
Stores/retrieves the fractionalising (RF) and orthogonalising (RO) 4x4 matrices, as well as the orthogonalisation code (OrthCode) into/from channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

real*4 RO(4,4)
the orthogonalising matrix. If RO(1,1) is set to 0.0 prior to the call of RBRORF2n, the information is retrieved from the channel; otherwise RO, RF and OrthCode are stored into the channel.

real*4 RF(4,4)
the fractionalising matrix.

integer OrthCode
the orthogonalization code, which specifies the way of calculating the orthogonalizing matrices. This parameter has exactly the same meaning as in RBFrac3, see its valid values and their meaning here.

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. RBRORF2n may return RWBERR_NoChannel, RWBERR_NoFile and RWBERR_NoMatrices.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

RBRORF2n substitutes the RBRORF2 function from former rwbrook.f. The way in which the data is passed between the channel and application, is determined by the value of RO(1,1) given to the function, as described above.

RBRORF2n has two more parameters than RBRORF2 function from rwbrook.f: the channel number iUnit and return code iRet. It is important to note here that crystallographic information in RWBROOK interface is local to every channel, while in former rwbrook.f it was global for all channels. Read more details about this here.

An attention should be given to the length of real-type parameters. As a meter of standard, 4-byte real values are assumed. This is determined by the definition of apireal found in file mmdb_rwbrook.h of the Library. More likely than not, a mismatch in the length of real-type parameters passed between application and Library will lead to a crash.

 


subroutine RBFRO1n ( iUnit,celld,Vol,RRR,iRet )

PURPOSE:
Calculates the matrices for standard orthogonalisations and the cell volume in channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

real*4 celld(6)
array of cell parameters (input):
celld(1) = a (angstroms)
celld(2) = b (angstroms)
celld(3) = c (angstroms)
celld(4) = alpha (degrees)
celld(5) = beta (degrees)
celld(6) = gamma (degrees)
If celld(1) is greater then zero, then the existing cell parameters in the channel will be substituted by those given in celld. If new cell parameters differ substantially from the old ones, the returned value of Vol will be negative (this replicates precisely the behaviour of older rwbrook.h).

Vol
returns the unit cell volume. It may be set negative, which serves as an indicator that the new cell parameters, given in celld, differ substantially from what was previously set in the channel (see above).

real*4 RRR(3,3,6)
returns 6 orthogonalising 3x3 matrices corresponding to 6 values of the orthogonalisation code.

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. RBFRO1n may return RWBERR_NoChannel, RWBERR_NoFile and RWBERR_NoCellParams.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

RBFRO1n substitutes the RBFRO1 function from former rwbrook.f. The value of celld(1) determines if new cell parameters are to be set in the channel, as described above.

RBFRO1n has two more parameters than RBFRO1 function from rwbrook.f: the channel number iUnit and return code iRet. It is important to note here that crystallographic information in RWBROOK interface is local to every channel, while in former rwbrook.f it was global for all channels. Read more details about this here.

An attention should be given to the length of real-type parameters. As a meter of standard, 4-byte real values are assumed. This is determined by the definition of apireal found in file mmdb_rwbrook.h of the Library. More likely than not, a mismatch in the length of real-type parameters passed between application and Library will lead to a crash.

 


subroutine CvAnisou1 ( iUnit,U,iFlag,iRet )

PURPOSE:
Converts between crystallographic bs and orthogonal Us or the other way round for channel iUnit.

PARAMETERS:

integer iUnit
the channel number. If iUnit is less than or equal to zero, then the channel number mentioned in the previous call to RWBROOK is used. The channel must be previously opened with function XYZOpen or XYZOpen1 for either input or output.

real*4 U(6)
array of temperature anisotropic factors.

PDB files contain anisotropic temperature factors as orthogonal Us. The anisotropic temperature factors can be input/output to CvAnisou1 as orthogonal or as crystallographic Us.

Shelx defines Uf to calculate temperature factor as:

T(anisoUf) = exp (-2pi2 ( (h*ast)2 Uf11 + (k*bst)2Uf22 + ... + 2hk*ast*bst*Uf12 +..)

Note here that Uoji = Uoij and Ufji = Ufij.

[Uoij] listed on PDB 'ANISOU' card satisfy the relationship:

[Uoij] = [RFu]-1 [Ufij] {[RFu]-1}T

where [Rfu] is the normalised [Rf] matrix read from the 'SCALEn' cards; [ROu] = [RFu]-1.

Hence:
[Uf_ij] = [RFu] [Uoij] {[RFu] }T

T(anisoUo) = U(11)*H**2 + U(22)*K**2 + 2*U(12)*H*K + ...

where H,K,L are the orthogonal reciprocal lattice indicies.

Biso = 8*pi2 (Uo11 + Uo22 + Uo33) / 3.0

[Uf(symmj)] = [Symmj] [Uf] [Symmj]T

integer iFlag
convertion flag: iFlag=0 : convert from fractional to orthogonal Us; iFlag=1 : convert from orthogonal to fractional Us.

integer iRet
the return code. The return codes are listed in Error Handling and Return Codes. Read that section also for learning how to automate the checking of return codes issued by RWBROOK interface functions. CvAnisou1 may return RWBERR_NoChannel, RWBERR_NoFile and RWBERR_NoMatrices.

Zero return (=RWBERR_Ok) means success, no warnings.

 

REMARKS:

CvAnisou1 substitutes the CvAnisou function from former rwbrook.f. The value of iFlag determines the regime of converting the anisotropic temperature factors, as described above.

CvAnisou1 has two more parameters than CvAnisou function from rwbrook.f: the channel number iUnit and return code iRet. It is important to note here that crystallographic information in RWBROOK interface is local to every channel, while in former rwbrook.f it was global for all channels. Read more details about this here.

An attention should be given to the length of real-type parameters. As a meter of standard, 4-byte real values are assumed. This is determined by the definition of apireal found in file mmdb_rwbrook.h of the Library. More likely than not, a mismatch in the length of real-type parameters passed between application and Library will lead to a crash.

 


Back to index