(1) The real-basin version of the Miami Isopycnic Coordinate Ocean Model (originally called ATLMIX but now referred to as MICOM) contains a Kraus- Turner mixed layer, accomodates 2 independent thermodynamic variables (T,S), and supports variable bathymetry and irregular coastlines. The model is documented in a paper entitled "Salinity-driven thermocline transients in a wind- and thermohaline-forced isopycnic coordinate model of the North Atlantic" by Bleck/Rooth/Hu/Smith. (JPO 1992, Vol.22, p.1486-1505). The diapycnic mixing scheme, which didn't make it into that paper, is documented in a LaTeX file called DIAPYC.TEX. Recent improvements to the mixed-layer detrainment algorithm are written up in MXLAYR.TEX. (2) Model versions 1.x are snapshots taken at various stages of model development as bugs were discovered and loose ends were tied up. In versions 1.x, temperature and salinity are advected and diffused independently throughout the domain. Model versions 2.x treat temperature as a diagnostic variable in isopycnic layers (but not in the mixed layer). This cuts advection time in half and eliminates the need for a coordinate maintenance ("cabbeling") algorithm. Detrainment is patterned after Appendix E in BRHS. Versions 2.2 and higher include diapycnal mixing of buoyancy and salinity, with temperature in isopycnic layers inferred from the equation of state. Starting with version 2.3, the thermal forcing functions "T-hat" and Bowen ratio used in older versions are replaced by actual atmospheric temperature and humidity. (3) Horizontal array dimensions are uniformly set to (IDM,JDM), even though most fields do not make use of the full allotted space due to horizontal staggering considerations (Arakawa C grid). Specifially, there are only (IDM-1)x(JDM-1) mass points, (IDM)x(JDM-1) U-velocity points and (IDM-1)x (JDM) V-velocity points. U and V points addressed as (I,J) are actually located at grid locations (I-1/2,J) and (I,J-1/2), respectively, relative to mass point (I,J). Vorticity and Coriolis parameter addressed as (I,J) are at (I-1/2,J-1/2). The distribution of water and land within the rectangle spanned by (IDM-1,JDM-1) is defined by the DEPTHS array. Zero means land. (4) The two time slots required for all prognostic and some diagnostic variables are incorporated into the third (vertical) array dimension. The vertical grid index KM [as in TEMP(I,J,KM)] stands for model level K, time level M (as in "mid" time). Letter N [as in TEMP(I,J,KN)] indicates the "new" and "old" time level. (5) We recommend that the code be compiled with all variables preset to indefinite. On Cray machines, this is accomplished by compiling with the "-ei" option and loading with the "-f indef" option. Grid values whose use in the various finite-difference operators is anticipated (and only those) are set to zero during model initialization. This provides some safeguard against contamination by "spurious" land data in case of unforeseen complexities in coastline shape. (6) If compiled with the "-ei" compiler option, model version 1 will crash upon encountering single-grid-interval coastal inlets or channels. Versions 2.1 - 2.3 contain code (16 lines starting with statement label 16 in subroutine BIGRID.F) to detect and fill in such features in the DEPTHS array. Version 2.4 does away with this restriction, i.e., allows single-point inlets (provided the above-mentioned 16 lines in BIGRID.F are removed). Single-point promontories and islands are okay. (7) There are no restrictions regarding the number of islands, but the parameter MS must be adjusted to the maximum number of "interruptions" of any grid row or column by land. Specifically, MS-1 interruptions are allowed. Interruptions in diagonal direction (of interest to the Poisson solver) are governed by the parameter MSD. If MS and/or MSD are chosen too small, the program will stop in one of the routines BIGRID,INDXI,INDXJ during the initialization phase with an error message. (8) Loops extending over the horizontal grid domain are triply nested to suspend arithmetic operations wherever a grid row crosses land. Innermost loop bounds are stored in arrays with names like IFP,ILP,IFU,ILU,JFV,JLV where the letters F and L stand for first and last grid point in a segment (segments are defined as contiguous 1-dimensional sets of "water" points), the letters P,U,V,Q indicate whether the loop goes over mass (P), velocity (U,V), or vorticity (Q) points, and the letters I,J indicate whether the inner loop index is I or J. The middle loop extends over the number of segments in the grid row defined in the outer loop; this number is given in arrays named ISP,JSV, etc. (9) The model does not use a rigid lid; instead, it advances the barotropic and baroclinic solutions using a split-explicit scheme. The barotropic streamfunction is therefore computed for diagnostic purposes alone. If the iteration count in the Poisson solver is set too low for the solution to converge, the model run itself will not be affected. No attempt is presently made to determine the correct streamfunction value along island boundaries. We suggest the following quick fix to prevent the Poisson solver from setting the streamfunction to zero along island boundaries (which it presently does): (a) Change the name of the GINDEX Common block in Subr. POISND to GINDX1. (b) Make a copy of Subr. BIGRID (named, say, BIGRD1) in which the name of the GINDEX common block is changed to GINDX1. (c) Make a version of the DEPTHS array (named DEPTH1) in which you change zero depth values indicating islands into small nonzero numbers in the 0.001 .... 0.01 m range. (d) In the initialization part of the model, insert the statement CALL BIGRD1(DEPTH1) after CALL BIGRID(DEPTHS). The solution produced by the above procedure, which amounts to covering islands with a thin sheet of water, should be sufficiently accurate for most display purposes. It is implemented in our model output processor MICOMPROC (see MICOMPROC.TAR in this subdirectory). (10) Numerous diagnostic messages in the code are presently commented out by the letters CDIAG but can be activated as needed. Many of these messages refer to a specific grid point (ITEST,JTEST) which the user must define in a DATA statement in BLKDAT.F. (11) The model equations are solved on a regular grid overlying a Mercator projection of the earth's surface; this is to assure isotropy in grid resolution. Provisions for rotating the poles 90 degrees, i.e., defining a true meridian as the "equator" of the map projection, are made. Subroutine NEWOLD/OLDNEW gives the location of (rotated) model grid points in relation to a lat/lon grid and vice versa. However, interpolation routines for translating fields of variables back and forth are the user's responsibility. (12) Versions 1.3 and up read 2-degree North Atlantic basin depths from an ASCII file named DEPTH.51x56 and 7 sets of monthly forcing fields. Forcing fields for version 2.3 and up are in ASCII files named FORCING.TAU_X, FORCING.TAU_Y, FORCING.WINDSPD, FORCING.RADFLX, FORCING.PRECIP, FORCING .Q_STAR, and FORCING.T_STAR. These form a complete set of boundary conditions that can be used to test-run the model. Initial conditions -- based on zonally averaged Levitus climatology -- are generated internally by routine POFLAT.F. A batch submit file for machines running under Unix is given in DEMORUN_2.6. Results from a 10-day test run on a 32-bit workstation (DEC-5000) are in DEMOOUT_2.6. (13) During the upgrade of model version 1.3 to 2.0, a bug was introduced into the mixed-layer buoyancy calculation [BUOYFL(I,J)=...] which was not discovered until 17 October 1992. The mod file 1PT3_TO_2PT0.MODS was corrected on that day; this led to a set of altered source files for versions 2.0 - 2.2 which are marked with the suffix "BUGFIX". (14) A FORTRAN-90 version of MICOM level 2.6 suitable for running on a Connection Machine (CM-5) is kept as a tar file in subdirectory bleck/ massive. This particular version is based on 127 x 127 horizontal points with a mesh size of 0.9 deg. longitude. Monthly forcing functions and a 127 x 127 point Atlantic depth array are provided in the same subdirectory. (15) Starting with version 2.4, the previously monolithic 2500-line main program has been split into approximately 10 subroutines. The fragmented code, which runs 10% faster (probably because compilers can optimize the fragments more easily), requires the UNIX 'tar' utility for unpacking. The most recent version of the code is found in MICOM_2.6_TAR. It is being updated occasionally, mainly for cosmetic reasons. Users are advised to use the UNIX 'diff' utility to keep track of differences between their version and the latest version of MICOM. (16) The major differences between versions 2.5 and 2.4 are as follows: (a) mixed-layer dissipation is formulated according to Gaspar; (b) the convective-adjustment algorithm in CONVEC.F entrains both momentum and mass into the mixed layer (it used to entrain only mass); (c) the old MXLAYR.F routine has been split into one routine (called THERMF.F) which handles thermal bounday forcing and a new MXLAYR.F dealing exclusively with mixed-layer entrainment/detrainment. (d) time smoothing of u,v fields is done in layer thickness-weighted fashion (analogous to the smoothing of mass field variables in TSADVC.F); (e) the "physics" routines CONVEC,THERMF,MXLAYR are now called after the "dynamics" routines to remove inconsistencies in the definition and treatment of "old" and "new" fields. (17) The major differences between versions 2.6 and 2.5 are as follows: (a) mixed-layer detrainment driven by fresh-water (as opposed to heat) input has been made easier by extending the traditional temperature redistribution concept in the fossil mixed layer to joint salinity/ temperature redistribution; (b) diagnosis of the barotropic streamfunction has been eliminated; (c) Newtonian relaxation boundary conditions can be chosen for the mass field at the northern and southern domain boundary. (18) Setting horizontal array dimensions IDM,JDM to powers of 2 may cause slowdowns on some computers due to cache or memory bank conflicts. Since the scope of do-loops in the model is defined in terms of the variables II, JJ, model performance can be optimized without changing the physical basin configuration by increasing IDM and/or JDM without changing II,JJ. (17) One by-product of ongoing efforts to globalize MICOM has been the creation of a cyclic channel version. The code is stored under the name 'micomchan.tar'. Differences to the standard closed-boundary version have been kept to a minimum. In view of its planned use in a global model, the code allows unrestricted placement of geographic obstacles relative to the cyclic boundary. The parameter setup may change in the near future as we search for interesting test cases of channel flow around topography. No efforts have been made (yet) to create a cyclic boundary version of the Poisson solver POISND.F. (19) A version of CNUITY.F in which the conventional Laplacian thickness (interface) smoothing algorithm is replaced by a biharmonic scheme is available upon request. No efforts have been made to switch from Laplacian to biharmonic lateral momentum mixing, mainly because of the computational complexity of enforcing free-slip/no-slip lateral boundary conditions along submerged sidewalls. (20) Efforts to suppress a computational mode leading to occasional amplification of a 2-grid-interval seesaw pattern in the velocity and thickness field are unsuccessful at this point. Since this mode does not seem to exist in the older BOXMIX version based on the B grid, we plan to write a B-grid version of MICOM. (21) Users have recently reported that the present bottom stress treatment -- i.e., the assumption of a linear bottom stress profile based on the average flow speed in the lowest 10 m -- is unable to retard the flow in ultra-thin, fast-moving layers occasionally developing along steep bottom slopes. Modifications of the stress profile to take care of this problem (which is believed to be a side effect of PV conservation in near-massless layers) are presently being tested. Rainer Bleck (rbleck@rsmas.miami.edu) 09 December 1994