User guide

Manage your API tokens and run simulations

Manage your API tokens and run battery simulations in your browser or with the DandeLiion Python Client.

1. Set up your account

Create an account with your email address and a strong password.
Accept the current Terms of Service and Privacy Notice when prompted.
Open the verification email and follow its link.
Open API tokens to see your shared allowance and token list.

If the verification message does not arrive, sign in and request another from the verification page.

2. Generate and store a token

On the API tokens page, choose Generate token.
Add a descriptive label such as Laptop, Jupyter notebook or CI runner.
Choose an expiry date within the maximum lifetime allowed by your tier.
Generate the token and copy it immediately to a password manager or secret store.

The full token is shown once. The portal stores only a cryptographic digest and cannot show or recover the secret later. If you lose it, generate a replacement.

For command-line use, place the token in an environment variable instead of writing it into a script:

export DANDELIION_API_TOKEN="your-64-character-token"

Never commit a token to source control, paste it into logs, or share it in email or chat.

3. Manage, replace and deactivate tokens

Your token dashboard shows each token's label, eight-character prefix, status, expiry, last use and successful-use count. The prefix helps identify a token without exposing its secret.

Create a separate labelled token for each device, notebook, application or collaborator. This makes it possible to replace one credential without disrupting everything else.

Replace a token safely

Generate and securely store a new token.
Update the Python Client, application or secret store that uses the old token.
Run a test simulation with the replacement.
Choose Deactivate beside the old token and confirm the action.

Deactivation is immediate and permanent. Tokens are not deleted from the list because their metadata is retained for your usage history; a deactivated token can never be used or reactivated. Deactivate a token immediately if its secret may have been exposed.

4. Understand your allowance

All tokens on your account draw from one shared simulation allowance. The dashboard shows the current allowance, uses consumed, uses remaining and the next renewal date.

Each successful simulation validation consumes one use.
If a response is lost, retrying the same request with the same key returns the original run without consuming another use.
Submitting different input with a previously used key is rejected.
An expired, deactivated or unknown token does not consume a use.
When the shared allowance is exhausted, none of your tokens can start another simulation until the allowance is renewed or adjusted.

5. Use the online simulator

The online simulator is a public beta. We can provide more tokens for testers; contact DandeLiion to request them or share feedback.

Sign in, choose a parameter set or upload a BPX file, configure the input and simulation limits, then submit. Selecting a drive cycle shows a current or power preview that updates with direction, multiplier and repeats. Current profiles include UDDS, US06, WLTC and eVTOL; the eVTOL current is already scaled to one quarter of the supplied profile before your chosen multiplier is applied. WLTP uses power. The portal prepares temporary simulator access automatically and each accepted submission consumes one use from your shared allowance. Viewing plots, moving the time slider and downloading results do not consume additional uses.

Configure a cylindrical pack

Choose DFN :: NsMp pack :: Cylindrical cells to configure series cells, parallel cells and vertical sections per cell, each from 1 to 10. Pack defaults are LG M50 Chen2020 and O'Regan2022, 4s4p and four sections per cell. Rotate or zoom the geometry preview to inspect the arrangement. Single-cell simulations default to Isothermal; packs require Lumped thermal. Review the pack thermal properties, editable cell volume, section resistances and the initial, ambient and base-plate temperatures before submitting. Standard and Extra resources use the same one-use allowance per accepted run.

PAT03, PAT07 and PAT10 provide prescribed charge/discharge and rest sequences. Their current scales with the number of parallel cells and your multiplier; voltage cut-offs scale with the series count. Each pattern runs once, with direction fixed by its instructions. The preview shows one nominal cycle: reaching a voltage cut-off can shorten a step. With Maximum time step set to Auto, embedded pattern periods remain active; an explicit setting also caps those periods.

Pack results include an interactive 3D view when geometry is available. Select a cell section to explore its electrical, thermal and spatial plots. Separate pack plots show current, power, voltage and the mean temperature of all cell sections. Available results can be downloaded as JSON or CSV.

Explore the plots

