Differences

This shows you the differences between two versions of the page.

--- gibbs [2012/11/15 14:45] – created ignacy
+++ gibbs [2012/11/15 14:46] – ignacy
@@ Line 1: / Line 1: @@
-Module HASH_DB
+ Module Gibbs
+Ignacy Misztal, University of Georgia
+/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.
-. declare a table
+Subroutine link_hash was inspired by Urs Schnyder, ETH, Switzerland.
-    	type (db_hash)::x
-   where x is a database
-, Initialize
-	call init(x)
+Module Gibbs
+============
-. 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.
-. 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.
-. 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
-. 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
-. 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.
-. 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.
-. 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
-. 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
-. 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.
-. 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