API documentation with executable examples

The rise of component-based software development has created an urgent need for effective application program interface (API) documentation. Experience has shown that it is hard to create precise and readable documentation. Prose documentation can provide a good overview but lacks precision. Formal methods offer precision but the resulting documentation is expensive to develop. Worse, few developers have the skill or inclination to read formal documentation. We present a pragmatic solution to the problem of API documentation. We augment the prose documentation with executable test cases, including expected outputs, and use the prose plus the test cases as the documentation. With appropriate tool support, the test cases are easy to develop and read. Such test cases constitute a completely formal, albeit partial, specification of input/output behavior. Equally important, consistency between code and documentation is demonstrated by running the test cases. This approach provides an attractive bridge between formal and informal documentation. We also present a tool that supports compact and readable test cases; and generation of test drivers and documentation, and illustrate the approach with detailed case studies. (C) 2002 Elsevier Science Inc. All rights reserved.

A case study in specification and implementation testing

Achieving consistency between a specification and its implementation is an important part of software development In previous work, we have presented a method and tool support for testing a formal specification using animation and then verifying an implementation of that specification. The method is based on a testgraph, which provides a partial model of the application under test. The testgraph is used in combination with an animator to generate test sequences for testing the formal specification. The same testgraph is used during testing to execute those same sequences on the implementation and to ensure that the implementation conforms to the specification. So far, the method and its tool support have been applied to software components that can be accessed through an application programmer interface (API). In this paper, we use an industrially-based case study to discuss the problems associated with applying the method to a software system with a graphical user interface (GUI). In particular, the lack of a standardised interface, as well as controllability and observability problems, make it difficult to automate the testing of the implementation. The method can still be applied, but the amount of testing that can be carried on the implementation is limited by the manual effort involved.

SimuMap: a computational system for spatial modelling

The paper presents a computational system based upon formal principles to run spatial models for environmental processes. The simulator is named SimuMap because it is typically used to simulate spatial processes over a mapped representation of terrain. A model is formally represented in SimuMap as a set of coupled sub-models. The paper considers the situation where spatial processes operate at different time levels, but are still integrated. An example of such a situation commonly occurs in watershed hydrology where overland flow and stream channel flow have very different flow rates but are highly related as they are subject to the same terrain runoff processes. SimuMap is able to run a network of sub-models that express different time-space derivatives for water flow processes. Sub-models may be coded generically with a map algebra programming language that uses a surface data model. To address the problem of differing time levels in simulation, the paper: (i) reviews general approaches for numerical solvers, (ii) considers the constraints that need to be enforced to use more adaptive time steps in discrete time specified simulations, and (iii) scaling transfer rates in equations that use different time bases for time-space derivatives. A multistep scheme is proposed for SimuMap. This is presented along with a description of its visual programming interface, its modelling formalisms and future plans. (C) 2003 Elsevier Ltd. All rights reserved.

Programming internet based DAI applications in Qu-Prolog

This paper presents the unique collection of additional features of Qu-Prolog, a variant of the Al programming language Prolog, and illustrates how they can be used for implementing DAI applications. By this we mean applications comprising communicating information servers, expert systems, or agents, with sophisticated reasoning capabilities and internal concurrency. Such an application exploits the key features of Qu-Prolog: support for the programming of sound non-clausal inference systems, multi-threading, and high level inter-thread message communication between Qu-Prolog query threads anywhere on the internet. The inter-thread communication uses email style symbolic names for threads, allowing easy construction of distributed applications using public names for threads. How threads react to received messages is specified by a disjunction of reaction rules which the thread periodically executes. A communications API allows smooth integration of components written in C, which to Qu-Prolog, look like remote query threads.

Optimal release strategies for biological control agents: an application of stochastic dynamic programming to population management

