ELISA

Desktop UI:

The Gradio-based desktop UI is under active development in a separate branch: feature/ui. You can preview and test the UI from this branch; it contains the latest UI work-in-progress.

If you want the latest Gradio desktop UI work-in-progress without checking out the repository locally you can install directly from the feature/ui branch on GitHub using pip. This is useful for quick testing or when you don't need to edit the source.

• Branch on GitHub: https://github.com/mikecokina/elisa/tree/feature/ui

Non-editable install (package is installed into the environment):

The following PEP 508 direct-URL form installs the package and the UI extras in one step. This is the form tested and known to install Gradio and other UI extras correctly in most shells:

pip install "elisa[dev,test,ui] @ git+https://github.com/mikecokina/elisa.git@feature/ui"

Notes and troubleshooting

• Shell quoting matters: include the quotes (double or single) around the whole PEP 508 URL expression so your shell does not split the argument. On POSIX shells use double quotes as shown above; on Windows PowerShell you may need single quotes.
• If you later see "ModuleNotFoundError: No module named 'gradio'", extras were not installed. You can either re-run the PEP 508 install (make sure it's quoted), or install Gradio manually:

pip install gradio
# or re-run the PEP 508 form above with correct quoting

After installation, launch the desktop UI the same way:

python -m elisa.ui

Publications

ELISa: A new tool for fast modelling of eclipsing binaries

Desktop UI:

The Gradio-based desktop UI is under active development in a separate branch: feature/ui. You can preview and test the UI from this branch; it contains the latest UI work-in-progress.

• Branch on GitHub: https://github.com/mikecokina/elisa/tree/feature/ui

How to try the UI locally

# fetch the branch and check it out locally
git fetch origin
git checkout -b feature-ui origin/feature/ui

# install the package with UI extras (editable install) and launch the desktop app
pip install -e ".[dev,test,ui]"
python -m elisa.ui

Reporting issues

• This branch may be unstable; use it for testing and experimentation only.
• If you find bugs or UX issues while testing, please open a GitHub Issue and:
  • Prefix the issue title with [UI] to help triage.
  • Mention you tested feature/ui and include steps to reproduce, screenshots, and terminal output when possible.

Once UI features are ready they will be merged into the main dev branch. Contributions and feedback are very welcome.

Introduction

ELISa is a cross-platform Python package for modeling the light curves of close eclipsing binary systems, including surface features such as spots. Support for pulsations is planned.

Current capabilities include:

• BinarySystem - modeling detached, semi-detached, and over-contact binary systems
• SingleSystem - modeling single-star light curves with spot support (pulsations planned)
• Observer - generating synthetic observables such as light curves (with more observables planned)
• Spots - defining stellar spots by longitude, latitude, radius, and temperature factor
• Pulsations - low-amplitude pulsations modeled using spherical harmonics
• Fitting methods - fitting light curves and radial velocity curves using:
  • non-linear least squares
  • Markov Chain Monte Carlo (MCMC)
• Radial velocity modeling - including the Rossiter-McLaughlin effect and RV variations due to spots (and pulsations where applicable)

ELISa is under active development. Work in progress includes:

• extending LC and RV fitting with additional methods and utilities, including automated classification of eclipsing binaries using neural networks to support solving the inverse problem

Planned features include:

• synthetic spectral line modeling

Installation

ELISa requires Python 3.10 or newer.

It is strongly recommended to install ELISa inside a virtual environment.

1. Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows

Upgrade pip:

python -m pip install --upgrade pip

---

2. Install ELISa

Install the latest stable release from PyPI:

pip install elisa

Install the latest development version from GitHub:

pip install git+https://github.com/mikecokina/elisa.git@dev

---

Optional: Jupyter Notebooks

To run example notebooks:

pip install jupyterlab ipykernel

Then launch:

jupyter lab

Configuration

Minimal Configuration

Starting from version 0.6, ELISa includes a built-in Settings Manager and Download Manager to simplify first-time setup.

When ELISa is executed for the first time and no configuration file is detected, a setup wizard will guide you through the basic configuration process. A default configuration file will be created at:

~/.elisa/config.ini

The wizard will prompt you to:

• Select directories for storing atmosphere models and limb darkening tables
• Choose a default atmosphere atlas
• Optionally download required data files automatically

This allows most users to get started without any manual configuration.

---

Manual Configuration

ELISa requires atmosphere models and limb darkening tables before it can run.

You can download them from:

• Atmosphere models:
  https://github.com/mikecokina/elisa/tree/dev/atmosphere
• Limb darkening tables:
  https://github.com/mikecokina/elisa/tree/dev/limbdarkening

---

Default Data Locations

By default, ELISa searches for data files in:

• Atmospheres: $HOME/.elisa/atmosphere/
• Limb darkening tables: $HOME/.elisa/limbdarkening/

If the files are stored in these directories, no additional configuration is required.

---

Custom Data Locations

You may store atmosphere models and limb darkening tables in any directory of your choice.

For example:

• Atmospheres: /home/user/castelli_kurucz/ck04
• Limb darkening: /home/user/ld/

Create a configuration file, for example:

/home/user/.elisa/elisa_config.ini

With minimal content such as:

[support]
ld_tables = /home/user/ld
castelli_kurucz_04_atm_tables = /home/user/castelli_kurucz/ck04
atlas = ck04

A complete configuration reference is available here:

https://github.com/mikecokina/elisa/blob/master/src/elisa/conf/elisa_conf_docs.ini

---

Important Note on Data Format

Atmosphere models and limb darkening tables are stored in standard .csv format.
However, their native format is not directly compatible with ELISa.
The provided datasets have been converted to a format required by ELISa.

---

Specifying a Custom Configuration File

If you are not using the default configuration path, set the environment variable ELISA_CONFIG to point to your configuration file.

On Linux or macOS:

export ELISA_CONFIG=/home/user/.elisa/elisa_config.ini

You can place this command in your shell configuration file (for example, .bashrc or .zshrc) to make it persistent.

On Windows (PowerShell):

setx ELISA_CONFIG "C:\Users\user\.elisa\elisa_config.ini"

Alternatively, you may use the default config.ini file located in:

src/elisa/conf/

without defining any environment variable.

---

Once configured, ELISa is ready to use.

Physics

For a detailed description of the physical assumptions and numerical methods used in ELISa,
please refer to the ELISa Handbook:

https://github.com/mikecokina/elisa/blob/dev/ELISa_handbook.pdf

The handbook explains the modeling of single stars and binary systems, including surface discretization, radiative treatment, orbital dynamics, and observable synthesis.

---

Available Passbands

ELISa can currently model light curves in the following photometric filters:

bolometric
Generic.Bessell.U
Generic.Bessell.B
Generic.Bessell.V
Generic.Bessell.R
Generic.Bessell.I
SLOAN.SDSS.u
SLOAN.SDSS.g
SLOAN.SDSS.r
SLOAN.SDSS.i
SLOAN.SDSS.z
Generic.Stromgren.u
Generic.Stromgren.v
Generic.Stromgren.b
Generic.Stromgren.y
Kepler
Gaia.2010.G
Gaia.2010.BP
Gaia.2010.RP
TESS

Support for additional passbands may be added in future releases.

---

Multiprocessing

ELISa supports parallel computation of light curves to improve performance on multi-core systems.

During multiprocessing, the requested light curve points are divided into smaller batches, and each batch is evaluated on a separate CPU core.

Important Considerations

• Parallelization introduces computational overhead.
• For simple systems (e.g., circular, synchronous, spot-free binaries), multiprocessing may not provide a speed benefit.
• Performance gains depend strongly on system complexity and hardware.

In general, multiprocessing is most effective for:

• Eccentric orbits
• Systems with surface spots
• Systems requiring expensive radiative computations

Careful benchmarking on your target system is recommended to determine whether multiprocessing improves performance for your specific use case.

Examples

Building a Simple Binary System Model (Minimal Working Example)

ELISa allows fast construction of binary system models using parameters prov