User guide

Manage your API tokens and run simulations

Use this portal to create and manage tokens, then use a token with the DandeLiion Python Client to submit battery simulations securely.

1. Set up your account

1. Create an account with your email address and a strong password.
2. Open the verification email and follow its link.
3. Accept the current Terms of Service and Privacy Notice when prompted.
4. 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

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

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

1. Generate and securely store a new token.
2. Update the Python Client, application or secret store that uses the old token.
3. Run a test simulation with the replacement.
4. 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.
• Submitting the same request again consumes another use.
• 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 DandeLiion Python Client

The Python Client provides a PyBaMM-like interface for submitting simulations and retrieving their results. 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 API 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/v1"
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 also accepts optional extra_params for settings such as mesh resolution, initial state of charge, thermal modelling and time-series input. See the complete DandeLiion Python Client reference for advanced model inputs and drive cycles.

6. 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, success or failed
print(solution.log)
solution.join()         # wait until the run finishes

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]"]

To reconnect after closing your program, save the solution reference and restore it later with the same token:

solution.dump("solution.json")

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

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.

Service error

Retry later rather than immediately replacing a valid token. A temporary API or validation-service problem may be responsible.

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