Evolution of thermally pulsing asymptotic giant branch stars - I. The COLIBRI code

We present the COLIBRI code for computing the evolution of stars along the thermally pulsing asymptotic giant branch (TP-AGB) phase. Compared to purely synthetic TP-AGB codes, COLIBRI relaxes a significant part of their analytic formalism in favour of a detailed physics applied to a complete envelope model, in which the stellar structure equations are integrated from the atmosphere down to the bottom of the hydrogen-burning shell. This allows us to predict self-consistently: (i) the effective temperature, and more generally the convective envelope and atmosphere structures, correctly coupled to the changes in the surface chemical abundances and gas opacities; (ii) the conditions under which sphericity effects may significantly affect the atmospheres of giant stars; (iii) the core mass-luminosity relation and its possible breakdown due to the occurrence of hot-bottom burning (HBB) in the most massive AGB stars, by taking properly into account the nuclear energy generation in the H-burning shell and in the deepest layers of the convective envelope; (iv) the HBB nucleosynthesis via the solution of a complete nuclear network (including the pp chains, and the CNO, NeNa and MgAl cycles) coupled to a diffusive description of mixing, suitable to follow also the synthesis of Li-7 via the Cameron-Fowler beryllium transport mechanism; (v) the intershell abundances left by each thermal pulse via the solution of a complete nuclear network applied to a simple model of the pulse-driven convective zone (PDCZ); (vi) the onset and quenching of the third dredge-up, with a temperature criterion that is applied, at each thermal pulse, to the result of envelope integrations at the stage of the post-flash luminosity peak. At the same time, colibri pioneers new techniques in the treatment of the physics of stellar interiors, not yet adopted in full TP-AGB models. It is the first evolutionary code ever to use accurate on-the-fly computation of the equation of state (EoS) for roughly 800 atoms, ions, molecules and of the Rosseland mean opacities throughout the atmosphere and the deep envelope. This ensures a complete consistency, step by step, of both EoS and opacity with the evolution of the chemical abundances caused by the third dredge-up and HBB. Another distinguishing aspect of colibri is its high computational speed, which allows to generate complete grids of TP-AGB models in just a few hours. This feature is absolutely necessary for calibrating the many uncertain parameters and processes that characterize the TP-AGB phase. We illustrate the many unique features of colibri by means of detailed evolutionary tracks computed for several choices of model parameters, including initial star masses, chemical abundances, nuclear reaction rates, efficiency of the third dredge-up, overshooting at the base of the PDCZ, etc. Future papers in this series will deal with the calibration of all these and other parameters using observational data of AGB stars in the Galaxy and in nearby systems, a step that is of paramount importance for producing reliable stellar population synthesis models of galaxies up to high redshift.