File doc/history.txt; TRANSIENT V4.3; 3 Nov 2023 (C) 1995-2023 Miroslav Kolar ~~~~~~~~~~~~~~~ | TRANSIENT | ~~~~~~~~~~~~~~~ History: *** November 2023: TRANSIENT V4.3 beta - released No new changes in the working algorithms of TRANSIENT were made, except for minor cosmetic changes. But all the documentation (with the exception of the manual), including interactive help output and comments in the code, was updated to make it consistent with the current workings of TRANSIENT V4.3. Minimally updated manual for now is available only at http://transient.mkolar.org/transien/index.html *** October 2021: TRANSIENT V4.3 - development completed - NR stopping criterion simplified and properly tied to machine precision: CTOL replaced by TOL and TOLC, see nl3_conv.h; compare with doc/nl3_conv.h.V4.2. - tStepMax was removed. - It was replaced in a sense by a new control input parameter maxScale, which sets the upper limit to the ratio of two consecutive time steps. - tStep is now allowed to be changed in PDM's update_Other(). Therefore, concentrations c are now extrapolated to the new time step, and c moved to c_o, only after the call to update_Other(). In previous versions these two actions were done before the call to update_Other(). Thus update_Other() must now use the new c[], whereas in all older versions it had to use c_o[]. - New macro preV4_3 enables to link older PDMs with TRANSIENT V4.3 without the need to re-write update_Other() - see defs.h. - Macro RESETtStepAT99 removed (#define preV4_3 1 also takes care of this). - Macro NO_EXIT_m4 and the associated use of exit code -4 were eliminated. Only a reminder is now printed when an apparent steady state is reached. - Exit code -4 is now used when exceeding attemptMAX(>0) or attemptMaxSTEADY. - Variable highAttempts removed from next tStep algorithm in transien.c. - Updated list of TRANSIENT's exit codes can be found in transien.h at line 60. (In the previous versions V4.x, there was one instance of using exit code -2 inconsistently with the respective versions of this list.) - Output files naming finalized: Output file name postfixes were turned into extensions (a dot was added). Thus the output file names are now: 'Output'.par, 'Output'.stat, 'Output'.diag, 'Output'.tdep, 'Output'.1, 'Output'.2, .... Optionally 'Output'.0. Or all profiles in a single file 'Output'. - 'Output'.par can still be used as the input file for another (re)run, after or without modification. - cDiffMfgroup input control parameter (string) was renamed to cDiffMfExcl (and the number of thus excluded equations to Nexcl) - see lines 247-259 of transien.h and the beginning of nl3_conv.h for brief explanation. *** November 2015: TRANSIENT V4.2 - Output files structure and naming has changed: the prefixes par, diag and stat were moved behind the 'Output' root name; and the par file was split in two: it now contains only all the input parameters, and all the time-dependent output was moved to a new output file 'Output'tdep. As before, the concentration profiles are in the files 'Output'1, 'Output'2, .... Optionally, the initial concentrations can now be recorded in the file 'Output'0. Or concentration profiles for all output time can be in a single file 'Output'. The authors of PDMs are still able to place additional output in any of the above output files. - ATTEMPT_MAX was renamed into attemptMAX (which can now also be <0), and the definition of both macros defining "hardcoded" maximum numbers of attempts was moved to defs.h, and associated with exit code is -3. - (This version was not released to general public.) *** 2012-2014: TRANSIENT V4.1 - CTOL made an input parameter. - Prec control parameter removed. - Added the capability to exclude some equations (unknown variables) when calculating various cresid's, fresid's, and cDiffM. The list of such excluded equations is inputted via the cDiffMfgroup string control input parameter. - strict=1 failures streamlined, reported/counted only when significant. - monitor=4: exit if no convergence achieved in a transient run. - some code cleaning and optimization. - fullPath: memory allocation corrected. - tStepMin removed (no sense to force larger tStep than what's required for convergence; tStep decreasing too much indicates problems to be corrected, or impossibility to solve the given system with TRANSIENT). - CHECK_COND macro to be used to check for any condition anywhere in PDM. - Added checking of correct format of default values of input parameters that are defined in the PDM header file. - "Hardcoded" maximum number of attempts of repeating a time step was added: see macro ATTEMPT_MAX in transien.c. - (This version was not released to general public.) *** October 2009: TRANSIENT V4.0 - signal.c improved. - Piece-wise linear interpolation mode added for cDifMxf (for transient run with strict>-1) - function cDifMxf3() in InOut.c. - linInter() function made available in InOut.c. Related to the above. linInter() can be used for linear interpolation between arbitrary tabulated data (e.g., tabulated functions used read into PDM from external files, for which analytic expressions are not known). - CTOL removed again ("hardcoded" to 1e-7 and 1e-2), and nl3_conv.h almost finalized. - No minimal time step needs to be set for a transient run. - (This version was not released to general public.) *** August 2009: TRANSIENT V3.3 - A new function added to PDM: init_tStep_for_evalf(). It can be used to calculate all values needed in evalf() that are the same in all the NR iteration for the given time step (and thus depend only on time and tStep magnitude). - nl3_conv.h further improved. - (This version was not released to general public.) *** April 2009: TRANSIENT V3.2 - CTOL returned into nl3_conv.h with a somewhat different role. - (This version was not released to general public.) *** February 2006: TRANSIENT V3.11 - The role of negative tStepMax for small times slightly changed. - It was ensured that tStepMin and tStepMax input values are mutually consistent (that they produce a minimum time step bound smaller at all times than the maximum time step bound). - Attempt to recover from a matrix inversion failure in the NL3BAND solver corrected (possibility of an infinite loop removed). - nl3_conv.h algorithm further modified - however, it will need further improvement. *** January 2006: TRANSIENT V3.1 - Termination algorithm for the NR iteration (nl3_conv.h) further improved. - New role added for the non-positive values of tStepMax. *** October 2005: TRANSIENT V3.01 - Discrete LowPrec control parameter replaced by continuous Prec. - tStepMin and tStepMax can be proportional to time elapsed from the start of a simulation. *** June 2005: TRANSIENT V3.0 - New robust convergence algorithm used: TRANSIENT RUN NOW ALMOST NEVER FAILS. Error estimates are given. Precision can be controlled to some extent by varying nIter. Larger nIter gives longer time steps, thus shorter CPU times but smaller precision. - A single consolidated TRANSIENT version, pre-V2.5 (PRE_V2_5_PDM) PDM compatibility no more offered. - WEIGHTS/weights removed. getCresidBase() eliminated. - CTOL and iterMax control parameters also eliminated. - ABSV function offered for PDM for absolute value calculate in accordance with the TRUE_FABS macro. - A descriptive string 2nd argument added to the exitTR() function. - Interactive help on control input parameters improved. *** April 2005: TRANSIENT V2.6p - FTOL and attemptMax control parameters eliminated. - A transient run is now never interrupted if CTOL fails to be satisfied after repeated attempts to decrease the time step. Instead, the best of these attempts (the one with the smallest fresidM/fresidM1 + cresidM/CTOL) is repeated - see nl3_conv.h . - Adaptive time-stepping algorithm has been further improved; highAttempt's role modified. - A single variable, NRiter, introduced for the # of NR iterations, available in all TRANSIENT files, exportable to PDM. During the iteration process it contains the number of the iteration currently performed, which may be sometime useful in evalf(). - "Hardcoded" maximum number of attempts of repeating steady-state calculation was added: see macro attemptMaxSTEADY in transien.c *** November 2002 - February 2005: TRANSIENT V2.6 (intermediate versions V2.6a to V2.6o) - Termination algorithm for the NR iteration has changed: it requires a new PDM function, getCresidBase(). - Number of grid nodes can change during a run. - Number of grid nodes can be as low as one. - Concentration bound values can change during a run. - Some control parameters (monitor, sepProf, nOutOTH) can have additional values. - In transien.c the extrapolation to get a new guess for c is now controlled by the new control input parameter NIG (New Initial Guess extrapolation factor); previous versions of TRANSIENT correspond to NIG=1. - update_Other can return negative values which cause immediate termination of the program (after a call to pr_Other() and pr_Profiles()). - Three new macros NO_X, NO_Y and NR_BOUNDS were added to defs.h: - NO_X and NO_Y are used to simplify the code if the Jacobian blocks X or Y are identically zero. - As default, bounds are now applied in nl3band?.c only at the end of a time step, after NR iteration process had converged. The previous behavior (bounds applied in each NR iteration) can be obtained with the NR_BOUNDS macro set in defs.h. - Adaptive time-stepping algorithm improved (especially the step-increase regime - "constant-step trap" removed; strict=1 is now enforced for arbitrarily small time step; variable highAttempt now keeps track of the history of worst behavior). - Termination codes description in the stat file improved. - Additional TRANSIENT variables automatically exported to the PDM (strict, stat_out). - A few minor errors corrected; dynarr.c simplified, optimized for TRANSIENT. - CHECK_PAR can be safely used anywhere in the PDM module. - nOutOTH<0 case corrected. - The path to the executable (argv[0]) exported to the PDM module (full path usually only when explicitly given on the command line). - New function show_dvector_f() in matrixv.c . - Only non-zero elements in show_matrix() printed. - (Not all V2.6x intermediate versions were released publicly. Only those for x = h, j, k, l and m.) *** August 16, 2002: TRANSIENT V2.54 - transien.h corrected to being able to handle a PDM split into more than one source file; documentation updated correspondingly *** March 15, 2002: TRANSIENT V2.53 - The control input parameter monitor can have an additional value of 3. - New URL: http://transient.mkolar.org/ *** January 16, 2002: TRANSIENT V2.52 - Consolidated "Other" quantities output: * Added the function out_Other(only_Other), similar to out_profiles() introduced in V2.51, to avoid "Other" output duplication. The most obvious use of this would be indirect: * The meaning of the value returned by update_Other() has changed: if nonzero, out_Other (pr_Other) is called by TRANSIENT immediately after update_Other (previously, it meant that pr_Other was called from within update_Other(); demo1.c modified accordingly). (Required modifications in transien.c, transien.h, InOut.c) - tStep made available to PDM; its magnitude can be REDUCED by user in update_Other(), e.g., when a change in boundary conditions has to be made at an exact time. - Termination of TRANSIENT when the concentrations do not change any more (exit code -4) can be switched off be setting macro NO_EXIT_m4 to 1. See defs.h. This is useful e.g. when the boundary conditions will change some time after an (apparent) steady state was reached. - Always resetting c to c_old for all new attempts. - Corrected PDMtemplate. - Updated/corrected manual/documentation. *** August 14, 2001: TRANSIENT V2.51 - New type of lower "bound" added: zero cutoff - set c to zero if below this cutoff value. - The function out_profiles(NewFile) may now be used for output of profiles from the PDM at arbitrary time instants (in addition to the automatic ones determined by tOutInit and tOutMulF). See transien.h for more info. - Handling of switching between different profiles output files for sepProf>0 consolidated. - Demo1 modified (substantially): * improved initialization from a file; * more TRANSIENT validation: a new switch enables to solve a simplified model with only 1 or 2 Cu(I) species for the purpose of analytical comparison. - Demo2: numerical-analytical Laplace transform comparison was improved by adding a check whether a steady state was reached. - Manual updated accordingly. *** June 16, 2001: TRANSIENT V2.50 - Only the new adaptive time-stepping algorithm retained. - No substantial changes in the TRANSIENT engine, only some streamlining of the code. - More transparent interfaces between PDM, NL3BANDV and the TRANSIENT engine. - PDM made simple by moving the INPT_model_param, pr_model, WRONG_model_param and 'cDiffMaxf' (cDifMxf) functions to TRANSIENT): - All model input parameters need to be listed only once in a PDM header file. - TRANSIENT V2.50 can still be made backward compatible with the older PDM format (by enabling PRE_V2_5_PDM in defs.h). - Manual completely updated and revised. - abs(x) optimization, see TRUE_FABS in defs.h. - The values of individual (or of groups of) input parameters can be displayed during interactive start-up. - Demos are in the new PDM format. - Demos are made consistent by using the same mass-balance discretization for all nodes: biggest change: LHS b.c. in demo1. - Improved numerical Laplace transform used to validate TRANSIENT results in demo2. *** October 13, 2000: TRANSIENT V2.04 (V1.54) - strict = 1 corrected, strict > -1 improved. - extrapolating new solution guess for ttStep > Dttout now correct, Scale output for monitor=2 now always correct. - diag file improved. - RESETtStepAT99 case improved. *** August 12, 2000: TRANSIENT V2.03 (V1.53) - Corrections/improvements of the interactive help output made. - Capability to reset time step to the initial value added (do search for RESETtStepAT99 in transien.c for more info (see also a note in defs.h)). - diag'Output' file for steady-state calculations changed. - Time zone patch for the GYGWIN gcc compiler (Windows 95/NT) added to DateTime.c . - CPU time clocking corrected for MS DOS/Windows native compilers. - New makefiles (command procedures) written. - The names of nl3_????.h files shortened to 8 characters. - Concentration-profiles output-format control added to demo1.c. - All demoX subdirectories moved one step lower to a common 'demo' directory. - Up-to-date sample output created, and placed into the newly added 'out' subdirectories of each demoX directory. - Other changes (mainly in #ifdef directives) made throughout the code so that it now works at least with the following compilers/OS: GNU gcc (Cygwin/MS Windows, Linux), DEC C (DEC UNIX and OpenVMS), HP-UX C, and in MS Windows also with MS Visual C++, Borland Turbo C++ and MS (Quick) C. No problems are expected with other ANSI C compatible compilers. (Thanks to P. Martinet, martinet@ce.kth.se for reporting a problem for GNU gcc). - MANUAL REVISED AND UPDATED! - More 'readme' files added. *** Feb. 18, 2000: TRANSIENT V2.02 (V1.52) - Exit status -4 reserved for the rare situation when a steady state is reached in a transient calculation; associated minor change in the time-stepping algorithm. *** Dec. 3, 1999: TRANSIENT V2.01 (V1.51) - Transformation of tEnd corrected (using ttEnd). - The format of the diagnostic diag'Output' file changed. *** Sept. 16, 1999: TRANSIENT V2.0 (V1.5) - A new, simpler adaptive time-stepping algorithm introduced that is rather different from the previous one, yet at least as efficient. It does not use any more a history stored in the bits of an integer, although a different version of history is still being used. - For the sake of comparison, the older adaptive time-stepping algorithm is still being retained in the code, and one can choice between the two algorithms at the compilation time as explained at the beginning. In this way all the subsequent improvements are identical for both series of TRANSIENT's versions, V1.5x and V2.0x, such that the difference between V1.5x and V2.0x remains the same (time-stepping algorithm and number of strict values) for all x. *** Sept. 16, 1999: TRANSIENT V1.5 - Two new output files introduced: diag'Output' containing tStep, cDiffM, and # of iter for most time steps; stat'Output' containing CPU times and cumulative #'s of time steps, etc. Examples of the output files can be found in subdirectory demo1 of the distribution package. See the file demo1/readme.too.please. - update_Other() now returns an integer value (int update_Other(void)). Normally it is a 0. Only if pr_Other() is called from inside update_Other(), e.g. when a certain condition requires additional output, update_Other() must return a nonzero value. - exitTR(sts) function introduced. It should be used instead of exit() when terminating TRANSIENT from a PDM. Use exit status sts<=100 and different from -3,-2 and -1 (see transien.h). sts=0 indicates successful termination. This exit status will be written out at the end of the stat'Output' file. - If iterMax is positive, runband() gives up prematurely ONLY if the relative c-residuals start to grow (cf. nl3_conv.h in which the parabolic extrapolation test, introduced in V1.4b1, is commented out). - Randomizing a new estimate between subsequent attempts not done any more in a transient calculation, only in a steady-state calculation. *** March 9, 1999: TRANSIENT V1.4b1 - In V1.3, the N-R termination algorithm in runband() was still not good enough. The new solution is contained in the new file nl3_conv.h . Convergence is now achieved if cresid < CTOL OR fresidM < FTOL*fresidM1, where fresidM1 is fresidM from the 1st iteration. - iterMax is now set through the new control input parameter of the same name. Its absolute value is the maximum allowed number of N-R iterations in runband(). If iterMax is negative, runband() terminates only if convergence is achieved, or if |iterMax| N-R iterations are made. If iterMax is positive, runband() gives up prematurely if after the 5th iteration the relative c-residuals start to grow OR if their parabolic extrapolation does not fall below CTOL. iterMax < 0 (and very large) should be used for steady state calculations, and iterMax > 0 for the transient calculations (see demo1). iterMax=0 sets such suitable default values for the two cases automatically (see defs.h). - All the bound-checking code that is essentially the same for both nl3bandv.c and nl3band1.c moved to four more new nl3_*.h include files. - The weight (w_k, wei) capability is now completely switched off (not compiled) as a default. To switch it on, edit file defs.h , and set WEIGHTS to 1 in defs.h. (The weight argument was retained in runband() at all times, and is unused if WEIGHTS is disabled (and in nl3band1.c as before)). - Similarly, to enable the old monitor=3 functionality, set PDMtrace to 1 in defs.h . *** May 29, 1998: TRANSIENT V1.31 - Minor change in the N-R stopping criterion involving FTOL . *** Feb. 11, 1997: TRANSIENT V1.3 - Minor changes in nl3band?.c (return values). - Changes in the adaptive time-stepping algorithm. *** July 14, 1996: TRANSIENT V1.2 - Major change in the adaptive time-stepping algorithm: the new algorithm uses recent history of time-step changes stored in the bits of a single integer variable. - Randomize() enforces automatically the bounds if they are set. - Bounds changed from float to double . *** Dec. 28, 1995: TRANSIENT V1.1 - Input/output functions moved from transien.c to a new file InOut.c . - cDiffMaxf(t) moved to a PDM (to be custom coded by the user). - Control input parameter memFactor removed. - Control input parameter interBest changed into nIter. - Constant maximum number of N-R iterations, iterMax, (linked to nIter) used in the runband() N-R termination algorithm (instead of a variable maximum linked to an average number of N-R iterations). - MACHINEZERO removed from lufacv.c . - Three more examples (demonstration PDM) added. *** Oct. 1995: First publicly released version of TRANSIENT - Two more types of lower and upper bounds (position-dependent, memory-saving) introduced. - Minor changes in adaptive time-stepping algorithm. *** July 1995: First attempt at TRANSIENT - Newton-Raphson (N-R) scheme to solve the discretized nonlinear PDE essentially finalized: nl3bandv.c, lufacv.c, matinvv.c and matrixv.c "vectorized". - The structure of the main TRANSIENT function main() in transien.c set. - Only constant lower and upper bounds of unknown functions (concentrations) available. - Adaptive time-stepping algorithm not yet very effective. - A single demonstration problem definition module (PDM) provided.