Modelling astronomical adaptive optics - I. The software package caos. The software package caos (code for adaptive optics systems) described in this paper is a software ensemble of modules designed for end-to-end simulation of generic astronomical adaptive optics (AO) systems, including a complete atmosphere turbulence model, sodium laser-guide star upward and downward propagation, observed object definition, Shack–Hartmann and novel pyramid wave-front sensors detailed modelling, wave-front reconstruction and subsequent time-filtering tools, and wave-front correction via different kinds of correctors; but also image formation, Fizeau interferometry, coronagraphy, etc. Consequently, it is more likely to be used as a tool dedicated to detailed optical astronomy studies than as an instrument simulator, as it is based on a wide range of unprecedented physical modelling. After a brief but global description, with particular emphasis on the most interesting physical modelling features, its use is illustrated through a chosen application, namely the question concerning the opportunity of having a tip–tilt-dedicated sensor in a 8-m class telescope pyramid-based AO system.