Versioning Recommendations

NEEDS follows the Compact Model Coalition recommendations for assigning version numbers to models as described below.

For new models, where a version control mechanism has not been established, it is recommended that the version control number take the following form:

< version# >.< subversion# >.< revision# >

where the numbers in angle brackets (< >) are integers.

The model version number is used to identify a major model formulation change that requires a new model parameter set (i.e., is not backward compatible with the previous release), and is increased when such a major model formulation change has been implemented.

The model subversion number is used to identify a minor model formulation change which does not require a new model parameter set (i.e. is backward compatible with the previous release). The model subversion number is increased:

• Whenever minor model formulation changes are made which do not require new model parameter sets, and is reset whenever the model version number is changed (i.e., when a major model formulation change is made).
  
• To capture minor formulation simplifications such as those to increase run time efficiency.

It is important to note that a model change may necessitate the use of additional model parameters, but if the model formulation and default values for the additional model parameters are chosen carefully, model parameter sets from the previous release will yield results that match those of the previous release. In this case, only the model subversion number needs to be changed since backward compatibility with the previous release is maintained. Models with the same version number and different subversion numbers are backward compatible with the exception of minor formulation simplification to enhance e.g., run time efficiency.

The model revision number is used to identify different implementations of the same set of model equations. The following are examples where different implementations may arise:

• Numerical measures to improve convergence
  
• Restructuring of source code to increase maintainability, readability, etc.
  
• Small changes in the model such as changing constants used in smoothing functions or changing clipping values of model parameters
  
• Bug fixes which do not change the model formulation
  

The model revision number is increased whenever such changes occur, and is reset when the model subversion number is changed.

Model developers are strongly encouraged to use conditionals (e.g., if (subversion == 2) then…, or if (revision < = 4) then …) in their source code to capture model implementation changes that require changes to the model revision number or the model subversion number. In this way, a single source code file or set of source code files can cover multiple model releases, making it easier for simulator vendors to implement a new model release in their simulator. It is not expected that changes to the model version number can be handled with source code conditionals.

It is also recommended that a model parameter, “version”, be included in the model parameter set with the following specification:

version=< version# >.< subversion# >< revision# >

For example BSIM4.6.5 will have a parameter version=4.65.