mf__equilrc.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{p 4 4 2}
Thus programmers who want to use equilibration and obtain the best speed
possible examine the matrix and based on that perform (1) no equilibration,
(2) row equilibration, (3) column equilibration, or (4) both.  They then write
four branches in their subsequent code to handle each case efficiently.

{p 4 4 2}
In terms of determining whether equilibration is necessary, measures of the
row and column condition can be obtained from
{cmd:min(}{it:r}{cmd:)}/{cmd:max(}{it:r}{cmd:)} and
{cmd:min(}{it:c}{cmd:)}/{cmd:max(}{it:c}{cmd:)}, where {it:r} and {it:c} are
the scaling factors (reciprocals of the row and column maximums).  If
those measures are near 1 (LAPACK uses >= .1), then equilibration can be
skipped.

{p 4 4 2}
There is also the issue of the overall scale of the matrix.  In theory, the
overall scale should not matter, but many packages set tolerances in absolute
rather than relative terms, and so overall scale does matter.  In most of
Mata's other functions, relative scales are used, but
provisions are made so that you can specify tolerances in relative or absolute
terms.  In any case, LAPACK uses the rule that equilibration is necessary if
the matrix is too small (its maximum value is less than
{cmd:epsilon(}100{cmd:)}, approximately 2.220453-14) or too large (greater
than 1/{cmd:epsilon(}100{cmd:)}, approximately 4.504e+13).

{p 4 4 2}
To summarize,

{p 8 12 2}
    1.  In statistical applications, we believe that equilibration 
        burns too much computer time and adds too much code complexity
        for the extra accuracy it delivers.  This is a judgment 
        call, and it is worth noting that we would probably 
        recommend the use of equilibration were it computationally free.

{p 8 12 2}
    2.  If you are going to use equilibration, there is nothing
        numerically wrong with simply equilibrating matrices in all cases,
        including those in which equilibration is not necessary.  
        The advantages of this is that you will gain the precision to be 
        had from equilibration while still keeping your code reasonably 
        simple.

{p 8 12 2}
    3.  If you wish to minimize execution time, then you want to perform 
        the minimum amount of equilibration possible and write code to 
        deal efficiently with each case:  (1) no equilibration, (2) row
        equilibration, (3) column equilibration, and (4) row and column
        equilibration.  The defaults used by LAPACK and incorporated in Mata's
        {cmd:_perhapsequil*()} routines are

{p 12 16 2}
	    a.   Perform row equilibration if 
                 {cmd:min(}{it:r}{cmd:)}/{cmd:max(}{it:r}{cmd:)}<.1, 
		 or if 
                 {cmd:min(abs(}{it:A}{cmd:))}<{cmd:epsilon(}100{cmd:)}, 
                 or if 
                 {cmd:min(abs(}{it:A}{cmd:))}>1/{cmd:epsilon(}100{cmd:)}. 

{p 12 16 2}
            b.   After performing row equilibration, perform column 
                 equilibration if 
                 {cmd:min(}{it:c}{cmd:)}/{cmd:max(}{it:c}{cmd:)}<.1, 
                 where {it:c} is calculated on {it:r}{cmd:*}{it:A}, 
                 the row-equilibrated {it:A}, if row equilibration was
                 performed.


{title:The _equil*() family of functions}

{p 4 4 2}
The {cmd:_equil*()} family of functions performs equilibration:

{p 8 27 2}
{cmd:_equilrc(}{it:A}{cmd:,} {it:r}{cmd:,} {it:c}{cmd:)}{bind:  }performs
    row equilibration followed by column equilibration; it returns in {it:r}
    and in {it:c} the row and column scaling factors, and it modifies {it:A}
    to be the fully equilibrated matrix {it:r}{cmd::*}{it:A}{cmd::*}{it:c}.

{p 8 27 2}
{cmd:_equilr(}{it:A}{cmd:,} {it:r}{cmd:)}{bind:      }performs
    row equilibration only; it returns in {it:r} the row scaling factors, 
    and it modifies {it:A} to be the row equilibrated matrix 
    {it:r}{cmd::*}{it:A}.

{p 8 27 2}
{cmd:_equilc(}{it:A}{cmd:,} {it:c}{cmd:)}{bind:      }performs
    column equilibration only; it returns in {it:c} the row scaling factors, 
    and it modifies {it:A} to be the row equilibrated matrix 
    {it:A}{cmd::*}{it:c}.

{p 4 4 2}
Here is code to solve {it:Ax} = {it:b} using the fully equilibrated form, 
which damages {it:A} in the process:

		{cmd:_equilrc(A, r, c)}
		{cmd:x = c:*lusolve(A, r:*b)}


{title:The _perhapsequil*() family of functions}

{p 4 4 2}
The {cmd:_perhapsequil*()} family of functions mirrors {cmd:_equil*()}, 
except that these functions apply the rules mentioned above for whether 
equilibration is necessary.

