Overview

This document describes the work plan for the ADMB Public Domain Open Source Project based on the joint NCEAS - ADMB Foundation Proposal to the Gordon and Betty Moore Foundation.

Deliverables

1. admb-project.org website -Done (see Oct 2008 milestone)
   
2. ADMB binaries and libraries -Done (Released ADMB 9.0 see http://admb-project.org/downloads)
   
3. ADMB Version Control -Done (See Dec 2008 milestone)
   
4. ADMB Testing Systems -Done
   
5. ADMB Documentation -Done
   
6. ADMB Source -Done (Dec 31, 2009)
   

Proposal Milestones

Currently supported versions of the libraries freely available from admb-project.org. This milestone was postponed from the original July date because of delays in acquiring the software.

Temporary version control and preliminary testing systems in place on existing server. Source code available to the "core development team" on restricted server.

documentation, libraries and source code available to interested users for "beta" testing.

ADMB software suite including documentation, libraries and source code freely available on a public website.

Milestones Tasks

Currently supported versions of the libraries freely available from admb-project.org.
[X] plone server with apache front end installed at http://admb-project.nceas.ucsb.edu/ - Completed May 30, 2008
[X] admb-project.org hosted at NCEAS - Completed July 3, 2008
[X] Implemented Initial ADMB Public Binary Release plan. Completed November 7, 2008.

December 2008:
A. Provisional version control in place.
[X] Completed October 31, 2008.

B. Implement integrated multiplatform build and test system
[X] Buildbot system in place. Completed December 2008.

C. Source code available to the "core development team" on restricted server.
[X] Restricted access Subversion system in place.  Completed December 2008.

A. documentation available to interested users for "beta" testing.
[X] Implemented Accessing Beta Documentation: Interested Users plan.

B. libraries available to interested users for "beta" testing.
[X] Implemented Accessing Beta Binary Libraries: Interested Users plan.

C. source code available to interested users for "beta" testing.
[X] Implemented Accessing Beta Source Code: Interested Users plan.

A. ADMB software suite documentation freely available on a public website.
[X] Implemented Public ADMB Documentation Release plan.

B. ADMB software suite libraries freely available on a public website.
[X] Implemented Public Binary Libraries Release plan.

C. ADMB software suite source code freely available on a public website.
[X] Implemented Public Open Source Code Release plan.

Initial ADMB Public Binary Release

Tasks

[X] Add new license information to header and source files as appropriate.
[X] Manually compiled ADMB binaries and libraries for supported OS and compiler combination.
[X] Packaged the ADMB distribution folder using file name conventions.  Release as version 9.0.x.
[X] Make http://www.admb-project.org/downloads/ folder public readable.
[X] Uploaded binaries to http://code.google.com/p/admb-project/downloads with references in http://www.admb-project.org/downloads/ .

Provisional Version Control

Tasks

[X] Subversion control server installed at PFRP

[X] Procedures established for SSH access to Subversion server.

[X] Procedure documentation on how to access using TortoiseSVN for Windows. (For developers only)

[X] Procedure documentation on how to access using command line svn for unix. (For developers only)

Component Tasks

[X] Install CentOS 4 on server.
[X] Install Subversion Server (SVN).
[X] Import initial ADMB source code to SVN. -Completed Oct. 26, 2008
[X] Make SVN server accessible.
[X] Add users account and assign them to the group admb-project
[X] Document procedures for Subversion access under Linux and Windows.

Supported Operating Systems and Compilers

[X] Linux and GNU g++ version 3.4.x and 4.1.x for 32 bit processors

[X] Linux and GNU g++ version 3.4.x and 4.1.x for 64 bit processors (Done for gcc-4.3)

[X] Windows and Mingw with GNU g++ version 3.4.5

[X] Windows and Visual Studio version 2003 (VC 7)

[X] Windows and Borland 5.5.x

[X] Mac OSX

Building and Testing of ADMB

Objectives

1. Ensure that code modification committed to the Subversion server is compiled into candidate distributions.
2. Ensure that the modified code does not "break" legacy applications.

Tasks

1. Build and test VMware virtual server for Microsoft Windows XP (32 bit) with Visual Studio, Borland, and MinGw
2. Build and test VMware virtual server for Centos 5 (32 bit) and Gnu g++.
3. Build and test VMware virtual server for Centos 5 (64 bit)and Gnu g++.
4. ADMB examples test case added  to each of the build and server servers.
5. Implement a Buildbot instance to control all builds and tests in virtual servers
   

F. Baseline Test Cases

The purpose of baseline testing is to ensure that any changes to the code does not affect previous outputs. 

A revision in from the version control will be chosen as the baseline source (i.e. revision 0).  It gets compiled and run with the test case, then the results are saved.  Next, a branch is compiled and run with the test case, then the results of the baseline is compared with the results of the branch.  If the final minimum likelihood value and the final maximum gradient values are the same, then the test case has PASSed, else it FAILs and the branch cannot be merged with the main trunk.

As well as checking the results, the test case will check for time to complete for for baseline and branch executable.

The baseline test cases below will be use to determine if that happens.

• Use example tpl files from http://otter-rsch.ca/examples.htm .

1. Rick Methot's Stock Synthesis models 
2. MULTIFAN-CL
3. Anders Nielsen's models
4. Mark Maunder's models
5. John Sibert's movemod model

G. Unit Testing

Unit testing is used in Test Driven Development to ensure that a function is works as intended.  It can also be use to ensure that any code changes will not result in a FAIL for a unit test.  If any of the unit test FAIL, the branch cannot be merged with the trunk.

Below are some unit tests that will be used.

1. Movemod 25 Unit Tests

H. Daily Builds

The trunk will be built daily regardless of whether the previous build was a PASS or FAIL.  If it FAILs an email will be sent to all developers warning them about the error.

Distribution Folder

Distribution Folder Contents

configure (unix)

• for source distribution
  

• autoconf script for creating unix Makefile 

Makefile.vc

• for source distribution
  

• for nmake

README

• For outline, see <http://www.tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#README>. 

INSTALL

• See tasks (Creating INSTALL documentation)

LICENSE

• See License section. 

src folder

• contains entire ADMB source and header files

lib folder

• contains compiled libraries for binary distribution
  
• libado.a
• libadt.a
• df1b2stub.a 
  
• libdf1b2s.a
• libadmod.a  
  
• libads.a 
  
• libdf1b2o.a
  

bin folder

• contains compiled executables and scripts for binary distribution
  
• tpl2cpp

include folder

• contains processed compiled headers files for binary distribution

Distribution File Naming Conventions

Source distributions

• admb-{version}.zip
  

Binary Distributions 

• admb-{version}-{operating system}-{compiler}.zip
  
• admb-{version}-{operating system}-{compiler}.exe (Self extracting windows distribution)

• admb-{version}-{operating system}-{compiler}.tar.gz (Unix)

• admb-{version}-{operating system}-{compiler}.rpm (Redhat based Linux distributions)
• admb-{version}-{operating system}-{compiler}bin.sh (Self extracting unix distribution)

Operating Systems Tags

{operating system name}{32 or 64 bit}

• linux32

• linux64

• win32

• win64
• mingw32
  

Compiler Tags

{compiler name}{version of compiler}

• gcc3.4.5

• gcc3.4.5

• bcc5.5.1 (Borland)
  

• vc7 (Microsoft)
  

• cl64-6.0 (Microsoft)
  

Version Tag

{major}.{minor}.{revision}

revision is the total number of revisions from the version control system.

Examples

• admb-8.0.0.zip

• admb-8.0.0-linux32-gcc3.4.6.zip

References

License - New BSD

Copyright (c)  2008, Regents of the University of California
All rights reserved.

References

New BSD License (Open Source Initiative)

BSD Licenses (Wikipedia)

Coding Standards

Purpose

Define the coding standard for ADMB.

Overview

A coding standard improves readability, understandability and maintainability by ensuring the code is formatted the same in all source and header files.

ADMB C/C++ Style and Coding Standards (Proposed) 

For C/C++ style and coding standards, use the existing books below.

Supplemental Coding Standard

These rules will be used override the above coding standards which conflict with current style or are just not the preferred style.

ADMB TPL Style and Coding Standard (Proposed)

These rules will define the ADMB template (TPL) style and coding standard.  Although ADMB will allow the TPL file to be style and organized according to the users preferences, it is much better to have a general style and coding standard for the TPL.  Below are some of those rules.

1. All C/C++ codes should follow the "ADMB C/C++ Style and Coding Standards".
2. All indents should be four(4) spaces.

Tools

Below are tools can automate C/C++ styling.  Although they are handy tools, the process final output should still be checked and manually verified that it does not break any coding standard rules.

Artistic Style <http://astyle.sourceforge.net/>

• Command line C/C++ code styler

References

Other C/C++ Coding Standards

• http://geosoft.no/development/cppstyle.html
• http://www.research.att.com/~bs/bs_faq2.html
• http://www.possibility.com/Cpp/CppCodingStandard.html
• http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html