1. Establishing biological control agents in the field is a major step in any classical biocontrol programme, yet there are few general guidelines to help the practitioner decide what factors might enhance the establishment of such agents. 2. A stochastic dynamic programming (SDP) approach, linked to a metapopulation model, was used to find optimal release strategies (number and size of releases), given constraints on time and the number of biocontrol agents available. By modelling within a decision-making framework we derived rules of thumb that will enable biocontrol workers to choose between management options, depending on the current state of the system. 3. When there are few well-established sites, making a few large releases is the optimal strategy. For other states of the system, the optimal strategy ranges from a few large releases, through a mixed strategy (a variety of release sizes), to many small releases, as the probability of establishment of smaller inocula increases. 4. Given that the probability of establishment is rarely a known entity, we also strongly recommend a mixed strategy in the early stages of a release programme, to accelerate learning and improve the chances of finding the optimal approach.

Generalized quasi mode theory of macroscopic canonical quantization in cavity quantum electrodynamics and quantum optics II. Application to reflection and refraction at a dielectric interface

The generalization of the quasi mode theory of macroscopic quantization in quantum optics and cavity QED presented in the previous paper, is applied to provide a fully quantum theoretic derivation of the laws of reflection and refraction at a boundary. The quasi mode picture of this process involves the annihilation of a photon travelling in the incident region quasi mode, and the subsequent creation of a photon in either the incident region or transmitted region quasi modes. The derivation of the laws of reflection and refraction is achieved through the dual application of the quasi mode theory and a quantum scattering theory based on the Heisenberg picture. Formal expressions from scattering theory are given for the reflection and transmission coefficients. The behaviour of the intensity for a localized one photon wave packet coming in at time minus infinity from the incident direction is examined and it is shown that at time plus infinity, the light intensity is only significant where the classical laws of reflection and refraction predict. The occurrence of both refraction and reflection is dependent upon the quasi mode theory coupling constants between incident and transmitted region quasi modes being nonzero, and it is seen that the contributions to such coupling constants come from the overlap of the mode functions in the boundary layer region, as might be expected from a microscopic theory.

Rough Notes on Programming AVR Microcontrollers in C

These notes follow on from the material that you studied in CSSE1000 Introduction to Computer Systems. There you studied details of logic gates, binary numbers and instruction set architectures using the Atmel AVR microcontroller family as an example. In your present course (METR2800 Team Project I), you need to get on to designing and building an application which will include such a microcontroller. These notes focus on programming an AVR microcontroller in C and provide a number of example programs to illustrate the use of some of the AVR peripheral devices.

Analysis of the gate capacitance measurement technique and its application for the evaluation of hot-carrier degradation in submicrometer MOSFETs

The use of gate-to-drain capacitance (C-gd) measurement as a tool to characterize hot-carrier-induced charge centers in submicron n- and p-MOSFET's has been reviewed and demonstrated. By analyzing the change in C-gd measured at room and cryogenic temperature before and after high gate-to-drain transverse field (high field) and maximum substrate current (I-bmax) stress, it is concluded that the degradation was found to be mostly due to trapping of majority carriers and generation of interface states. These interface states were found to be acceptor states at top half of band gap for n-MOSFETs and donor states at bottom half of band gap for p-MOSFETs. In general, hot electrons are more likely to be trapped in gate oxide as compared to hot holes while the presence of hot holes generates more interface states. Also, we have demonstrated a new method for extracting the spatial distribution of oxide trapped charge, Q(ot), through gate-to-substrate capacitance (C-gb) measurement. This method is simple to implement and does not require additional information from simulation or detailed knowledge of the device's structure. (C) 2001 Elsevier Science Ltd. All rights reserved.

The use of stochastic dynamic programming in optimal landscape reconstruction for metapopulations

