This shows you the differences between two versions of the page.
gibbs [2012/11/15 14:45] ignacy created |
gibbs [2012/11/15 14:46] (current) ignacy |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | Module HASH_DB | + | Module Gibbs |
+ | |||
+ | Ignacy Misztal, University of Georgia | ||
+ | 04/29/99-04/19/2001 | ||
- | Written by Ignacy Misztal, University of Georgia | + | Introduction |
- | June 6, 2001 - July 16, 2001 | + | ============ |
- | Module hash_db implements simple database(s) using hash tables in memory and | + | Module Gibbs is a collection of data manipulation subroutines useful for |
- | Fortran 90. Operations include: | + | implementing the Gibbs sampler predominantly in the BLUPF90 environment. |
+ | To understand the module fully, please read the documentation on modules | ||
+ | SPARSEM and PROB, and on BLUPF90. | ||
- | 1. declare a table | + | Subroutine link_hash was inspired by Urs Schnyder, ETH, Switzerland. |
- | type (db_hash)::x | ||
- | |||
- | where x is a database | ||
- | |||
- | 2, Initialize | ||
- | call init(x) | + | Module Gibbs |
- | + | ============ | |
- | 3. Declare fields | + | |
- | call add_field(x,name,type,n) | ||
- | |||
- | where alphanumeric variable name contains name of field, type is | ||
- | alphanumeric field specifying type of variable as "character", "integer", | ||
- | or "real", and n is optional variable that specifies length of | ||
- | "character" field. | ||
- | |||
- | 4. Indicate which field is an index | ||
- | call set_index(x,name) | + | LINK_HASH |
- | + | ---------- | |
- | where name is an alphanumeric variable containing the name of field that | + | |
- | will serve as index. All searches are by the index. | + | |
- | 5. Indicate that all field definitions are provided | + | call link_hash_ija(xx,xx_ija) |
- | call align_db(x) | + | xx - matrix in sparse_hashm format |
- | + | xx_ija - matrix in sparse_ija format | |
- | 6. Specify the initial number of elements in the table: | + | |
- | call zero(x,n) | + | Matrix in sparse_hashm form can be rapidly constructed but cannot |
- | + | easily be used. Matrix in sparse_ija form can easily be used but | |
- | where n contains the maximum number of elements | + | cannot be set up directly. Conversion from sparse_hashm to sparse_ija |
- | warning: this subroutine calls subroutine "align" if needed. | + | as provided in module SPARSEM is relatively slow. Subroutine link_hash |
- | + | provides a fast conversion from sparse_hashm to sparse_ija format when xx | |
- | | + | with the same nonzero structure needs to be converted repeatedly. When |
- | 7. Insert elements | + | this routine is called the first time, a link is created that |
+ | points to equivalent locations in xx and xx_ija. During subsequent | ||
+ | calls, it is assumed that the nonzero structure of xx and xx_ija | ||
+ | remains the same, and the conversion is done rapidly by using the link | ||
+ | to update the numerical values only. | ||
- | call insert_el(x,name,val) | ||
- | |||
- | where name is name of field and val its value; the type of val corresponds | ||
- | to the type of field. Insertion is into the current record. However, if | ||
- | the field is an index, the action depends on whether a record with | ||
- | val as an index exists. If it does, that record will become the current | ||
- | record. If not, such a record will be created and it will become the current | ||
- | record. | ||
- | 8. Reposition pointer to a current record | + | Solve_iterm_block |
+ | ----------------- | ||
- | stat=move_rec(x,direction) | + | call solve_iterm_block(xx_ija,xy,sol,i,j,diag,op) |
- | + | ||
- | changes the current record according to value of variable direction: | + | |
- | "next","previous", "first","last". Logical variable stat is .true. if the | + | |
- | operation is successful and .false. otherwise. | + | |
- | + | ||
- | 9. Retrieve elements | + | |
- | stat=find_index(x,val) | + | xx_ija - Matrix in sparse_ija format |
- | | + | xy - (r8) vector of right hand sides |
- | tries to locate an entry with index value val; if successful, stat is | + | sol - (r8) vector of solutions |
- | set to .true. and that entry becomes the current entry; if not successful, | + | i - integer value of first equation to solve |
- | stat is set to .false. | + | j - integer value of last equation to solve |
- | + | diag - (r8) matrix of dimension j-i+1 x j-i+1 | |
+ | op - a character variable containing either 'solve' or "update' | ||
+ | When op='solve', the subroutine solves a block of | ||
+ | equations from i to j, and puts the diagonal part of the matrix xx_ija | ||
+ | into a dense matrix diag. When op='update', the right hand side is | ||
+ | updated for the current block of solutions. The "update' option should | ||
+ | always follow the "solve" option or the solutions will be incorrect. | ||
+ | The need for the 'update' option arises from xx_ija being half-stored. | ||
- | call get_el(x,name,val) | ||
- | |||
- | retrieves value of field name from the current record into variable val. | ||
+ | Other subroutines | ||
+ | ------------------ | ||
- | + | Extra subroutines (undocumented) have been added to enable multiple-trait | |
- | Additional subroutines/functions | + | Gibbs-sampling with single-trait matrices only. See programs gibbs.f90 and |
- | + | gibbs1f90.f90 for details. | |
- | A. Printing | + | |
- | + | ||
- | call print_entry(x,form,un) | + | |
- | + | ||
- | prints the current entry; | + | |
- | optional form specifies format | + | |
- | optional un specifies unit; by default the output goes to the terminal | + | |
- | + | ||
- | + | ||
- | call print_table(x,form,un) | + | |
- | + | ||
- | prints all entries | + | |
- | optional form specifies format | + | |
- | optional un specifies unit; by default the output goes to the | + | |
- | terminal | + | |
- | + | ||
- | + | ||
- | B. Printing database information | + | |
- | + | ||
- | call print_setup(x) | + | |
- | + | ||
- | shows order of fields and their physical location in table x | + | |
- | + | ||
- | + | ||
- | C. Reading and writing | + | |
- | + | ||
- | call write(setup(x,name) | + | |
- | + | ||
- | writes setup of the database (but not entries) to file name | + | |
- | + | ||
- | call write_data(x,name,form) | + | |
- | + | ||
- | writes contents of the database to file name; optional form has values | + | |
- | "character" for character storage (default) or "binary" for binary storage. | + | |
- | + | ||
- | call read_setup(x,name) | + | |
- | + | ||
- | reads setup into an existing or empty database from file name. | + | |
- | + | ||
- | call read_data(x,name,form,nel) | + | |
- | + | ||
- | reads contents of database from file name into x; optional form is | + | |
- | "character" or "binary"; optional nel specifies the maximum number of | + | |
- | elements in the table. If nel is absent, that number is 1.25 times the number | + | |
- | of entries. | + | |
- | + | ||
- | call expand(x,n) | + | |
- | + | ||
- | increases the maximum number of entries twice, or to n if optional | + | |
- | n is present. | + | |
- | + | ||
- | + | ||
- | D. Sorting, clustring, numbering, etc. | + | |
- | + | ||
- | call add_count(x,field,type) | + | |
- | + | ||
- | adds consecutive numbering from 1 to given field; | + | |
- | if optional type='sorted', then entries are numbered by increasing | + | |
- | indixes; otherwise, numbering is by random order. | + | |
- | + | ||
- | subroutine sort_db(x,fields,order) | + | |
- | + | ||
- | sorts x specified by optional field and order | + | |
- | if optional fields are missing, sort by index in asecnding order | + | |
- | + | ||
- | fields is a character variable containing fields to be sorted; fields | + | |
- | are separated by spaces | + | |
- | optional order is 'a' for ascending and 'd' for descending order | + | |
- | + | ||
- | + | ||
- | + | ||
- | ============================= | + | |
- | Selected low-level routines | + | |
- | ============================= | + | |
- | + | ||
- | All routines below operate on 2D integer matrices where entries are stored in | + | |
- | columns, i.e., x(:,i) is one entry | + | |
- | + | ||
- | 1. Hash insertion and retrieval | + | |
- | + | ||
- | i=hashv1(x,ind,mode,nr) | + | |
- | + | ||
- | tries to find such i: x(1:size(ind),i) = ind | + | |
- | if unsuccessful, then: | + | |
- | + | ||
- | if mode=0 (writing): | + | |
- | ind is stored in an empty (all 0) location and i is set to that | + | |
- | location; if there is no space, i is set to -1 | + | |
- | + | ||
- | if mode=1 (retrieval): | + | |
- | i is set to 0 | + | |
- | + | ||
- | + | ||
- | 2. Sorting | + | |
- | + | ||
- | call sort(x,col,n) | + | |
- | + | ||
- | sorts columns x by rows in vector x; if optional n is present, only | + | |
- | first n columns are sorted. | + | |
- | + | ||
- | 3. Clustering | + | |
- | + | ||
- | call clustermat(x,n) | + | |
- | + | ||
- | clusters columns of x with nonxero first-row at the beginning of the matrix; | + | |
- | n is set to the number of nonzero elements | + | |
- | + | ||
- | call | + | |
- | + | ||
- | + |