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. 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.

Explore the plots

The results page shows current or power, voltage, and temperature for lumped thermal simulations. Below these, choose a spatial profile: electrolyte concentration or potential, or paired negative and positive electrode potentials, exchange 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.

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.

Save the results

Choose Download results to select JSON or CSV and the fields to save. Time, current, voltage and temperature start selected. 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.

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 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.