A decision theory framework can be a powerful technique to derive optimal management decisions for endangered species. We built a spatially realistic stochastic metapopulation model for the Mount Lofty Ranges Southern Emu-wren (Stipiturus malachurus intermedius), a critically endangered Australian bird. Using diserete-time Markov,chains to describe the dynamics of a metapopulation and stochastic dynamic programming (SDP) to find optimal solutions, we evaluated the following different management decisions: enlarging existing patches, linking patches via corridors, and creating a new patch. This is the first application of SDP to optimal landscape reconstruction and one of the few times that landscape reconstruction dynamics have been integrated with population dynamics. SDP is a powerful tool that has advantages over standard Monte Carlo simulation methods because it can give the exact optimal strategy for every landscape configuration (combination of patch areas and presence of corridors) and pattern of metapopulation occupancy, as well as a trajectory of strategies. It is useful when a sequence of management actions can be performed over a given time horizon, as is the case for many endangered species recovery programs, where only fixed amounts of resources are available in each time step. However, it is generally limited by computational constraints to rather small networks of patches. The model shows that optimal metapopulation, management decisions depend greatly on the current state of the metapopulation,. and there is no strategy that is universally the best. The extinction probability over 30 yr for the optimal state-dependent management actions is 50-80% better than no management, whereas the best fixed state-independent sets of strategies are only 30% better than no management. This highlights the advantages of using a decision theory tool to investigate conservation strategies for metapopulations. It is clear from these results that the sequence of management actions is critical, and this can only be effectively derived from stochastic dynamic programming. The model illustrates the underlying difficulty in determining simple rules of thumb for the sequence of management actions for a metapopulation. This use of a decision theory framework extends the capacity of population viability analysis (PVA) to manage threatened species.

Edge-to-edge matching and its applications - Part I. Application to the simple HCP/BCC system

The edge-to-edge matching crystallographic model has been used to predict all the orientation relationships (OR) between crystals that have simple hexagonal close packed (HCP) and body-centered cubic (BCC) structures. Using the critical values for the interatomic spacing misfit along the matching directions and the cl-value mismatch between matching planes, the model predicted all the four common ORs, namely the Burgers OR, the Potter OR, the Pitsch-Schrader OR and the Rong Dunlop OR, together with the corresponding habit planes. Taking the c(H)/a(H) and a(H)/a(B) ratios as variables, where H and B denote the HCP and BCC structures respectively, the model also predicted the relationship between these variables and the four ORs. These predictions are perfectly consistent with the published experimental results. As was the case in the FCC/BCC system, the edge-to-edge matching model has been shown to be a powerful tool for predicting the crystallographic features of diffusion-controlled phase transformations. (C) 2004 Acta Materialia Inc. Published by Elsevier Ltd. All rights reserved.

Edge-to-edge matching and its applications - Part II. Application to Mg-Al, Mg-Y and Mg-Mn alloys

A model for the crystallography and morphology of diffusion-controlled phase transformations - edge-to-edge matching - has been used to predict the orientation relationships (OR) and habit planes of precipitates Mg17Al12 in Mg-Al alloy, Mg24Y5 in Mg-Y alloy and alpha-Mn in Mg-Mn alloy. Based on the crystal structures and lattice parameters only, the model predicts that the possible ORs between Mg17Al12 and Mg matrix are the near Burgers OR, the Potter OR, the Gjonnes-Ostmoe OR and the Crawley OR. In the Mg-Y alloy, the OR between Mg24Y5 precipitates and the Mg matrix is predicted to be the Burgers OR only. The model also predicts that there are no reproducible ORs between alpha-Mn and Mg in the Mg-Mn alloy. Combining the edge-to-edge matching model and W. Zhang's Deltag approach, the habit plane and side facets of the precipitate for each OR can be determined. All the predicted ORs and the corresponding habit planes in Mg-Al and Mg-Y alloys agree very well with the experimental results. (C) 2004 Acta Materialia Inc. Published by Elsevier Ltd. All rights reserved.

Tool support for executable documentation of Java class hierarchies

While object-oriented programming offers great solutions for today's software developers, this success has created difficult problems in class documentation and testing. In Java, two tools provide assistance: Javadoc allows class interface documentation to be embedded as code comments and JUnit supports unit testing by providing assert constructs and a test framework. This paper describes JUnitDoc, an integration of Javadoc and JUnit, which provides better support for class documentation and testing. With JUnitDoc, test cases are embedded in Javadoc comments and used as both examples for documentation and test cases for quality assurance. JUnitDoc extracts the test cases for use in HTML files serving as class documentation and in JUnit drivers for class testing. To address the difficult problem of testing inheritance hierarchies, JUnitDoc provides a novel solution in the form of a parallel test hierarchy. A small controlled experiment compares the readability of JUnitDoc documentation to formal documentation written in Object-Z. Copyright (c) 2005 John Wiley & Sons, Ltd.