**** Note 24/10/17 ******** This version had an inconsistency between the script and Fortran code for fgong-amdl.d which caused a truncation of the model below r/R = 1, with the default parameters. The script and Fortran code have now been replaced. ----------------------------------------------------------------------------- Installation guide for adiabatic pulsations and models package ============================================================== The present version v0_3 is a beta release updated to be consistent with the version in evolpack_ast_111216 on 22/2/16. The present distribution includes three test models and corresponding input files, described below. The documentation is not fully updated. For up-to-date documentation see also the source codes, in particular adipls/adipls.c.d.f. Note on problem with gfortran: Compiling readml.n.d.f with gfortran -O2 apparently gives rise to problems in the final code. For this reason readml.d.f is explicly compiled with no optimization in the adipls directory. This has no effect on the run time. ============================================================================ Previous release notes: The present version v0_1 is a beta release, motivated by the Leiden workshop on red giants in July/August 2012. Thus it has not yet been completely tested and documented. Comments will of course be very welcome, as a help towards a more complete release. The most important change has been in the programme (redistrb.c.d) resetting the mesh for the oscillation calculation. Here the goal has been to define a universal scheme that provides reasonable results for any stellar type. This certainly required further tests. However, some care has been made to ensure reasonable results for red-giant models. There is also a new option (nsig = 10) in the frequency scan, based on the asymptotic properties of the frequency spectrum. ------------------------------------------------------------------------------ Notes on version adipack.c This version was an update released in June 2010. Relative to the previous version adipack.n several aspects of the pulsation code were updated, including: - The use of fourth-order integration in the shooting method, flagged by mdintg = 5. - The use of the Takata (2006b) scheme for labelling dipolar modes, flagged by irsord = 20. - The possibility of computing first-order rotational effects on frequencies and eigenfunctions, following Soufi et al. (1998). This involves a new block of input parameters, rot, and is flagged by irotsl = 1. This option still needs testing. - The option of producing (generally discontinuous) solutions at arbitrary frequency, flagged by itmax = 0 and nfmode > 10. This also includes the option for output of solutions during scan in frequency, with iscan > 1, if nfmode > 0. Further details are provided in the general documentation on the code (in the following DOCUMENTATION), in the file adiab.prg.v0_1.pdf in the notes subdirectory. In addition, updates have been made in a new version of the code (redistrb.c.d) changing the mesh in the model. These are detailed in operations.pdf, also in the notes subdirectory. ============================================================================= Note on compatibility: ..................... In general it is believed that the present version is compatible with earlier versions. In particular, the new version of the pulsation code should accept earlier input files; however, there are obviously new options. The new version of the mesh code requires new input files, provided in the examples with the distribution. ----------------------------------------------------------------------------- As templates for the use of the code, examples are provided for three different types of models: A model of the present Suns, a subgiant model and a red-giant model. The properties and use of the models are discussed below, after the installation guide. ----------------------------------------------------------------------------- The package consists of eight files: This README file. The file adipack.v0_3.tar.gz, containing the source of the code and various auxiliary codes and notes, as well as the sample stellar models. The initial installation consists in the following steps: 1) Transfer the compressed tar file to the directory where you wish to place the code and models. Then, uncompress and un-tar them. To uncompress the file, type: gunzip adipack.v0_3.tar (NOTE: do NOT append the '.gz' to the filename for the command) To un-tar the files, type: tar xvf adipack.v0_3.tar adipack.v0_3.tar will generate the following directories: - adipls: contains basic pulsation code - adiajobs: contains auxiliary programmes - bin: contains executables - gensr: contains general subroutines required by programmes - idl_pro: contains IDL procedures for reading relevant data files - notes: contains plain TeX and PDF and/or ps files of notes on the programmes and data. - test_cases: contains the models for testing and the relevant input files etc. In the following I refer to the directory where the unpack was performed as . Also, reference to directories is often given relative to . 2) It may be necessary to edit the makefiles in the directories adipls, adiajobs, adiajobs/sr and gensr, to reset the name of the command to run Fortran on the system and/or the flags for this command. The current version uses the Portland compiler, with the command "pgf77", and flag "-O2". 3) Compile and link the programmes by the following steps: cd /adipls ; make cd /adiajobs ; make See below for possible incompatibilities or warnings. 4) Add the directory /bin to the command path (usually set in your .cshrc file). 5) Add the line setenv aprgdir in the .cshrc file (at a point where it is invoked every time a csh command is called). 6) Print the documentation in the directory notes, from the following files: - adiab.prg.v0_3.pdf (from adiab.prg.v0_3.tex): documentation on the adiabatic pulsation code (described as DOCUMENTATION above) - operation.pdf (from operation.tex): more general notes on the programmes and models provided. Note that these are not up to date, but still defines the basic structure of the package and input files, etc. Information in the present README file should be used in preference. - file-format.pdf (from file-format.tex): notes on data structure for models in the form of an extensive set of variables, in an ASCII file (the so-called FGONG format). - frequency_format.pdf: notes on oscillation output, in the so-called ASCII fobs format. Test cases: ========== These are provided in the directory /test_cases. The somewhat unwieldy file names are the ones used in my own installation. It is preferably to keep them for easy cross reference. The file names have the following form: . The relevant file types are: - fgong: Extensive set of model variables, in ASCII form. - amdl: Variables specifically used for the oscillation calculation (see DOCUMENTATION); famdl provides an ASCII version of the files (see below) - agsm: Detailed binary output from the oscillation calculation (see DOCUMENTATION) - fobs: Selected output from the oscillation calculation, in ASCII Note that the ASCII files typically contains a header, marked by '#' in the first column. This should be skipped before reading the files. Three model cases are provided: - l9bi.d.202c: A model of the present Sun, largely corresponding to Model S of Christensen-Dalsgaard et al (1996; Science, 272, 1286) but using updated opacity and and equation of state tables. - 0130.X72.Z2.1.265: A 1.3 Msun subgiant model, from Jiang & C-D (2014; MNRAS 444, 3622). The model was used for Fig. 16 of Hekker & C-D (2017; AAR, 25, 1) - AST_100_R07_RGB_solarcal: A 1 Msun, 7 Rsun red-giant model. Part of the Aarhus red giant challenge (Silva Aguirre et al., in preparation, (Christensen-Dalsgaard et al., in preparation) To run the test for the solar model do: 7) Set binary amdl file with the command form-amdl.d 2 famdl.l9bi.d.202c amdl.l9bi.d.202c 8) Transfer the model to a mesh for oscillation calculations with redistrb.cy.d redistrb.sun.prxt3.in > ttt.red.sun.out 9) Calculate oscillations with adipls.c.d adipls.sun.in > ttt.adi.sun.out 10) Set ASCII frequency file with set-fobs.d 16 l9bi.d.202c.prxt3 11) Compare these frequencies with those that I computed with freqdif.d compfreq.sun.in The relative frequency differences are in the 4th column of the file dfr.sun. 12) The test for the subgiant model is very similar: form-amdl.d 2 famdl.0130.X72.Z2.1.265 amdl.0130.X72.Z2.1.265 redistrb.cy.d redistrb.sg.prxt4.in > ttt.red.sg.out adipls.c.d adipls.sg.in > ttt.adi.sg.out set-fobs.d 16 0130.X72.Z2.1.265.prxt4 freqdif.d compfreq.sg.in with output in dfr.sg 13) The test for the red-giant model is very similar: form-amdl.d 2 famdl.AST_100_R07_RGB_solarcal amdl.AST_100_R07_RGB_solarcal redistrb.cy.d redistrb.rg.prxt5.in > ttt.red.rg.out adipls.c.d adipls.rg.in > ttt.adi.rg.out set-fobs.d 16 AST_100_R07_RGB_solarcal.prxt5 freqdif.d compfreq.rg.in with output in dfr.sg Note that for the red-giant model the computations involve a very large number of g modes and hence are quite time-consuming. 14) At this point you are ready to start using the package. Please send me an E-mail (to jcd@phys.au.dk) indicating that you have installed the package, and providing your E-mail (and other) addresses, as well as a few details on the system on which the package is being run. This will enable me to notify you of bugs or updates. A note on the mesh for oscillation calculations ----------------------------------------------- In many cases the modes of interest are of high radial order, with a specific structure reflecting the properties of the stellar model considered. This is in particular the case for red-giant models where thousands of nodes can be found in the inner, g-mode-dominated region. Thus setting up of the mesh is a critical part of the calculation. This is handled by the commands redistrb.cy.d above, which specifically takes into account the asymptotic properties of the modes. The names of the input files (e.g. redistrb.sg.prxt4.in) contain a part (prxt) which also becomes a trailer in the output file names. Here 'prxt' in a somewhat convoluted way labels the ongoing development of the scheme for the mesh redistribution, and (in this case 4) indicates the number N of mesh points. For the cases considered here prxt3: N = 4802 prxt4: N = 9602 prxt5: N = 19202 In general N is doubled when is increased by one. Compiler inconsistencies: ------------------------- I have found a single point where different compilers may give problems. In ofiles.f and ofiles.c.f, both in the directory gensr, there is a call to the system clock to set up scratch output files. The present version assumes the use of the Portland compiler and has the command itime = secnds(0.d0) Using the gnu compilers g77 or gfortran, the command call system_clock(itime) should apparently be used instead. These commands follow a line containing 'c Set scratch file name from system time.' I have no systematic experience with other compilers. The directory gensr contains version ofiles_g77.f and ofiles.c_g77.f of the routines that should be appropriate for the gnu compilers. Thus if you have problems you can try the commands (in .../gensr) cp ofiles_g77.f ofiles.f cp ofiles.c_g77.f ofiles.c.f Compiler warnings: ----------------- It is possible that compilation will produce warnings on some systems. These should generally be unimportant. A particular cause of warnings is the fact that I occasionally dimension arrays passed as arguments into subroutines as, e.g., dimension a(1) in the subroutine, even if the true dimension of the array is bigger than one. This will cause a warning if the compiler attempts a check of array bounds. I have yet to come across a system where this causes problems. Please let me know if you suspect that it is a problem in the results of computations on your system. Disclaimer: ---------- There is no guarantee that the package will work as intended, although it has been used previously, in a less well-documented form, by several people. I am willing to consider problems, or suggestions for improvements, but given my schedule I cannot promise to act quickly on them. I shall attempt to correct errors in the package, as they are pointed out to me, and post revised versions. This file (and the Web pages) will contain a record of such updates, with a few details of the problems that have been fixed. Below is a list of problems that have been seen of different installations, but appear to be of a sufficiently special nature that they should not be corrected in the general release: my inclination would be to leave features that are convenient on most machines, even if they cause problems in selected cases. Acknowledgements: ---------------- I am very grateful to Alan Irwin, Helmut Schlattl, Frank Hill and Dennis Stello for their help in testing earlier versions of the package, as well as to Gulnur Dogan for installing the Takata labelling of dipolar modes in the package. Dennis Stello and Anwesh Mazumdar also provided helpful comments on the documentation, and Jakob Mosumgaard and Andreas Joergensen helped finding a serious error in the code converting fgong files to amdl files. Aarhus, 17 October 2018 -------------------------------------------------------------------------