For lumped thermal simulations, choose Simplified (the default), BPX, or Corrected heat generation. Simplified uses the Bernardi irreversible heating term (V − U) × I. BPX follows the BPX standard (opens in a new tab). Corrected is rigorously derived from the DFN model and the conservation law, as described in “Heat Generation and a Conservation Law for Chemical Energy in Lithium-ion Batteries” by G. Richardson and I. Korotkin (DOI, arXiv; both open in new tabs). Fixed, initial and ambient temperature inputs accept −40°C to 80°C.

Single-cell results show current or power, voltage, and temperature for lumped thermal simulations. Heat sources appear below temperature as cumulative energy in W·h, integrated from zero using the saved time samples. Combined plots reversible and irreversible contributions together. For Corrected it also includes a red dashed line for irreversible heating without the two electrode heat-of-mixing contributions; this derived line appears only in the chart. Corrected results start on Loss breakdown: seven separate lines for electrolyte losses, negative and positive particle mixing, electrode ohmic losses and particle-surface polarisation losses. Electrolyte losses are black; mixing is red, ohmic losses green and polarisation losses purple. Negative-electrode terms use solid lines and positive-electrode terms dashed lines. Signed values are preserved because some terms can represent cooling. The legend appears inside the top-left corner of the plot with a translucent white background. JSON and CSV retain the original, non-integrated heat sources in watts.

Below the time plots, choose a spatial profile: electrolyte concentration or potential, overpotentials, or paired negative and positive electrode potentials, exchange current densities, Li insertion reaction current densities, concentrations or surface concentrations.

Electrolyte concentration is shown by default at the final saved time. Move the time slider to inspect earlier saved samples; the chosen time is retained when switching plots. Time labels are rounded to one decimal place. Each spatial plot uses a fixed vertical scale covering its values across the entire simulation, so moving the slider lets you compare profiles directly. The x-axis spans the negative electrode, separator and positive electrode in micrometres. Electrode profiles leave a gap across the separator; electrolyte profiles extend through it. Electrode concentration is the particle-volume average at each x-coordinate, while surface concentration describes the particle surface.

The number of electrode pairs defaults from the chosen BPX file and accepts whole numbers from 1 to 100. Changing it leaves the nominal cell capacity and applied current unchanged. For example, doubling the number of pairs reduces the effective C-rate by half and approximately doubles the discharge duration, subject to the simulation limits.

If the solver stops early after producing usable data, the page shows Completed (partial results). You can plot and download the available samples; the simulation log explains why the run stopped. A run that produces no usable data cannot show plots. Open the Simulation log disclosure to refresh available log output automatically while the run is active; new solver messages are published periodically, so allow a few seconds for them to appear.

Save the results

Choose Download results to select JSON or CSV and the fields to save. Time, current, voltage and temperature start selected. Thermal outputs are available for lumped runs and start unchecked; Corrected runs include all seven loss components. Time is always included; use Select all or Clear selection to change the other choices. Main fields appear first in the order time, current, voltage, temperature and power, including in CSV exports when selected. Labels ending in vs x identify spatial profiles; exported field names retain their original units and spelling. JSON exports automatically include available x-coordinate arrays needed by the selected spatial profiles. Older files need both a profile and its saved x-coordinates to draw a spatial plot; other spatial quantities are optional.

To reopen a saved file, choose Load results on the API tokens page. Version-2 JSON bundles from this portal or Python Client 2.0.0 are read locally in the current tab, without uploading the file or using tokens. Full and selected-field results use the existing single-cell or pack plots; missing data is labelled No data. Available heating terms, temperature and saved logs are shown. The client restores only the fields actually saved.

New portal JSON downloads include model information and available pack geometry even when only selected fields are saved. Older files need enough information to identify their model; ambiguous files are rejected. An older pack file without geometry can show its saved plots but cannot reconstruct the 3D view. Refreshing or leaving the local viewer requires selecting the file again. Its Download results button saves the original JSON unchanged.

