{"id":17872801,"url":"https://github.com/hombit/freddi","last_synced_at":"2025-07-20T02:31:50.639Z","repository":{"id":11622705,"uuid":"48480871","full_name":"hombit/freddi","owner":"hombit","description":"Compute FRED light curves of LMXBs outbursts","archived":false,"fork":false,"pushed_at":"2025-02-12T07:52:27.000Z","size":2279,"stargazers_count":8,"open_issues_count":8,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-02T01:37:05.374Z","etag":null,"topics":["accretion-disks","astrophysics","fred","lmxb","science","x-ray-binaries"],"latest_commit_sha":null,"homepage":"http://freddi.homb.it","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hombit.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-23T09:10:25.000Z","updated_at":"2025-01-11T13:58:43.000Z","dependencies_parsed_at":"2024-01-15T17:36:29.278Z","dependency_job_id":"e526ed20-493a-43bc-a8dd-969fac7a5c2c","html_url":"https://github.com/hombit/freddi","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/hombit/freddi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hombit%2Ffreddi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hombit%2Ffreddi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hombit%2Ffreddi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hombit%2Ffreddi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hombit","download_url":"https://codeload.github.com/hombit/freddi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hombit%2Ffreddi/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266058467,"owners_count":23870155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accretion-disks","astrophysics","fred","lmxb","science","x-ray-binaries"],"created_at":"2024-10-28T10:47:28.521Z","updated_at":"2025-07-20T02:31:50.612Z","avatar_url":"https://github.com/hombit.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `Freddi` — compute FRED-like light curves of LMXB\n\n## Table of contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Physical Background](#physical-background) \n- [Accretion disk wind](#accretion-disk-wind) \n- [Development guide](#development-guide)\n- [Questions and comments](#questions-and-comments)\n- [License](#license)\n- [BibTex](#bibtex)\n\n## Overview\n\nThe code solves 1-D evolution equation of Shakura-Sunyaev accretion alpha-disk\naround black hole or neutron star. The code is developed to simulate fast-rise \nexponential-decay (FRED) light curves of low mass X-ray binaries (LMXBs). \nIt has been first presented in the paper “Determination of the turbulent \nparameter in the accretion disks: effects of self-irradiation in 4U 1543-47 \nduring the 2002 outburst” by Lipunova \u0026 Malanchev (2017)\n[2017MNRAS.468.4735L](http://adsabs.harvard.edu/abs/2017MNRAS.468.4735L). \nCurrently, the code can take into account self-irradiation of the disc, \nwinds from the disc surface, disc-magnetosphere interactions. The related \npapers are Avakyan et al (2021) [2021AstL...47..377A](http://adsabs.harvard.edu/abs/2021AstL...47..377A)\nand Lipunova et al (2021)\n[2021arXiv211008076L](http://adsabs.harvard.edu/abs/2021arXiv211008076L).\n\n`Freddi` is written on C++ and available as a couple of binary executables and\na Python module.\n\nNote that the original `Freddi` version 1 introduced in Lipunova \u0026 Malanchev (2017)\n[2017MNRAS.468.4735L](http://adsabs.harvard.edu/abs/2017MNRAS.468.4735L) is still\navailable in the [`v1` git branch](https://github.com/hombit/freddi/tree/v1).\n\n## Installation\n\n### Executables\n\n`Freddi` is represented by two binary executables: the black hole version\n`freddi` and the neutron star version `freddi-ns`.\n\n#### Docker\n\nIf you are familiar with [Docker](http://docker.com) then you can use\npre-compiled binaries inside Docker container:\n```sh\ndocker run -v $(pwd):/data --rm -ti ghcr.io/hombit/freddi freddi -d/data\ndocker run -v $(pwd):/data --rm -ti ghcr.io/hombit/freddi freddi-ns --Bx=1e8 -d/data\n```\n\n#### Build from source\n\n`Freddi` has following build dependencies:\n\n- [Boost](http://www.boost.org/) 1.57+\n- [CMake](https://cmake.org) with a back-end build system like Make or Ninja\n- C++ compiler with C++17 support, e.g. `gcc` version 8+ or `clang` 5+\n\nGet requirements on Debian based systems (e.g. Ubuntu):\n```sh\napt-get install g++ cmake libboost-all-dev\n```\n\nOn Red-Hat based systems (e.g. Fedora):\n```sh\ndnf install gcc-c++ cmake boost-devel\n```\n\nOn macOS via [Homebrew](https://brew.sh):\n```sh\nbrew install cmake boost\n```\n\nGet `Freddi` source code and compile it:\n```sh\ngit clone https://github.com/hombit/freddi\ncd freddi\nmkdir cmake-build\ncd cmake-build\ncmake .. # -DSTATIC_LINKING=TRUE\ncmake --build .\n```\n\nUncomment `-DSTATIC_LINKING=TRUE` to link against static Boost libraries\n\nNow you should have both `freddi` and `freddi-ns` executables in the build\ndirectory. You can install these binaries and the default configuration\nfile `freddi.ini` by running\n```sh\ncmake --install . --prefix=PREFIX # replace with preferable location\n```\n\n`Freddi` is known to be built on Linux and macOS.\n\n### Python\n\n[![PyPI version](https://badge.fury.io/py/freddi.svg)](https://badge.fury.io/py/freddi)\n\nPython 2 isn't supported, use Python 3 instead.\n\n`Freddi` pre-compiled x86-64 Linux packages for several Python versions\nare available on \u003chttps://pypi.org/project/freddi/\u003e and can be used as is,\nwhile for other configurations you should have C++ compiler and Boost\nlibraries in your system before running this command:\n\n```sh\n# Please upgrade your pip\npython3 -m pip install -U pip\n# Depending on your Python setup, you need or need not --user flag\npython3 -m pip install --user freddi\n```\n\n[`astropy`](https://astropy.org) is an optional requirement which must be\ninstalled to use dimensional input via `Freddi.from_astropy`\n\n## Usage\n\n### Executables\n\n`Freddi` runs from the command line with inline options and/or with configuration \nfiles. `Freddi` outputs file `freddi.dat` with distribution of various physical values \nover time. If `--fulldata` is specified then files `freddi_%d.dat` for each time step \nare created in the same directory with snapshot radial distributions. These data-files \ncontain whitespace-separated data columns with header lines starting\nwith `#` symbol. You can set another prefix instead of `freddi` with `--prefix`\noption and change the output directory with `--dir` option. If you choose the\nDocker way and would like to specify the directory, then avoid using `--dir`\noption and just replace `` \"`pwd`\" `` with some local path (for more details see\n[Docker documentation](https://docs.docker.com/engine/tutorials/dockervolumes)).\n\n#### \u003ca name=\"usage-executables-options\"\u003e Options\n\nThe full list of command line options is viewed with `--help` option. Default\nvalues are given in brackets.\n\n```sh\n./freddi --help\n```\n\n\u003cdetails\u003e\u003csummary\u003eexpand\u003c/summary\u003e\n\n```\nFreddi: numerical calculation of accretion disk evolution:\n\nGeneral options::\n -h [ --help ] Produce help message\n \n --config arg Set filepath for additional configuration \n file. There is no need to declare a \n configuration file with the default name \n freddi.ini\n \n --prefix arg (=freddi) Set prefix for output filenames. Output file\n with distribution of parameters over time is\n PREFIX.dat\n \n --stdout Output temporal distribution to stdout \n instead of PREFIX.dat file\n \n -d [ --dir ] arg (=.) Choose the directory to write output files. \n It should exist\n \n --precision arg (=12) Number of digits to print into output files\n \n --tempsparsity arg (=1) Output every k-th time moment\n \n --fulldata Output files PREFIX_%d.dat with radial \n structure for every time step. Default is to\n output only PREFIX.dat with global disk \n parameters for every time step\n \n\nBasic binary and disk parameters\n:\n -a [ --alpha ] arg Alpha parameter of Shakura-Sunyaev model\n \n --alphacold arg Alpha parameter of cold disk, currently it \n is used only for the critical maximum value \n of the surface density of the cold disk \n Sigma_minus (Lasota et al., 2008, A\u0026A 486, \n 523) and the cooling front velocity (Ludwig \n et al., 1994, A\u0026A 290, 473), see \n --Qirr2Qvishot. Default value is --alpha \n divided by ten\n \n -M [ --Mx ] arg Mass of the central object, in the units of \n solar masses\n \n --kerr arg (=0) Dimensionless Kerr parameter of the black \n hole\n \n --Mopt arg Mass of the optical star, in units of solar \n masses\n \n --rochelobefill arg (=1) Dimensionless factor describing a size of \n the optical star. Polar radius of the star \n is rochelobefill * (polar radius of critical\n Roche lobe)\n \n --Topt arg (=0) Effective temperature of the optical star, \n in units of Kelvins\n \n -P [ --period ] arg Orbital period of the binary system, in \n units of days\n \n --rin arg Inner radius of the disk, in the units of \n the gravitational radius of the central \n object GM/c^2. There is no need to set it \n for a neutron star. If it isn't set for a \n black hole then the radius of ISCO orbit is \n used, defined by --Mx and --kerr values\n \n -R [ --rout ] arg Outer radius of the disk, in units of solar \n radius. If it isn't set then the tidal \n radius is used, defined by --Mx, --Mopt and \n --period values as 90% of the Roche lobe \n radius (Papaloizou \u0026 Pringle, 1977, MNRAS, \n 181, 441; see also Artymowicz \u0026 Lubow, 1994,\n ApJ, 421, 651; http://xray.sai.msu.ru/~galja\n /images/tidal_radius.pdf)\n \n --risco arg Innermost stable circular orbit, in units of\n gravitational radius of the central object \n GM/c^2. If it isn't set then the radius of \n ISCO orbit is used defined by --Mx and \n --kerr values\n \n\nParameters of the disk model:\n -O [ --opacity ] arg (=Kramers) Opacity law: Kramers (varkappa ~ rho / \n T^7/2) or OPAL (varkappa ~ rho / T^5/2)\n \n --Mdotout arg (=0) Accretion rate onto the disk through its \n outer radius\n \n --boundcond arg (=Teff) Outer-boundary movement condition\n \n Values:\n Teff: outer radius of the disk moves \n inwards to keep photosphere temperature of \n the disk larger than some value. This value \n is specified by --Thot option\n Tirr: outer radius of the disk moves \n inwards to keep irradiation flux of the disk\n larger than some value. The value of this \n minimal irradiation flux is \n [Stefan-Boltzmann constant] * Tirr^4, where \n Tirr is specified by --Thot option\n \n --Thot arg (=0) Minimum photosphere or irradiation \n temperature at the outer edge of the hot \n disk, Kelvin. For details see --boundcond \n description\n \n --Qirr2Qvishot arg (=0) Minimum Qirr / Qvis ratio at the outer edge \n of the hot disk to switch the control over \n the evolution of the hot disk radius: from \n temperature-based regime to Sigma-based \n cooling-front regime (see Lipunova et al. \n (2021, Section 2.4) and Eq. A.1 in Lasota et\n al. 2008; --alpha value is used for \n Sigma_plus and --alphacold value is used for\n Sigma_minus)\n \n --initialcond arg (=powerF) Type of the initial condition for viscous \n torque F or surface density Sigma\n \n Values:\n [NB! Here below dimensionless xi = (h - \n h_in) / (h_out - h_in)]\n \n powerF: F ~ xi^powerorder, powerorder is \n specified by --powerorder option\n linearF: F ~ xi, specific case of powerF \n but can be normalised by --Mdot0, see its \n description for details\n powerSigma: Sigma ~ xi^powerorder, \n powerorder is specified by --powerorder \n option\n sineF: F ~ sin( xi * pi/2 )\n gaussF: F ~ exp(-(xi-mu)**2 / 2 sigma**2),\n mu and sigma are specified by --gaussmu and \n --gausssigma options\n quasistat: F ~ f(h/h_out) * xi * h_out/h, \n where f is quasi-stationary solution found \n in Lipunova \u0026 Shakura 2000. f(xi=0) = 0, \n df/dxi(xi=1) = 0\n \n --F0 arg Initial maximum viscous torque in the disk, \n dyn*cm. Can be overwritten via --Mdisk0 and \n --Mdot0\n \n --Mdisk0 arg Initial disk mass, g. If both --F0 and \n --Mdisk0 are specified then --Mdisk0 is \n used. If both --Mdot0 and --Mdisk0 are \n specified then --Mdot0 is used\n \n --Mdot0 arg Initial mass accretion rate through the \n inner radius, g/s. If --F0, --Mdisk0 and \n --Mdot0 are specified then --Mdot0 is used. \n Works only when --initialcond is set to \n linearF, sinusF or quasistat\n \n --powerorder arg Parameter for the powerlaw initial condition\n distribution. This option works only with \n --initialcond=powerF or powerSigma\n \n --gaussmu arg Position of the maximum for Gauss \n distribution, positive number not greater \n than unity. This option works only with \n --initialcond=gaussF\n \n --gausssigma arg Width of for Gauss distribution. This option\n works only with --initialcond=gaussF\n \n --windtype arg (=no) Type of the wind\n \n no: no wind\n SS73C: super-Eddington spherical wind from\n Shakura-Sunyaev 1973\n ShieldsOscil1986: toy wind model from \n Shields et al. 1986 which was used to obtain\n oscillations in the disk luminosity. \n Requires --windC_w and --windR_w to be \n specified\n Janiuk2015: super-Eddington wind from \n Janiuk et al 2015. Requires --windA_0 and \n --windB_1 to be specified\n Shields1986: thermal wind from Begelman et\n al. 1983 and Shields et al. 1986. Requires \n --windXi_max, --windT_ic and --windPow to be\n specified\n Woods1996AGN: thermal AGN wind from Woods \n et al. 1996. Requires --windC_0 and \n --windT_ic to be specified\n Woods1996: thermal wind from Woods et al. \n 1996. Requires --windXi_max, --windT_ic and \n --windPow to be specified\n toy: a toy wind model used in \n arXiv:2105.11974, the mass loss rate is \n proportional to the central accretion rate. \n Requires --windC_w to be specified\n \n --windC_w arg The ratio of the mass loss rate due to wind \n to the central accretion rate, |Mwind|/Macc\n \n --windR_w arg The ratio of the wind launch radius to the \n outer disk radius, Rwind/Rout\n \n --windA_0 arg Dimensionless parameter characterizing the \n strength of the super-Eddington wind in the \n framework of the model Janiuk et al. 2015. \n Effective value range from 10 to 25\n \n --windB_1 arg The quantity is of the order of unity. \n Characterizes the relationship between the \n change in energy per particle and virial \n energy.\n E = B_1 * k * T\n \n --windXi_max arg Ionization parameter, the ratio of the \n radiation and gas pressures\n \n --windT_ic arg Inverse Compton temperature, K. \n Characterizes the hardness of the \n irradiating spectrum\n \n --windPow arg Multiplicative coefficient to control wind \n power\n \n --windC_0 arg Characteristic column density of the wind \n mass loss rate from Woods et al. 1996 model,\n g/(s*cm^2). For AGN approx value is 3e-13 \n g/(s*cm^2)\n \n\nParameters of self-irradiation:\nQirr = Cirr * (H/r / 0.05)^irrindex * L * psi / (4 pi R^2), where psi is the angular distribution of X-ray radiation\n:\n --Cirr arg (=0) Irradiation factor for the hot disk\n \n --irrindex arg (=0) Irradiation index for the hot disk\n \n --Cirrcold arg (=0) Irradiation factor for the cold disk\n \n --irrindexcold arg (=0) Irradiation index for the cold disk\n \n --h2rcold arg (=0) Semi-height to radius ratio for the cold \n disk\n \n --angulardistdisk arg (=plane) Angular distribution of the disk X-ray \n radiation. Values: isotropic, plane\n \n\nParameters of flux calculation:\n:\n --colourfactor arg (=1.7) Colour factor to calculate X-ray flux\n \n --emin arg (=1) Minimum energy of X-ray band, keV\n \n --emax arg (=12) Maximum energy of X-ray band, keV\n \n --staralbedo arg (=0) Part of X-ray radiation reflected by optical\n star, (1 - albedo) heats star's photosphere.\n Used only when --starflux is specified\n \n -i [ --inclination ] arg (=0) Inclination of the system, degrees\n \n --ephemerist0 arg (=0) Ephemeris for the time of the minimum of the\n orbital light curve T0, phase zero \n corresponds to inferior conjunction of the \n optical star, days\n \n --distance arg Distance to the system, kpc\n \n --colddiskflux Add Fnu for cold disk into output file. \n Default output is for hot disk only\n \n --starflux Add Fnu for irradiated optical star into \n output file. See --Topt, --starlod and \n --h2rcold options. Default is output for the\n hot disk only\n \n --lambda arg Wavelength to calculate Fnu, Angstrom. You \n can use this option multiple times. For each\n lambda one additional column with values of \n spectral flux density Fnu [erg/s/cm^2/Hz] is\n produced\n \n --passband arg Path of a file containing tabulated passband\n for a photon counter detector, the first \n column for wavelength in Angstrom, the \n second column for transmission factor, \n columns should be separated by spaces\n \n\nParameters of disk evolution calculation:\n:\n --inittime arg (=0) Initial time moment, days\n \n -T [ --time ] arg Time interval to calculate evolution, days\n \n --tau arg Time step, days\n \n --Nx arg (=1000) Size of calculation grid\n \n --gridscale arg (=log) Type of grid for angular momentum h: log or \n linear\n \n --starlod arg (=3) Level of detail of the optical star 3-D \n model. The optical star is represented by a \n triangular tile, the number of tiles is 20 *\n 4^starlod\n \n\n\n```\n\u003c/details\u003e\n\n```sh\n./freddi-ns --help\n```\n\n\u003cdetails\u003e\u003csummary\u003eexpand\u003c/summary\u003e\n\n```\nFreddi NS: numerical calculation of accretion disk evolution:\n\nGeneral options::\n -h [ --help ] Produce help message\n \n --config arg Set filepath for additional \n configuration file. There is no need to\n declare a configuration file with the \n default name freddi.ini\n \n --prefix arg (=freddi) Set prefix for output filenames. Output\n file with distribution of parameters \n over time is PREFIX.dat\n \n --stdout Output temporal distribution to stdout \n instead of PREFIX.dat file\n \n -d [ --dir ] arg (=.) Choose the directory to write output \n files. It should exist\n \n --precision arg (=12) Number of digits to print into output \n files\n \n --tempsparsity arg (=1) Output every k-th time moment\n \n --fulldata Output files PREFIX_%d.dat with radial \n structure for every time step. Default \n is to output only PREFIX.dat with \n global disk parameters for every time \n step\n \n\nBasic binary and disk parameters\n:\n -a [ --alpha ] arg Alpha parameter of Shakura-Sunyaev \n model\n \n --alphacold arg Alpha parameter of cold disk, currently\n it is used only for the critical \n maximum value of the surface density of\n the cold disk Sigma_minus (Lasota et \n al., 2008, A\u0026A 486, 523) and the \n cooling front velocity (Ludwig et al., \n 1994, A\u0026A 290, 473), see \n --Qirr2Qvishot. Default value is \n --alpha divided by ten\n \n -M [ --Mx ] arg Mass of the central object, in the \n units of solar masses\n \n --kerr arg (=0) Dimensionless Kerr parameter of the \n black hole\n \n --Mopt arg Mass of the optical star, in units of \n solar masses\n \n --rochelobefill arg (=1) Dimensionless factor describing a size \n of the optical star. Polar radius of \n the star is rochelobefill * (polar \n radius of critical Roche lobe)\n \n --Topt arg (=0) Effective temperature of the optical \n star, in units of Kelvins\n \n -P [ --period ] arg Orbital period of the binary system, in\n units of days\n \n --rin arg Inner radius of the disk, in the units \n of the gravitational radius of the \n central object GM/c^2. There is no need\n to set it for a neutron star. If it \n isn't set for a black hole then the \n radius of ISCO orbit is used, defined \n by --Mx and --kerr values\n \n -R [ --rout ] arg Outer radius of the disk, in units of \n solar radius. If it isn't set then the \n tidal radius is used, defined by --Mx, \n --Mopt and --period values as 90% of \n the Roche lobe radius (Papaloizou \u0026 \n Pringle, 1977, MNRAS, 181, 441; see \n also Artymowicz \u0026 Lubow, 1994, ApJ, \n 421, 651; http://xray.sai.msu.ru/~galja\n /images/tidal_radius.pdf)\n \n --risco arg Innermost stable circular orbit, in \n units of gravitational radius of the \n central object GM/c^2. If it isn't set \n then the radius of ISCO orbit is used \n defined by --Mx and --kerr values\n \n\nParameters of the disk model:\n -O [ --opacity ] arg (=Kramers) Opacity law: Kramers (varkappa ~ rho / \n T^7/2) or OPAL (varkappa ~ rho / T^5/2)\n \n --Mdotout arg (=0) Accretion rate onto the disk through \n its outer radius\n \n --boundcond arg (=Teff) Outer-boundary movement condition\n \n Values:\n Teff: outer radius of the disk moves \n inwards to keep photosphere temperature\n of the disk larger than some value. \n This value is specified by --Thot \n option\n Tirr: outer radius of the disk moves \n inwards to keep irradiation flux of the\n disk larger than some value. The value \n of this minimal irradiation flux is \n [Stefan-Boltzmann constant] * Tirr^4, \n where Tirr is specified by --Thot \n option\n \n --Thot arg (=0) Minimum photosphere or irradiation \n temperature at the outer edge of the \n hot disk, Kelvin. For details see \n --boundcond description\n \n --Qirr2Qvishot arg (=0) Minimum Qirr / Qvis ratio at the outer \n edge of the hot disk to switch the \n control over the evolution of the hot \n disk radius: from temperature-based \n regime to Sigma-based cooling-front \n regime (see Lipunova et al. (2021, \n Section 2.4) and Eq. A.1 in Lasota et \n al. 2008; --alpha value is used for \n Sigma_plus and --alphacold value is \n used for Sigma_minus)\n \n --initialcond arg (=powerF) Type of the initial condition for \n viscous torque F or surface density \n Sigma\n \n Values:\n [NB! Here below dimensionless xi = (h\n - h_in) / (h_out - h_in)]\n \n powerF: F ~ xi^powerorder, powerorder\n is specified by --powerorder option\n linearF: F ~ xi, specific case of \n powerF but can be normalised by \n --Mdot0, see its description for \n details\n powerSigma: Sigma ~ xi^powerorder, \n powerorder is specified by --powerorder\n option\n sineF: F ~ sin( xi * pi/2 )\n gaussF: F ~ exp(-(xi-mu)**2 / 2 \n sigma**2), mu and sigma are specified \n by --gaussmu and --gausssigma options\n quasistat: F ~ f(h/h_out) * xi * \n h_out/h, where f is quasi-stationary \n solution found in Lipunova \u0026 Shakura \n 2000. f(xi=0) = 0, df/dxi(xi=1) = 0\n quasistat-ns: Distibution of the \n initial viscous torque in the disc is \n F = F0 * f_F(xi) * (1-h_in/h_out/xi) / \n (1-h_in/h_out), where xi=h/h_out and \n f_F(xi) is taken from Lipunova \u0026 \n Shakura (2000)\n \n --F0 arg Initial maximum viscous torque in the \n disk, dyn*cm. Can be overwritten via \n --Mdisk0 and --Mdot0\n \n --Mdisk0 arg Initial disk mass, g. If both --F0 and \n --Mdisk0 are specified then --Mdisk0 is\n used. If both --Mdot0 and --Mdisk0 are \n specified then --Mdot0 is used\n \n --Mdot0 arg Initial mass accretion rate through the\n inner radius, g/s. If --F0, --Mdisk0 \n and --Mdot0 are specified then --Mdot0 \n is used. Works only when --initialcond \n is set to linearF, sinusF or quasistat\n \n --powerorder arg Parameter for the powerlaw initial \n condition distribution. This option \n works only with --initialcond=powerF or\n powerSigma\n \n --gaussmu arg Position of the maximum for Gauss \n distribution, positive number not \n greater than unity. This option works \n only with --initialcond=gaussF\n \n --gausssigma arg Width of for Gauss distribution. This \n option works only with \n --initialcond=gaussF\n \n --windtype arg (=no) Type of the wind\n \n no: no wind\n SS73C: super-Eddington spherical wind\n from Shakura-Sunyaev 1973\n ShieldsOscil1986: toy wind model from\n Shields et al. 1986 which was used to \n obtain oscillations in the disk \n luminosity. Requires --windC_w and \n --windR_w to be specified\n Janiuk2015: super-Eddington wind from\n Janiuk et al 2015. Requires --windA_0 \n and --windB_1 to be specified\n Shields1986: thermal wind from \n Begelman et al. 1983 and Shields et al.\n 1986. Requires --windXi_max, --windT_ic\n and --windPow to be specified\n Woods1996AGN: thermal AGN wind from \n Woods et al. 1996. Requires --windC_0 \n and --windT_ic to be specified\n Woods1996: thermal wind from Woods et\n al. 1996. Requires --windXi_max, \n --windT_ic and --windPow to be \n specified\n toy: a toy wind model used in \n arXiv:2105.11974, the mass loss rate is\n proportional to the central accretion \n rate. Requires --windC_w to be \n specified\n \n --windC_w arg The ratio of the mass loss rate due to \n wind to the central accretion rate, \n |Mwind|/Macc\n \n --windR_w arg The ratio of the wind launch radius to \n the outer disk radius, Rwind/Rout\n \n --windA_0 arg Dimensionless parameter characterizing \n the strength of the super-Eddington \n wind in the framework of the model \n Janiuk et al. 2015. Effective value \n range from 10 to 25\n \n --windB_1 arg The quantity is of the order of unity. \n Characterizes the relationship between \n the change in energy per particle and \n virial energy.\n E = B_1 * k * T\n \n --windXi_max arg Ionization parameter, the ratio of the \n radiation and gas pressures\n \n --windT_ic arg Inverse Compton temperature, K. \n Characterizes the hardness of the \n irradiating spectrum\n \n --windPow arg Multiplicative coefficient to control \n wind power\n \n --windC_0 arg Characteristic column density of the \n wind mass loss rate from Woods et al. \n 1996 model, g/(s*cm^2). For AGN approx \n value is 3e-13 g/(s*cm^2)\n \n\nParameters of accreting neutron star:\n:\n --nsprop arg (=dummy) Neutron star properties name: defines \n geometry (default values of --Rx, \n --Risco, and --freqx) and \n accretion-\u003eradiation efficiency of NS\n \n Values:\n dummy: NS accretion-\u003eradiation \n efficiency is R_g * (1 / R_x - 1 / \n 2R_in), default --freqx is 0, default \n Rx is 1e6, default Risco is Kerr value\n newt: NS accretion-\u003eradiation \n efficiency is a function of NS \n frequency, calculated in Newtonian \n mechanics (see Lipunova+2021), that's \n why --freqx must be specified \n explicitly\n sibgatullin-sunyaev2000: NS \n accretion-\u003eradiation efficiency and \n default values of Rx and Risco are \n functions of NS frequency, calculated \n for a specific equation of state for a \n NS with weak magnetic field \n (Sibgatullin \u0026 Sunyaev, 2000, Astronomy\n Letters, 26, 699), that's why --freqx \n must be specified explicitly\n \n --freqx arg Accretor rotation frequency, Hz. This \n parameter is not linked to --kerr, \n which could be reconciled manually \n (currently, --kerr is not needed for \n freddi-ns)\n \n --Rx arg Accretor radius, cm\n \n --Bx arg Accretor polar magnetic induction, G\n \n --hotspotarea arg (=1) Total area of the region on the \n accretor radiating because of \n accretion, normalized by the accretor \n surface area\n \n --epsilonAlfven arg (=1) Magnetosphere radius in units of the \n Alfven radius, which is defined as \n (mu^4/G/M/sqrt(Mdot))^(1/7)\n \n --inversebeta arg (=0) Not currently in use\n \n --Rdead arg (=0) Maximum inner radius of the disk that \n can be achieved, cm\n \n --fptype arg (=no-outflow) Scenario to determine the fraction fp \n of accreted mass. The rest of the disk \n inner accretion rate is propelled away.\n \n Values:\n no-outflow: the matter reaching the \n inner disk radius always falls onto NS,\n fp = 1\n propeller: the matter always flows \n away, fp = 0\n corotation-block: like 'no-outflow' \n when the inner disk radius is smaller \n than the corotation radius, like \n 'propeller' otherwise\n geometrical: experimental. \n Generalization of 'corotation-block' \n for the case of misaligned NS magnetic \n axis. Requires --fp-geometrical-chi to \n be specified\n eksi-kutlu2010: Under construction\n romanova2018: fp is an analytical \n function of the fastness, found from \n MHD simulations by Romanova et al. \n (2018, NewA, 62, 94): fp = 1 - \n par1*fastness^par2. This requires \n --romanova2018-par1 and \n --romanova2018-par2 to be specified\n \n --fp-geometrical-chi arg angle between the disk rotation axis \n and the NS magnetic axis, used for \n --fptype=geometrical, degrees\n \n --romanova2018-par1 arg par1 value for --fptype=romanova2018 \n and --kappattype=romanova2018\n \n --romanova2018-par2 arg par2 value for --fptype=romanova2018 \n and --kappattype=romanova2018\n \n --kappattype arg (=const) kappa_t describes how strong is the \n interaction between the NS \n magnetosphere and disk: total \n (accelerating) magnetic torque applied \n to the disc is kappa_t(R) * mu^2 / R^3.\n \n Values:\n const: doesn't depend on radius, \n kappa_t = value. Requires \n --kappat-const-value to be specified\n corstep: kappa_t can be different \n inside and outside the corotation \n radius. Requires --kappat-corstep-in \n and --kappat-corstep-out to be \n specified\n romanova2018: experimental. Similar \n to corstep option, but the outside \n value is reduced by the portion taken \n away by the outflow (see Table 2 of \n Romanova+2018, NewA, 62, 94). Requires \n --kappat-romanova2018-in, \n --kappat-romanova2018-out \n --romanova2018-par1 and --romanova-par2\n to be specified\n \n --kappat-const-value arg (=0.33333333333333331)\n kappa_t value for --kappattype=const\n \n --kappat-corstep-in arg (=0.33333333333333331)\n kappa_t value inside the corotation \n radius for --kappattype=corstep\n \n --kappat-corstep-out arg (=0.33333333333333331)\n kappa_t value outside the corotation \n radius for --kappattype=corstep\n \n --kappat-romanova2018-in arg (=0.33333333333333331)\n kappa_t value inside the corotation \n radius for --kappattype=romanova2018\n \n --kappat-romanova2018-out arg (=0.33333333333333331)\n kappa_t value outside the corotation \n radius for --kappattype=romanova2018\n \n --nsgravredshift arg (=off) Neutron star gravitational redshift \n flag.\n \n Values:\n off: gravitational redshift is not \n taken into account\n on: redshift is (1 - R_sch / Rx), \n where R_sch = 2GM/c^2\n \n\nParameters of self-irradiation:\nQirr = Cirr * (H/r / 0.05)^irrindex * L * psi / (4 pi R^2), where psi is the angular distribution of X-ray radiation\n:\n --Cirr arg (=0) Irradiation factor for the hot disk\n \n --irrindex arg (=0) Irradiation index for the hot disk\n \n --Cirrcold arg (=0) Irradiation factor for the cold disk\n \n --irrindexcold arg (=0) Irradiation index for the cold disk\n \n --h2rcold arg (=0) Semi-height to radius ratio for the \n cold disk\n \n --angulardistdisk arg (=plane) Angular distribution of the disk X-ray \n radiation. Values: isotropic, plane\n \n --angulardistns arg (=isotropic) Flag to calculate angular distribution \n the NS emission. Values: isotropic, \n plane\n \n\nParameters of flux calculation:\n:\n --colourfactor arg (=1.7) Colour factor to calculate X-ray flux\n \n --emin arg (=1) Minimum energy of X-ray band, keV\n \n --emax arg (=12) Maximum energy of X-ray band, keV\n \n --staralbedo arg (=0) Part of X-ray radiation reflected by \n optical star, (1 - albedo) heats star's\n photosphere. Used only when --starflux \n is specified\n \n -i [ --inclination ] arg (=0) Inclination of the system, degrees\n \n --ephemerist0 arg (=0) Ephemeris for the time of the minimum \n of the orbital light curve T0, phase \n zero corresponds to inferior \n conjunction of the optical star, days\n \n --distance arg Distance to the system, kpc\n \n --colddiskflux Add Fnu for cold disk into output file.\n Default output is for hot disk only\n \n --starflux Add Fnu for irradiated optical star \n into output file. See --Topt, --starlod\n and --h2rcold options. Default is \n output for the hot disk only\n \n --lambda arg Wavelength to calculate Fnu, Angstrom. \n You can use this option multiple times.\n For each lambda one additional column \n with values of spectral flux density \n Fnu [erg/s/cm^2/Hz] is produced\n \n --passband arg Path of a file containing tabulated \n passband for a photon counter detector,\n the first column for wavelength in \n Angstrom, the second column for \n transmission factor, columns should be \n separated by spaces\n \n\nParameters of disk evolution calculation:\n:\n --inittime arg (=0) Initial time moment, days\n \n -T [ --time ] arg Time interval to calculate evolution, \n days\n \n --tau arg Time step, days\n \n --Nx arg (=1000) Size of calculation grid\n \n --gridscale arg (=log) Type of grid for angular momentum h: \n log or linear\n \n --starlod arg (=3) Level of detail of the optical star 3-D\n model. The optical star is represented \n by a triangular tile, the number of \n tiles is 20 * 4^starlod\n \n\n\n```\n\u003c/details\u003e\n\n**Write which options are mandatory**\n\nAlso you can use `freddi.ini` configuration file to store options. This [INI\nfile](https://en.wikipedia.org/wiki/INI_file) contains lines `option=value`,\noption names are the as provided by the help message above. Command line option\noverwrites configuration file option. For example, [see\ndefault](https://github.com/hombit/freddi/blob/master/freddi.ini) `freddi.ini`.\n\nPaths where this file is searched are `./freddi.ini` (execution path),\n`$HOME/.config/freddi/freddi.ini`, `/usr/local/etc/freddi.ini` and\n`/etc/freddi.ini`. You can provide configuration file to Docker container as a\nvolume: `` -v \"`pwd`/freddi.ini\":/etc/freddi.ini ``.\n\n#### Output values\n\n`Freddi` outputs time; the accretion rate; the mass of the hot part of the disk;\nthe outer radius of the hot zone; the irradiation factor; the relative\nhalf-height, effective and irradiation temperature, ratio of the irradiation to\nviscous flux at the outer radius of the hot zone; X-ray luminosity (erg/s) in\nthe band from E\\_min to E\\_max (`--emin` and `--emax` options); the optical\nmagnitudes in *U*, *B*, *V*, *R*, *I*, and *J* band ([Allen's Astrophysical\nQuantities, Cox 2015](http://www.springer.com/book/9780387951898)); the spectral density flux (erg/s/cm^2/Hz) at some wavelengths set by one or more `--lambda` options.\n\nSnapshot distributions at each time step, if produced, contain the following\ndata: radial coordinate in terms of the specific angular momentum, radius,\nviscous torque, surface density, effective temperature Teff, viscous temperature\nTvis, irradiation temperature Tirr, and the absolute half-height of the disk.\n\n#### \u003ca name=\"usage-executables-example\"\u003e\u003c/a\u003e Example\n\nThe following arguments instruct `Freddi` to calculate the decay of the outburst\nin the disk with the constant outer radius equal to 1 solar radius. The Kerr\nblack hole at the distance of 5 kpc has the mass of 9 solar masses, and the\nKerr's parameter is 0.4. The outer disk is irradiated with Cirr=1e-3.\n\n```sh\n./freddi --alpha=0.5 --Mx=9 --rout=1 --period=0.5 --Mopt=0.5 --time=50 \\\n --tau=0.25 --dir=data/ --F0=2e+37 --colourfactor=1.7 --Nx=1000 \\\n --distance=5 --gridscale=log --kerr=0.4 --Cirr=0.001 --opacity=OPAL \\\n --initialcond=quasistat --windtype=Woods1996 --windXi_max=10 --windT_ic=1e8 \\\n --windPow=1 \n```\n\nHere we run a simmulation with for a nine sollar mass blac hole (Kerr parameter is 0.4),\nsurrended by an accretion disc with α=0.5, outer radius equals one sollar radius.\nInitial torque profile corresponds to one described by Lipunova\u0026Shakura 2000,\nwhile outer torque equals 2\\*10^37 dyn\\*cm. The irradiation parameter equals 10^-3.\nWe run simmulations for 50 days, with time step of 0.25 days and spatial grid with\n1000 nodes. Disk opacity is described by a power-law κ∼ρ/T^5/2. Disk has a thermal\nwind following Woods et al 1996, with invert compton temperature of hundred million\nkelvins.\n\n### Python\n\nPython bindings can be used as a convenient way to run and analyse Freddi\nsimulations.\n\n#### Initializing\n\nYou can prepare simulation set-up initializing `Freddi`\n(for black hole accretion disk) or `FreddiNeutronStar` (for NS) class instance.\nThese classes accept keyword-only arguments which have the same names and\nmeanings as [command line options](#usage-executables-options), but with three\nmajor exceptions:\n 1. Python package doesn't provide any file output functionality, that's why output arguments like `config`, `dir`, `fulldata`, `starflux`, `lambda` or `passband` are missed;\n 2. all values are assumed to be in CGS units, but you can use `Freddi.from_asrtopy` for dimensional values (see the details bellow);\n 3. parameters of wind, NS `fp` and NS `kappa` models are passed as dictionaries (see the specifications bellow).\n\nThe following code snippet would set-up roughly the same simulation as\n[the command-line example](#usage-executables-example)\n\n```python\nfrom freddi import Freddi\n\nfreddi = Freddi(\n alpha=0.5, Mx=9*2e33, rout=1*7e10, period=0.5*86400, Mopt=0.5*2e33,\n time=50*86400, tau=0.25*86400, F0=2e+37, colourfactor=1.7, Nx=1000,\n distance=5*3e21, gridscale='log', kerr=0.4, Cirr=0.001, opacity='OPAL',\n initialcond='quasistat', windtype='Woods1996',\n windparams=dict(Xi_max=10, T_ic=1e8, Pow=1),\n)\n```\n\nAlternatively we can do the same using `from_astropy` class-method which casts\nall [`astropy.units.Quantity`](https://docs.astropy.org/en/stable/units/quantity.html)\nobjects to CGS values. Note that dimensionality isn't checked, and technically\nit just does `arg.cgs.value` for every `Quantity` argument.\n\n```python\nimport astropy.units as u\nfrom freddi import Freddi\n\nfreddi = Freddi.from_astropy(\n alpha=0.5, Mx=9*u.Msun, rout=1*u.Rsun, period=0.5*u.day, Mopt=0.5*u.Msun,\n time=50*u.day, tau=0.25*u.day, F0=2e+37, colourfactor=1.7, Nx=1000,\n distance=5*u.kpc, gridscale='log', kerr=0.4, Cirr=0.001, opacity='OPAL',\n initialcond='quasistat', windtype='Woods1996',\n windparams=dict(Xi_max=10, T_ic=1e8, Pow=1),\n)\n```\n\nWind model parameters are specified by `windparams` argument which should be\na `dict` instance with string keys and numeric values. Command option to \n`windparams` keys relation is: `--windC_w -\u003e C_w`, `--windR_w -\u003e R_w`,\n`--windA_0 -\u003e A_0`, `--windB_1 -\u003e B_1`, `--windXi_max -\u003e Xi_max`,\n`windT_ic -\u003e T_ic`, `--windPow -\u003e Pow`, `windC_0 -\u003e C_0`.\n\nNeutron star f_p model parameters are specified by `fpparams` mapping with the\nsame structure as `windparams`. Command options to `fpparams` keys relation is:\n`--fp-geometrical-chi -\u003e chi`, `romanova2018-par1 -\u003e par1`,\n`romanova2018-par2 -\u003e par2`.\n\nNeutron star kappa_t model parameters are specified by `kappatparams` mapping\nwith the same structure as `windparams`. Command options to the mapping keys\nrelation is: `--kappat-const-value -\u003e value`, `--kappat-corstep-in -\u003e in`,\n`kappat-corstep-out -\u003e out`, `--kappat-romanova2018-in -\u003e in`,\n`--kappat-romanova2018-out -\u003e out`, `romanova2018-par1 -\u003e par1`,\n`--romanova2018-par2 -\u003e par2`\n\n#### Running\n\nThere are two ways to run a simulation: iterating over time steps, and run the\nwhole simulation in one shot. Note that in both cases your `Freddi` object is\nmutating and represents the current state of the accretion disk.\n\nHere we use iterator interface which yields another `Freddi` object for each\ntime moment.\n\n```python\nimport astropy.units as u\nfrom freddi import Freddi\n\nfreddi = Freddi.from_astropy(\n alpha=0.5, Mx=9*u.Msun, rout=1*u.Rsun, period=0.5*u.day, Mopt=0.5*u.Msun,\n time=20*u.day, tau=1.0*u.day, Mdot0=5e18, distance=10*u.kpc,\n initialcond='quasistat',\n)\n\nfor state in freddi:\n print(f't = {state.t:\u003e7.0f} s, Mdot = {state.Mdot:5.3e} g/s')\nassert state.t == freddi.t\n```\n\nIn this example we run a simulation via `.evolve()` method which returns\n`EvolutionResult` object keeping all evolution states internally and providing\ntemporal distribution of disk's properties.\n\n```python\nimport astropy.units as u\nimport matplotlib.pyplot as plt\nfrom freddi import Freddi\n\nfreddi = Freddi.from_astropy(\n alpha=0.5, Mx=9*u.Msun, rout=1*u.Rsun, period=0.5*u.day, Mopt=0.5*u.Msun,\n time=20*u.day, tau=1.0*u.day, Mdot0=5e18, distance=10*u.kpc,\n initialcond='quasistat',\n)\n\nresult = freddi.evolve()\nassert result.t[-1] == freddi.t\n\n# Plot Mdot(t)\nplt.figure()\nplt.title('Freddi disk evolution: accretion rate')\nplt.xlabel('t, day')\nplt.ylabel(r'$\\dot{M}$, g/cm')\nplt.plot(result.t / 86400, result.Mdot)\nplt.show()\n\n# Plot all F(h) profiles\nplt.figure()\nplt.title('Freddi disk evolution: viscous torque')\nplt.xlabel('r, cm')\nplt.ylabel('F, dyn cm')\nplt.xscale('log')\nplt.yscale('log')\nplt.plot(result.R.T, result.F.T)\nplt.show()\n\n# Plot evolution of effective temperature of the outer hot disk ring\nplt.figure()\nplt.title('Freddi disk evolution: outer effective temperature')\nplt.xlabel('t, day')\nplt.ylabel('T, K')\nplt.plot(result.t / 86400, result.last_Tph)\nplt.show()\n```\n\n#### Properties and methods\n\n`Freddi`, `FreddiNeutronStar` and `EvolutionResult` objects contain dozens of\nproperties returning various physical values like `t` for time moment,\n`Mdot` for accretion rate onto central object, `R` for radius, `F` for torque,\n`Tph` for effective temperature and so on. `first_*` and `last_*` properties\nare used to access innermost and outermost hot disk values of radial-distributed\nquantities. The complete list of properties can be obtained by `dir(Freddi)` or\n`dir(FreddiNeutronStar)`. Note that the most properties are lazy-evaluated and\nrequire some time to access first time. `EvolutionResult` provides all the\nsame properties as underlying `Freddi` or `FreddiNeutronStar` objects but with\nadditional array dimension for temporal distribution, so if `Freddi.Lx` is a\nscalar then `EvolutionResult.Lx` is an 1-D `numpy` array of `(Nt,)` shape,\nif `Freddi.Sigma` is an 1-D array of `(Nx,)` shape, then\n`EvolutionResult.Sigma` is an 2-D array of `(Nt, Nx)` shape. Also, note that if\ndisk shrinks during a simulation, the missing values of `EvolutionResult`\nproperties are filled by NaN.\n\nAll three classes have `flux(lmbd, region='hot', phase=None)` method which can\nbe used to find spectral flux density per unit frequency for optical\nemission. `lmbd` argument can be a scalar or a multidimensional `numpy` array\nof required wavelengths in cm; `region` could be one of \"hot\" (hot disk),\n\"cold\" (cold disk), \"disk\" (\"hot\" + \"cold\"), \"star\" (companion star), and\n\"all\" (\"hot\" + \"cold\" + \"star\"); `phase` is a binary system orbital phase in\nradians, it is required for `region=\"star\"` and `region=\"all\"` only, it can be\ncalculated as `2π t / period + constant`.\n\nAll properties and methods return values in CGS units.\n\n## Physical Background\n\n`Freddi` — Fast Rise Exponential Decay: accretion Disk model Implementation — is\ndesigned to solve the differential equation of the viscous evolution of the\nShakura-Sunyaev accretion disk in a stellar binary system. Shakura-Sunyaev disk\nis the standard model of accretion of plasma onto the cosmic bodies, like\nneutron stars or black holes. Viscous evolution of the accretion disks exibits\nitself, for example, in X-ray outbursts of binary stars. Usually, the outbursts\nlast for several tens of days and many of them are observed by orbital\nobservatories.\n\nThe basic equation of the viscous evolution relates the surface density and\nviscous stresses and is of diffusion type. Evolution of the accretion rate can\nbe found on solving the equation. The distribution of viscous stresss defines\nthe emission from the source.\n\nThe standard model for the accretion disk is implied, which is developed by\n[Shakura \u0026 Sunyaev (1973)](http://adsabs.harvard.edu/abs/1973A%26A....24..337S).\nThe inner boundary of the disk is at the ISCO or can be explicitely set. The\nboundary conditions in the disk are the zero stress at the inner boundary and\nthe zero accretion rate at the outer boundary. The conditions are suitable\nduring the outbursts in X-ray binary transients with black holes.\n\nIn a binary system, the accretion disk is radially confined. In `Freddi`, the\nouter radius of the disk can be set explicitely or calculated as 90% of the \nRoche lobe size to aproximate the tidal truncation radius obtained by \n[Papaloizou \u0026 Pringle (1977)](https://ui.adsabs.harvard.edu/abs/1977MNRAS.181..441P), see --rout help for details.\n\nThe parameters at the disk central plane are defined by the analytic\napproximations ([Suleimanov et al. 2007](http://adsabs.harvard.edu/abs/2007ARep...51..549S)), valid for the\neffective surface temperatures from 10 000 to 100 000 K, approximately. It is\nassumed that the gas pressure dominates, the gas is completely ionized, and the\nphoton opacity is defined by the free-free and free-bound transitions. Opacity\nlaw is for the solar element abundancies and can be chosen from two types: (1)\nKramers' opacity: kappa = 5e24 rho/T\\^(7/2) cm2/g (2) approximation to OPAL\ntables: kappa = 1.5e20 rho/T\\^(5/2) cm2/g ([Bell \u0026 Lin\n1994](http://adsabs.harvard.edu/abs/1994ApJ...427..987B))\n\nThe disk at each radius is in the \"hot\" state if the gas is completely ionized.\nOtherwise, the disk is considered to be \"cold\" locally. Alpha-parameter in the\ncold parts of the disk is appreciably lower than in the hot parts. Thus the\nviscous evolution of the disk should proceed more effectively in the hot parts\nof the disk. To simulate this, `Freddi` has an option to control the outer\nradius of the hot evolving disk. We assume that the evolution goes through the\nquasi-stationary states in the hot zone of variable size. By default, the hot\nzone has the constant size, equal to the tidal radius.\n\nThe initial distribution of the matter in the disk should be specified with\n`--initialcond` option. `Freddi` can start from several types of initial\ndistributions: power-law distribution of the surface density\n`--initialcond=powerSigma`, power-law `--initialcond=powerF` or sinus-law\n`--initialcond=sinusF` distribution of the viscous torque, quasi-stationary\ndistribution `--initialcond=quasistat`. The choice of the initial distribution\ndefines what type of evolution is to be calculated.\n\nStarting from the quasi-stationary or `sinusF` distribution, the solution\ndescribes the decaying part of the outburst. Zero-time accretion rate through\nthe inner edge can be set. In other cases, the rise to the peak is also\ncomputed. Then, initial value of viscous torque at the outer radius (can be set\nby `--F0`) defines uniquely the initial mass of the disk.\n\nSelf-irradiation by the central X-rays heats the outer parts of the disk. A\nfraction of the bolometric flux is supposed to illuminate the disk surface. This\nresults in the larger size of the hot disk if such model is assumed. Also, the\noptical flux is increased because the flux outgoing from the disk surface is\nproportional to Teff\\^4 = Tvis\\^4+Tirr\\^4. Self-irradiation of the disk is\nincluded in the computation if irradiation parameter is not zero. The simplest\nway is to set a constant irradiation factor `--Cirr` (the studies of X-ray novae\nsuggest the range for Cirr 1e-5—5e-3).\n\nObserved flux depends on the distance to the source and the inclination of the\ndisk plane. The inclination angle is the angle between the line of sight and the\nnormal to the disk. The flux, emitted from the disk surface, is defined by the\nsum of the visous and irradiating flux, where the viscous flux is calculated\ntaking into account general relativity effects near the black hole, following\n[Page \u0026 Thorne\n(1974)](http://adsabs.harvard.edu/cgi-bin/nph-bib_query?bibcode=1974ApJ...191..499P)\nand [Riffert \u0026 Herold (1995)](http://adsabs.harvard.edu/cgi-bin/nph-bib\\_query?bibcode=1995ApJ...450..508R).\n\n\n### Accretion disk wind\n\nPresumably, during an outburst there is an outflow in the form of a wind from the \naccretion disk around the compact object. The presence of such a wind in the LMXBs is supported\nby modern observations indicating the expansion of ionized matter. Such an outflow of matter,\nbeing an additional source of angular momentum transfer in the disk, can strongly influence \nits viscous evolution. \n\nHowever, the nature of such winds and their physical characteristics are an open question.\nNamely, there are three mechanisms which are considered:\nheating of matter by central radiation in optically thin regions of the disk \n([Begelman et al. 1983](https://ui.adsabs.harvard.edu/abs/1983ApJ...271...70B), \n[Shields et al. 1986](https://ui.adsabs.harvard.edu/abs/1986ApJ...306...90S), \n[Woods et al. 1996](https://ui.adsabs.harvard.edu/abs/1996ApJ...461..767W)), \nthe pressure of the magnetic field of the disk\n([Blandford \u0026 Payne 1982](https://ui.adsabs.harvard.edu/abs/1982MNRAS.199..883B), \n[Habibi \u0026 Abbassi 2019](https://ui.adsabs.harvard.edu/abs/2019ApJ...887..256H), \n[Nixon \u0026 Pringle 2019](https://ui.adsabs.harvard.edu/abs/2019A%26A...628A.121N))\nand the pressure of local radiation at super-Eddington accretion rates\n([Shakura \u0026 Sunyaev 1973](http://adsabs.harvard.edu/abs/1973A%26A....24..337S), \n[Proga \u0026 Kallman 2002](https://ui.adsabs.harvard.edu/abs/2002ApJ...565..455P)). \n\n`Freddi` is modernized in such a way that it is able to solve the viscous evolution \nequation with an inhomogeneous term that is responsible for the presence of the disk wind.\nThis term is the dependence of the surface density of the wind mass-loss rate on \nthe distance along the disk's surface. Different forms of such dependence correspond \nto different wind models, and to different classes within `Freddi`. \n\n\nOne can choose a wind model by setting the\n`--windtype` option. The thermal wind model ([Woods et al. 1996](https://ui.adsabs.harvard.edu/abs/1996ApJ...461..767W)),\nwhich implies that the outflow of matter occurs due to the heating of the outer parts of the disk\nby a central radiation source, can be chosen by setting `--windtype=Woods1996`. \nThe option `--windtype=Janiuk15` corresponds to the model from work [Janiuk et al. (2015)](https://ui.adsabs.harvard.edu/abs/2015A%26A...574A..92J)\nwhere the wind is started in the super-Eddington regime.\nWhen choosing option `--windtype=Janiuk15`, the you must also specify the values of\nthe super-Eddington wind parameters with `--windA0` and `--windB1` options.\nYou can also select the `--windtype=toy` option, which corresponds to a toy wind model when the user sets \nthe wind strength relatively to the accretion rate using the option `--windPow`.\n\n#### Compton-heated wind\n\nAt the moment, `Freddi` is more focused on simulating outbursts taking into account the thermal wind (`--windtype=Woods1996` option). \nFor a better understanding, let's discuss a little the physics of the process of launching such a wind \nand its parameters in the code.\n\nIn the standard accretion disk model by [Shakura \u0026 Sunyaev (1973)](http://adsabs.harvard.edu/abs/1973A%26A....24..337S) \nthe disk is concave, and, as a result, the disk surface is exposed to the central radiation, \nwhich heats the disk material. As a result, the heated matter, starting from a certain radius, \nbegins to leave the accretion disk. This process of heating the matter of the accretion disk by means of Compoton\nprocesses was developed in [Begelman et al. (1983)](https://ui.adsabs.harvard.edu/abs/1983ApJ...271...70B) and \n[Shields et al. (1986)](https://ui.adsabs.harvard.edu/abs/1986ApJ...306...90S). \nIn a later work [Woods et al. (1996)](https://ui.adsabs.harvard.edu/abs/1996ApJ...461..767W), \ntwo-dimensional magnetohydrodynamic calculations were performed and the \nresults of [Shields et al. (1986)](https://ui.adsabs.harvard.edu/abs/1986ApJ...306...90S) were generalized. \n[Woods et al. (1996)](https://ui.adsabs.harvard.edu/abs/1996ApJ...461..767W) give an expression for the surface density of the mass \nloss rate as a function of distance along the disk's surface. This function is used in `Freddi` \nto taking thermal wind into account.\n\nChoosing option `--windtype=Woods1996`, it is necessary to set the value of the ionization parameter Xi\n(which is proportional to the ratio of the radiation and gas pressures) by the option `--windXi_max` and the Compoton temperature T_ic \n(which determines the hardness of the irradiating spectrum and the size of the region where the wind operates) by the option `--windT_ic`. \n\n### Companion star irradiation\n\nWe use a simple model of irradiated star to simulate periodic variability and\nX-ray thermalization by a companion's photosphere. Our model assumes that the\ncompanion star's shape corresponds to equipotential surface which size is set\nby `--rochelobefill` option, unity means that star fills its Roche lobe, any\nsmaller value decreases star's polar radius correspondingly. Technically,\nstar's surface is built from `20 * 4^starlod` triangles, use `--starlod` to\nset level of detail, `--starlod=3` should give few percent precision. Every\ntriangle has black-body spectrum with bolometric luminosity given by a sum of\nstar's own luminosity (set by `--Topt`) and irradiation flux multiplied by \nunity minus albedo (set by `--staralbedo`).\n\nPlease note that the model is limited and doesn't implement limb darking or\neclipsing.\n\n## Development guide\n\n### Source code and tests\n\n`Freddi` uses [Cmake](https://cmake.org) as a build system.\n\nThe C++ source code is located in `cpp` folder which has following structure:\n- `main.cpp` and `main-ns.cpp` implements `main()` function for `freddi` and `freddi-ns` correspondingly;\n- `include` for library header files, it has `ns` sub-folder for neutron star related stuff;\n- `src` for library C++ files, it also has `ns` sub-folder;\n- `test` provides library unit tests;\n- `pywrap` has both header and source files for `Boost::Python`/`Boost::NumPy` bindings.\n\nNote, that we require C++17 standard (while not having idiomatic C++17 code),\nand require code to be compiled by modern GCC and CLang on Linux. Please write\nunit tests where you can and use `ctest` to check they pass.\n\nThe Python project is specified by `pyproject.toml` (which lists build\nrequirements), `setup.py` and `MANIFEST.in` files, we use\n[`scikit-build`](https://scikit-build.readthedocs.io/) as a build system.\n`scikit-build` uses Python-related section of `CMakeLists.txt` to build C++\nsource code into Python extension, and accomplish it with Python files located\nin `python/freddi` directory. Use `python setup.py build_ext` to build the\nextension, optionally with `-DSTATIC_LINKING=TRUE` to link `Boost::Filesystem`,\n`Boost::Python` and `Boost::NumPy` statically. Please, pay attention to two\nlast libraries, because they should be built against the same Python version as\nyou use.\n\n`python/test` contains some tests, you can run them by `python3 setup.py test`.\n- `test_freddi.py` and `test_ns.py` contain unit tests for Python source;\n- `test_analytical.py` contains integration tests to compare analytical solutions of the equation of disk viscous evolution with the numerical solutions of `Freddi`;\n- `regression.py` contains regression tests to be sure that 1) the `Freddi` output is stable vs previous commits, and 2) the Python code gives the same results as binary executables do.\n\nThe regression test data are located in `python/test/data`. Sometimes you need\nto update these regression data, for example when you introduce new\ncommand-line option with a default value, add new output column or fix some bug\nin physical model. For these purposes you can use `generate_test_data.sh`\nscript located in this folder.\n\n`Dockerfile` is used to build a Docker image with statically-linked binaries,\nand `Dockerfile.python` is used to build a Docker image with\n[`manylinux`](https://github.com/pypa/manylinux)-compatible Python wheels.\n\n\n### Continuous integration\n\nWe use [Github Actions](https://github.com/hombit/freddi/actions) as a\ncontinuous integration (CI) system. The workflow file is located in\n`.github/workflows/main.yml` and a couple of auxiliary files are located in\n`.ci` folder. CI allows us to test new commits to prevent different bugs:\n- `gcc` and `clang` actions test binaries building, execute sample `Freddi` programs, run C++ unit tests, perform C++ regression tests, and check the consistency of the `Readme.md` with programs' `--help` output\n- `cpython` action builds Python extension module and runs all Python tests\n- `docker-exe` builds a Docker image using `Dockerfile` and execute sample `Freddi` programs inside a Docker container\n- `docker-python` builds a Docker image using `Dockefile.python`, uses wheels it has built to build Python Docker images for several Python versions using `.ci/Dockerfile-test-wheels`, and runs sample Python scripts with `freddi.Freddi` class\n\n### This Readme\n\nPlease keep Readme updated. You can update the help messages in the\n[Usage](#usage) section using `.ci/update-help-readme.py` script.\n\n### Release new version\n\nCheck-list:\n\n- [ ] Update version in `setup.py` and commit it\n- [ ] Create `git` tag\n ```sh\n git tag $VERSION\n ```\n- [ ] Build new `freddi` image using `Dockerfile`\n ```sh\n docker buildx build --push --platform linux/arm64,linux/amd64 --tag ghcr.io/hombit/freddi:$VERSION .\n docker pull ghcr.io/hombit/freddi:$VERSION\n docker tag ghcr.io/hombit/freddi:$VERSION ghcr.io/hombit/freddi:latest\n docker push ghcr.io/hombit/freddi:latest\n ```\n- [ ] Build new `freddi-python` image using `Dockerfile.python`\n ```sh\n docker buildx build --push --platform linux/arm64,linux/amd64 --tag ghcr.io/hombit/freddi-python:$VERSION -f Dockerfile.python .\n docker pull ghcr.io/hombit/freddi-python:$VERSION\n docker tag ghcr.io/hombit/freddi-python:$VERSION ghcr.io/hombit/freddi-python:latest\n docker push ghcr.io/hombit/freddi-python:latest\n ```\n- [ ] Upload wheels onto PyPi.org\n ```sh\n docker run --rm -ti ghcr.io/hombit/freddi-python:$VERSION sh -c \"python3.12 -m twine upload /dist/*.tar.gz\" # sdist\n docker run --rm -ti --platform linux/amd64 ghcr.io/hombit/freddi-python:$VERSION sh -c \"python3.12 -m twine upload /dist/*.whl\" # bdist x86_64\n docker run --rm -ti --platform linux/arm64 ghcr.io/hombit/freddi-python:$VERSION sh -c \"python3.12 -m twine upload /dist/*.whl\" # bdist aarch64\n ```\n- [ ] [Optional] Build executables for GitHub release\n- [ ] [Optional] Build and upload macOS wheels\n- [ ] Crate new GitHub release\n\n\n## Questions and comments\n\nIf you have any problems, questions, or comments, please address them to\n[Issues](https://github.com/hombit/freddi/issues) or to hombit\\@gmail.com\n\n## License\n\nCopyright (c) 2016–2024, Konstantin L. Malanchev, Galina V. Lipunova \u0026 Artur L. Avakyan.\n\n`Freddi` is distributed under the terms of the\n[GPLv3](https://www.gnu.org/licenses/gpl-3.0.html).\n\nPlease, accompany any results obtained using this code with reference to\nLipunova \u0026 Malanchev (2017)\n[2017MNRAS.468.4735L](http://adsabs.harvard.edu/abs/2017MNRAS.468.4735L),\nfor the case of windy calculations please also refer Avakyan et al. (2021)\n[2021AstL...47..377A](http://adsabs.harvard.edu/abs/2021AstL...47..377A),\nand for the case of magnetised neutron star please also refer Lipunova et al. (2021)\n[2021arXiv211008076L](http://adsabs.harvard.edu/abs/2021arXiv211008076L).\n\n\n## BibTex\n```bibtex\n@ARTICLE{2017MNRAS.468.4735L,\n author = { {Lipunova}, G.~V. and {Malanchev}, K.~L.},\n title = \"{Determination of the turbulent parameter in accretion discs: effects of self-irradiation in 4U 1543{\\minus}47 during the 2002 outburst}\",\n journal = {\\mnras},\narchivePrefix = \"arXiv\",\n eprint = {1610.01399},\n primaryClass = \"astro-ph.HE\",\n keywords = {accretion, accretion discs, methods: numerical, binaries: close, stars: black holes, X-rays: individual: 4U 1543-47},\n year = 2017,\n month = jul,\n volume = 468,\n pages = {4735-4747},\n doi = {10.1093/mnras/stx768},\n adsurl = {http://adsabs.harvard.edu/abs/2017MNRAS.468.4735L},\n adsnote = {Provided by the SAO/NASA Astrophysics Data System}\n}\n\n@ARTICLE{2021AstL...47..377A,\n author = {{Avakyan}, A.~L. and {Lipunova}, G.~V. and {Malanchev}, K.~L. and {Shakura}, N.~I.},\n title = \"{Change in the Orbital Period of a Binary System Due to an Outburst in a Windy Accretion Disk}\",\n journal = {Astronomy Letters},\n keywords = {X-ray binaries, wind, transients, period, accretion, Astrophysics - High Energy Astrophysical Phenomena},\n year = 2021,\n month = jun,\n volume = {47},\n number = {6},\n pages = {377-389},\n doi = {10.1134/S1063773721050017},\narchivePrefix = {arXiv},\n eprint = {2105.11974},\n primaryClass = {astro-ph.HE},\n adsurl = {https://ui.adsabs.harvard.edu/abs/2021AstL...47..377A},\n adsnote = {Provided by the SAO/NASA Astrophysics Data System}\n}\n\n@ARTICLE{2021arXiv211008076L,\n author = {{Lipunova}, Galina and {Malanchev}, Konstantin and {Tsygankov}, Sergey and {Shakura}, Nikolai and {Tavleev}, Andrei and {Kolesnikov}, Dmitry},\n title = \"{Physical modeling of viscous disc evolution around magnetized neutron star. Aql X-1 2013 outburst decay}\",\n journal = {arXiv e-prints},\n keywords = {Astrophysics - High Energy Astrophysical Phenomena, Astrophysics - Solar and Stellar Astrophysics},\n year = 2021,\n month = oct,\n eid = {arXiv:2110.08076},\n pages = {arXiv:2110.08076},\narchivePrefix = {arXiv},\n eprint = {2110.08076},\n primaryClass = {astro-ph.HE},\n adsurl = {https://ui.adsabs.harvard.edu/abs/2021arXiv211008076L},\n adsnote = {Provided by the SAO/NASA Astrophysics Data System}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhombit%2Ffreddi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhombit%2Ffreddi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhombit%2Ffreddi/lists"}