{p 4 4 2}
Here is code to solve {it:Ax} = {it:b}, which may damage {it:A} in the
process:

		{cmd}result = _perhapsequilrc(A, r, c)
		if (result==0)          x = lusolve(A, b)
		else if (result==1)     x = lusolve(A, r:*b)
		else if (result==2)     x = c:*lusolve(A, b)
		else if (result==3)     x = c:*lusolve(A, r:*b){txt}

{p 4 4 2}
As a matter of fact, the {cmd:_perhapsequil*()} family returns a vector of 
1s when equilibration is not performed, so you could code 

		{cmd}(void) _perhapsequilrc(A, r, c)
		x = c:*lusolve(A, r:*b){txt}

{p 4 4 2}
but that would be inefficient.


{title:rowscalefactors() and colscalefactors()}

{p 4 4 2}
{cmd:rowscalefactors(}{it:A}{cmd:)} and 
{cmd:colscalefactors(}{it:A}{cmd:)}
return the scale factors (reciprocals of row and column maximums)
to perform row and column equilibration.  These functions are used 
by the other functions above and are provided for those who wish to 
write the own equilibration routines.  


{title:Conformability}

    {cmd:_equilrc(}{it:A}{cmd:,} {it:r}{cmd:,} {it:c}{cmd:)}:
	{it:input:}
		{it:A}:  {it:m x n}
	{it:output:}
		{it:A}:  {it:m x n}
		{it:r}:  {it:m x} 1
		{it:c}:  1 {it:x n}

    {cmd:_equilr(}{it:A}{cmd:,} {it:r}{cmd:)}:
	{it:input:}
		{it:A}:  {it:m x n}
	{it:output:}
		{it:A}:  {it:m x n}
		{it:r}:  {it:m x} 1

    {cmd:_equilc(}{it:A}{cmd:,} {it:c}{cmd:)}:
	{it:input:}
		{it:A}:  {it:m x n}
	{it:output:}
		{it:A}:  {it:m x n}
		{it:c}:  1 {it:x n}

    {cmd:_perhapsequilrc(}{it:A}{cmd:,} {it:r}{cmd:,} {it:c}{cmd:)}:
	{it:input:}
		{it:A}:  {it:m x n}
	{it:output:}
		{it:A}:  {it:m x n}  (unmodified if {it:result}==0)
		{it:r}:  {it:m x} 1
		{it:c}:  1 {it:x n}
	   {it:result}:  1 {it:x} 1

    {cmd:_perhapsequilr(}{it:A}{cmd:,} {it:r}{cmd:)}:
	{it:input:}
		{it:A}:  {it:m x n}
	{it:output:}
		{it:A}:  {it:m x n}  (unmodified if {it:result}==0)
		{it:r}:  {it:m x} 1
	   {it:result}:  1 {it:x} 1

    {cmd:_perhapsequilc(}{it:A}{cmd:,} {it:c}{cmd:)}:
	{it:input:}
		{it:A}:  {it:m x n}
	{it:output:}
		{it:A}:  {it:m x n}  (unmodified if {it:result}==0)
		{it:c}:  1 {it:x n}
	   {it:result}:  1 {it:x} 1

    {cmd:rowscalefactors(}{it:A}{cmd:)}:
		{it:A}:  {it:m x n}
	   {it:result}:  {it:m x} 1

    {cmd:colscalefactors(}{it:A}{cmd:)}:
		{it:A}:  {it:m x n}
	   {it:result}:  1 {it:x n}


{title:Diagnostics}


{p 4 4 2}
Scale factors used and returned by all functions are calculated by 
{cmd:rowscalefactors(}{it:A}{cmd:)} and
{cmd:colscalefactors(}{it:A}{cmd:)}.
The functions are defined as
{cmd:1:/rowmaxabs(}{it:A}{cmd:)}
and 
{cmd:1:/colmaxabs(}{it:A}{cmd:)}, with missing values changed to 1.
Thus rows or columns that contain missing or are entirely zero are
defined to have scale factors of 1.

{p 4 4 2}
Equilibration functions do not equilibrate rows or columns that contain 
missing or all zeros.

{p 4 4 2}
The {cmd:_equil*()} functions convert {it:A} to an array if {it:A} was 
a view.  The Stata dataset is not changed.

{p 4 4 2}
The {cmd:_perhapsequil*()} functions convert {it:A} to an array if {it:A} was 
a view and returned is nonzero.  The Stata dataset is not changed.


{title:Source code}

{p 4 4 2}
{view _equilrc.mata, adopath asis:_equilrc.mata},
{view _equilr.mata, adopath asis:_equilr.mata},
{view _equilc.mata, adopath asis:_equilc.mata},
{view _perhapsequilrc.mata, adopath asis:_perhapsequilrc.mata},
{view _perhapsequilr.mata, adopath asis:_perhapsequilr.mata},
{view _perhapsequilc.mata, adopath asis:_perhapsequilc.mata},
{view rowscalefactors.mata, adopath asis:rowscalefactors.mata},
{view colscalefactors.mata, adopath asis:colscalefactors.mata}


{title:Also see}

{p 4 13 2}
Manual:  {hi:[M-5] _equilrc()}

{p 4 13 2}
Online:  help for 
{bf:{help m4_matrix:[M-4] matrix}}
{p_end}