CSV expands spatial profiles into separate columns and repeats selected fixed coordinates on each time row. JSON can be restored with the Python Client; choosing all fields retains the model Header. Both formats use up to eight significant digits. The Time interval slider defaults to Every saved step. Choose 0.1, 1, 10, 30, 60 or 300 seconds for an exactly spaced time grid with linearly interpolated values, starting at the first saved time and ending at the last grid point at or before the final saved time. Spatial profiles are interpolated in time; fixed coordinates remain unchanged.

The portal stores neither simulation history nor result files. Download anything you need before leaving. Reopening a run requires the same browser and its still-valid temporary simulator credential; signing out removes that access.

6. Use the DandeLiion Python Client

DandeLiion Python Client 2.0 provides a PyBaMM-like interface for submitting simulations to API v2, monitoring runs and retrieving results. It supports Python 3.10 through 3.13. Install it from PyPI:

python -m pip install dandeliion-client

To install the optional PyBaMM integration, which validates experiment instructions, use:

python -m pip install "dandeliion-client[pybamm]"

Create a Simulator with the DandeLiion service URL and the token stored in your environment. Then provide a valid BPX file and an experiment:

import os
import dandeliion.client as dandeliion

api_url = "https://api.dandeliion.com"
api_token = os.environ["DANDELIION_API_TOKEN"]
simulator = dandeliion.Simulator(api_url, api_token)

# A BPX filename, pathlib.Path, valid BPX dictionary or BPX object
params = "BPX_file.json"

experiment = dandeliion.Experiment(
    [
        (
            "Discharge at 10 A for 100 seconds",
            "Rest for 10 seconds",
            "Charge at 6 A for 100 seconds",
        )
    ],
    period="1 second",
)

solution = dandeliion.solve(
    simulator=simulator,
    params=params,
    experiment=experiment,
)

print("Status:", solution.status)
print("Final voltage [V]:", solution["Voltage [V]"][-1])

The client accepts optional extra_params for settings such as mesh resolution, initial state of charge, thermal modelling and time-series input. Comprehensive API and Python Client documentation, including advanced model inputs, drive cycles, cancellation, result downloads and structured errors, is available at api.dandeliion.com.

7. Monitor a simulation and use its results

By default, solve() waits for the simulation to finish. For a long-running simulation, start it in non-blocking mode and inspect its status or server log:

solution = dandeliion.solve(
    simulator=simulator,
    params=params,
    experiment=experiment,
    is_blocking=False,
)

print(solution.status)
# queued, running, cancel_requested, succeeded,
# failed, cancelled or timed_out

print(solution.log)
solution.join()  # wait until the run reaches a terminal state

Cancel a queued or running simulation when it is no longer needed:

status = solution.cancel()
print(status)  # cancel_requested or cancelled

A solution behaves like a dictionary. List the available outputs or access an individual result by name:

print(sorted(solution.keys()))
time = solution["Time [s]"]
voltage = solution["Voltage [V]"]
temperature = solution["Temperature [K]"]

Save a solution as an atomic, versioned JSON bundle. Client 2.0 does not store the API token, API origin or reusable server URLs in that file. To reconnect an unfinished run after closing your program, restore the bundle with the API URL and token again:

solution.dump("solution.json")

restored_solution = dandeliion.Simulator.restore(
    "solution.json",
    api_url=api_url,
    api_key=api_token,
)

Completed results are streamed into the bundle without loading the entire response into memory. Restored result fields are then loaded only when you access them.

When a simulation is rejected

Token rejected: Check that the environment variable contains the complete token and that the token is active, unexpired and owned by an active account with uses remaining.
Run failed: Print solution.log and check the BPX data, experiment instructions and optional parameters.
Authorisation uncertain: Do not submit again with a new key. Keep the authorisation request ID reported by the client and provide it to DandeLiion support so the token use can be reconciled.
Service error: Retry later rather than immediately replacing a valid token. A temporary API or validation-service problem may be responsible.

8. Download or delete your account data

At the bottom of the API tokens page, choose Download account data to export your profile, quota, token metadata and legal-acceptance records as JSON. Full token secrets are never included.

Choose Delete account to start permanent account deletion. After confirmation, all active tokens are deactivated, login is disabled and identifying profile data is anonymised. Download any account data you want to keep first.