From 12e0eabfbae28f73d87db48efea6389645e64acf Mon Sep 17 00:00:00 2001 From: "filipe@flexcompute.com" Date: Thu, 11 Sep 2025 18:28:33 -0300 Subject: [PATCH 1/2] add Web API FAQ --- _faqs/td.SimulationData.from_file.md | 19 ++++++++ _faqs/web.Batch.md | 59 +++++++++++++++++++++++ _faqs/web.Job.md | 56 ++++++++++++++++++++++ _faqs/web.abort.md | 24 ++++++++++ _faqs/web.account.md | 32 +++++++++++++ _faqs/web.estimate_cost.md | 30 ++++++++++++ _faqs/web.get_tasks.md | 26 +++++++++++ _faqs/web.load.md | 28 +++++++++++ _faqs/web.run.md | 34 ++++++++++++++ docs/faq/td.SimulationData.from_file.md | 22 +++++++++ docs/faq/web.Batch.md | 62 +++++++++++++++++++++++++ docs/faq/web.Job.md | 59 +++++++++++++++++++++++ docs/faq/web.abort.md | 27 +++++++++++ docs/faq/web.account.md | 37 +++++++++++++++ docs/faq/web.estimate_cost.md | 33 +++++++++++++ docs/faq/web.get_tasks.md | 29 ++++++++++++ docs/faq/web.load.md | 31 +++++++++++++ docs/faq/web.run.md | 37 +++++++++++++++ docs/index.rst | 1 + docs/web-api.rst | 15 ++++++ faq_categories.json | 15 ++++++ 21 files changed, 676 insertions(+) create mode 100644 _faqs/td.SimulationData.from_file.md create mode 100644 _faqs/web.Batch.md create mode 100644 _faqs/web.Job.md create mode 100644 _faqs/web.abort.md create mode 100644 _faqs/web.account.md create mode 100644 _faqs/web.estimate_cost.md create mode 100644 _faqs/web.get_tasks.md create mode 100644 _faqs/web.load.md create mode 100644 _faqs/web.run.md create mode 100644 docs/faq/td.SimulationData.from_file.md create mode 100644 docs/faq/web.Batch.md create mode 100644 docs/faq/web.Job.md create mode 100644 docs/faq/web.abort.md create mode 100644 docs/faq/web.account.md create mode 100644 docs/faq/web.estimate_cost.md create mode 100644 docs/faq/web.get_tasks.md create mode 100644 docs/faq/web.load.md create mode 100644 docs/faq/web.run.md create mode 100644 docs/web-api.rst diff --git a/_faqs/td.SimulationData.from_file.md b/_faqs/td.SimulationData.from_file.md new file mode 100644 index 0000000..b249098 --- /dev/null +++ b/_faqs/td.SimulationData.from_file.md @@ -0,0 +1,19 @@ +--- +title: Td.simulationdata.from_file? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- +The `SimulationData.from_file` method allows you to load a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html){: .color-primary-hover} object directly from a locally saved file. It is a good alternative to the [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html){: .color-primary-hover} to avoid the time of downloading the task from the cloud. + +The file can be saved with the `SimulationData.to_file` method. For more details, check [this](https://docs.flexcompute.com/projects/tidy3d/en/latest/faq/docs/faq/how-do-i-save-and-load-the-simulationdata-object.html){: .color-primary-hover} tutorial. + +## Example +
+{% highlight python %} +python +# Load a Simulation from an HDF5 file +sim_data = SimulationData.from_file(fname="folder/sim.hdf5") +{% endhighlight %} +{% include copy-button.html %}
+ diff --git a/_faqs/web.Batch.md b/_faqs/web.Batch.md new file mode 100644 index 0000000..032b96b --- /dev/null +++ b/_faqs/web.Batch.md @@ -0,0 +1,59 @@ +--- +title: Web.batch? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- +[`Batch`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html){: .color-primary-hover} is a container for submitting, running, monitoring, and downloading **multiple simulations** on the Tidy3D cloud in one go. It’s similar to a [`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html){: .color-primary-hover}, but for a whole set of tasks (FDTD, Heat/Charge, EME, Mode solver, etc.) that run in parallel. + +## Estimating cost + +It is possible to estimate the maximum cost of the whole batch with the `Batch.estimate_cost` method. For more information on simulation cost, check [this](https://docs.flexcompute.com/projects/tidy3d/en/v2.7.6/faq/docs/faq/how-do-i-see-the-cost-of-my-simulation.html){: .color-primary-hover} article. + +## Running a batch + +The batch is run with the `Batch.run(path_dir="path_dir")` method, which saves a batch file that can be loaded later and returns a [BatchData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.BatchData.html){: .color-primary-hover} object. + +## Loading a batch + +A batch can be loaded using the `Batch.from_file` method. If the `Batch.run` method was previously used, the `Batch` object will contain information about all executed tasks, and the [BatchData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.BatchData.html){: .color-primary-hover} object can be returned with the `Batch.load` method. For more information, refer to [this](https://docs.flexcompute.com/projects/tidy3d/en/stable/faq/docs/faq/how-do-i-save-or-load-a-tidy3d-web-batch-so-i-can-work-with-it-later.html){: .color-primary-hover} article. + +## When should I use it? + +- Parameter sweeps, design-of-experiments, or any workflow with many related runs in parallel. + +## Minimal example + +
+{% highlight python %} +python +import tidy3d as td +from tidy3d.web.api.container import Batch + +# 1) Build your simulations (FDTD shown as example) +sim_a = td.Simulation(...) # define as usual +sim_b = td.Simulation(...) +sims = {"run_a": sim_a, "run_b": sim_b} + +# 2) Create a Batch +batch = Batch( + simulations=sims, + folder_name="my_sweep", +) + +# (Optional) Quick cost estimate (max, assuming full run_time) +est_fc = batch.estimate_cost(verbose=True) + +# 3) Run (upload+start+monitor+download as needed) +data = batch.run(path_dir="results") + +# 4) Iterate over results (lazy-loaded from disk, downloads on demand) +for name, sim_data in data.items(): + print(name, sim_data) + # ... analyze sim_data ... + +# 5) Access final billed cost later (after runs finish) +billed_fc = batch.real_cost(verbose=True) +print("Billed FlexCredits:", billed_fc) +{% endhighlight %} +{% include copy-button.html %}
diff --git a/_faqs/web.Job.md b/_faqs/web.Job.md new file mode 100644 index 0000000..69b9b5b --- /dev/null +++ b/_faqs/web.Job.md @@ -0,0 +1,56 @@ +--- +title: Web.job? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- +[`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html){: .color-primary-hover} is a lightweight container that represents a single simulation task on the Tidy3D cloud. It keeps track of the task ID, manages upload/start/monitor/download, and lets you save/load the job metadata without manually handling the original Simulation or task ID. + +Use Job when working with one simulation and you want to track the task ID, conveniently manage tasks (upload/start/monitor/download), and have the ability to save/restore your job state cleanly across sessions. + +Minimal Example + +
+{% highlight python %} +from tidy3d.web.api.container import Job +from tidy3d import web + +# Create a Job from an existing simulation +job = Job(simulation=simulation, task_name="my_task", folder_name="default") + +# (Optional) Estimate cost before running +est = job.estimate_cost() +print(f"Estimated max cost (FC): {est:.2f}") + +# Upload and start +job.upload() +job.start() +job.monitor() # blocks until done + +# Download and load results +sim_data = job.load(path="out/simulation.hdf5") + +# Persist the job metadata for later reuse +job.to_file("data/job.json") + +# Later (even in a new session), restore and load results: +job2 = Job.from_file("data/job.json") +sim_data2 = job2.load(path="data/simulation.hdf5") +{% endhighlight %} +{% include copy-button.html %}
+ +## Convenient methods + +upload() – Upload the job (no run yet). + +start() – Start running the job. + +monitor() – Show progress until completion. + +download(path) – Download results (.hdf5). + +load(path) – Download and load as SimulationData. + +estimate_cost(verbose=True) – Maximum FlexCredit estimate (assumes full run time). + +real_cost(verbose=True) – Final billed cost. diff --git a/_faqs/web.abort.md b/_faqs/web.abort.md new file mode 100644 index 0000000..c433cea --- /dev/null +++ b/_faqs/web.abort.md @@ -0,0 +1,24 @@ +--- +title: Web.abort? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- +The [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html){: .color-primary-hover} function allows you to stop a running task on the server and abort any associated data processing. + +When you call `abort`, the server cancels the specified task and returns a `TaskInfo` object. This object contains details about the aborted task, including its status, size, and credit usage. + +Note that the input parameter for [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html){: .color-primary-hover} is the **task_id**, not the [`Simulation`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html){: .color-primary-hover} object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html){: .color-primary-hover} method when a task is created. + + +## Example +
+{% highlight python %} +import tidy3d.web as web + +# Abort the task +task_info = web.abort(task_id) + +print("Task status:", task_info.status) +{% endhighlight %} +{% include copy-button.html %}
diff --git a/_faqs/web.account.md b/_faqs/web.account.md new file mode 100644 index 0000000..131402a --- /dev/null +++ b/_faqs/web.account.md @@ -0,0 +1,32 @@ +--- +title: Web.account? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- + +[`web.account`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.account.html){: .color-primary-hover} is a helper function that retrieves **account details** for the currently authenticated user. It shows your FlexCredit balance, expiration dates, and limits on daily free simulations. + +## Example +
+{% highlight python %} +from tidy3d import web + +# Get account information +account_info = web.account() +{% endhighlight %} +{% include copy-button.html %}
+ +Example output: + +
+{% highlight python %} +Current FlexCredit balance: 10.00 and expiration date: 2024-12-31 23:59:59. Remaining daily free simulations: 3. + +# available FlexCredit balance: +available_flexcredits = account_info.credit + +# expiration date +expiration = account_info.credit_expiration +{% endhighlight %} +{% include copy-button.html %}
diff --git a/_faqs/web.estimate_cost.md b/_faqs/web.estimate_cost.md new file mode 100644 index 0000000..101a661 --- /dev/null +++ b/_faqs/web.estimate_cost.md @@ -0,0 +1,30 @@ +--- +title: Web.estimate_cost? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- +[`web.estimate_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.estimate_cost.html){: .color-primary-hover} returns the **maximum** possible FlexCredit cost of running a simulation before it starts. This helps prevent accidentally launching overly expensive tasks. + +The real cost after running the simulation can be checked with the [`web.real_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.real_cost.html){: .color-primary-hover} method. + +Note that the input parameter for `web.estimate_cost` and `web.real_cost` is the **task_id**, not the `Simulation` object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html){: .color-primary-hover} method when a task is created. + +## Example +
+{% highlight python %} +from tidy3d import web + +# Create a job and upload it +job = web.Job(simulation=sim, task_name="job_example", verbose=True) + +# Estimate its maximum cost before running +estimated_cost = web.estimate_cost(job.task_id) +print(f"Estimated maximum cost: {estimated_cost:.3f} FlexCredits") +{% endhighlight %} +{% include copy-button.html %}
+ +A minimum simulation cost may apply, depending on task details. + +The estimate is conservative: it assumes the simulation runs its full allocated time. For more information on the real cost and how to correctly estimate the simulation time, refer to [this](https://www.flexcompute.com/tidy3d/learning-center/tidy3d-gui/Lecture-8-Run-Time-and-Shutoff/){: .color-primary-hover} tutorial. + diff --git a/_faqs/web.get_tasks.md b/_faqs/web.get_tasks.md new file mode 100644 index 0000000..9e1244c --- /dev/null +++ b/_faqs/web.get_tasks.md @@ -0,0 +1,26 @@ +--- +title: Web.get_tasks? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- +[`web.get_tasks`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.get_tasks.html){: .color-primary-hover} is a function in `tidy3d.web.api.webapi` that **retrieves metadata about past simulation tasks** from your account. It’s useful for reviewing recent runs, checking their IDs, and organizing workflows. + +## What does it do? +- Returns a list of dictionaries with task metadata (e.g., ID, status, name). +- Lets you specify how many tasks to fetch and in what order. +- Can filter tasks by folder name. + +## Example +
+{% highlight python %} +python +from tidy3d import web + +# Get the 5 most recent tasks from the default folder +tasks = web.get_tasks(num_tasks=5, order="new", folder="default") + +for t in tasks: + print(f"Task {t['name']} (ID: {t['id']}) - Status: {t['status']}") +{% endhighlight %} +{% include copy-button.html %}
diff --git a/_faqs/web.load.md b/_faqs/web.load.md new file mode 100644 index 0000000..de31e74 --- /dev/null +++ b/_faqs/web.load.md @@ -0,0 +1,28 @@ +--- +title: Web.load? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- +The [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html){: .color-primary-hover} function is a convenient utility in Tidy3D that allows you to **download and load simulation results** directly into a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html){: .color-primary-hover}, [HeatChargeSimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulationData.html){: .color-primary-hover}, or [ModeSolverData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolverData.html){: .color-primary-hover}, depending on the simulation. + +It is particularly useful for retrieving results from simulations created and run through the Tidy3D GUI or API. + + +## Parameters +- **task_id (str)**: Unique identifier for the simulation task (returned when uploading). +- **path (str)**: Local path where the results file (`.hdf5`) will be saved. Default: `"simulation_data.hdf5"`. +- **replace_existing (bool)**: If `True`, overwrites existing files at the same path. + +--- + +## Example +
+{% highlight python %} +from tidy3d import web + +sim_data = web.load(task_id, path="out/sim.hdf5", verbose=True) + +# Now you can postprocess or visualize your simulation data +{% endhighlight %} +{% include copy-button.html %}
diff --git a/_faqs/web.run.md b/_faqs/web.run.md new file mode 100644 index 0000000..5cd6dad --- /dev/null +++ b/_faqs/web.run.md @@ -0,0 +1,34 @@ +--- +title: Web.run? +date: 2025-09-11 18:22:50 +enabled: true +category: "Web API" +--- +The [`web.run`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.run.html){: .color-primary-hover} function is a high-level API method for submitting a simulation to Flexcompute’s cloud server. It automatically uploads the simulation, runs it remotely, monitors progress, downloads the results, and loads them as a data object. + +It is the general method to submit a task to the cloud, and it works with the [Simulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html){: .color-primary-hover}, [HeatChargeSimulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulation.html){: .color-primary-hover}, [web.Batch](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html){: .color-primary-hover}, and [ModeSolver](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolver.html){: .color-primary-hover} objects. + + +## Example +
+{% highlight python %} +from tidy3d import web + +# Submit and run the simulation +sim_data = web.run( + simulation, + task_name="my_task", + path="out/sim.hdf5" +) +{% endhighlight %} +{% include copy-button.html %}
+ +The `web.run` function requires the `task_name` string. + +Optional arguments: + +`folder_name`: Where to store the task in the web UI (default: "default"). + +`path`: Local file path to save results (.hdf5). + +`verbose`: If True, shows progress (default). diff --git a/docs/faq/td.SimulationData.from_file.md b/docs/faq/td.SimulationData.from_file.md new file mode 100644 index 0000000..8edbfad --- /dev/null +++ b/docs/faq/td.SimulationData.from_file.md @@ -0,0 +1,22 @@ +# Td.simulationdata.from_file? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + +The `SimulationData.from_file` method allows you to load a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html) object directly from a locally saved file. It is a good alternative to the [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html) to avoid the time of downloading the task from the cloud. + +The file can be saved with the `SimulationData.to_file` method. For more details, check [this](https://docs.flexcompute.com/projects/tidy3d/en/latest/faq/docs/faq/how-do-i-save-and-load-the-simulationdata-object.html) tutorial. + +## Example + + +```python +python +# Load a Simulation from an HDF5 file +sim_data = SimulationData.from_file(fname="folder/sim.hdf5") +``` + + + diff --git a/docs/faq/web.Batch.md b/docs/faq/web.Batch.md new file mode 100644 index 0000000..3ace2ac --- /dev/null +++ b/docs/faq/web.Batch.md @@ -0,0 +1,62 @@ +# Web.batch? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + +[`Batch`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html) is a container for submitting, running, monitoring, and downloading **multiple simulations** on the Tidy3D cloud in one go. It’s similar to a [`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html), but for a whole set of tasks (FDTD, Heat/Charge, EME, Mode solver, etc.) that run in parallel. + +## Estimating cost + +It is possible to estimate the maximum cost of the whole batch with the `Batch.estimate_cost` method. For more information on simulation cost, check [this](https://docs.flexcompute.com/projects/tidy3d/en/v2.7.6/faq/docs/faq/how-do-i-see-the-cost-of-my-simulation.html) article. + +## Running a batch + +The batch is run with the `Batch.run(path_dir="path_dir")` method, which saves a batch file that can be loaded later and returns a [BatchData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.BatchData.html) object. + +## Loading a batch + +A batch can be loaded using the `Batch.from_file` method. If the `Batch.run` method was previously used, the `Batch` object will contain information about all executed tasks, and the [BatchData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.BatchData.html) object can be returned with the `Batch.load` method. For more information, refer to [this](https://docs.flexcompute.com/projects/tidy3d/en/stable/faq/docs/faq/how-do-i-save-or-load-a-tidy3d-web-batch-so-i-can-work-with-it-later.html) article. + +## When should I use it? + +- Parameter sweeps, design-of-experiments, or any workflow with many related runs in parallel. + +## Minimal example + + + +```python +python +import tidy3d as td +from tidy3d.web.api.container import Batch + +# 1) Build your simulations (FDTD shown as example) +sim_a = td.Simulation(...) # define as usual +sim_b = td.Simulation(...) +sims = {"run_a": sim_a, "run_b": sim_b} + +# 2) Create a Batch +batch = Batch( + simulations=sims, + folder_name="my_sweep", +) + +# (Optional) Quick cost estimate (max, assuming full run_time) +est_fc = batch.estimate_cost(verbose=True) + +# 3) Run (upload+start+monitor+download as needed) +data = batch.run(path_dir="results") + +# 4) Iterate over results (lazy-loaded from disk, downloads on demand) +for name, sim_data in data.items(): + print(name, sim_data) + # ... analyze sim_data ... + +# 5) Access final billed cost later (after runs finish) +billed_fc = batch.real_cost(verbose=True) +print("Billed FlexCredits:", billed_fc) +``` + + diff --git a/docs/faq/web.Job.md b/docs/faq/web.Job.md new file mode 100644 index 0000000..9430b80 --- /dev/null +++ b/docs/faq/web.Job.md @@ -0,0 +1,59 @@ +# Web.job? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + +[`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html) is a lightweight container that represents a single simulation task on the Tidy3D cloud. It keeps track of the task ID, manages upload/start/monitor/download, and lets you save/load the job metadata without manually handling the original Simulation or task ID. + +Use Job when working with one simulation and you want to track the task ID, conveniently manage tasks (upload/start/monitor/download), and have the ability to save/restore your job state cleanly across sessions. + +Minimal Example + + + +```python +from tidy3d.web.api.container import Job +from tidy3d import web + +# Create a Job from an existing simulation +job = Job(simulation=simulation, task_name="my_task", folder_name="default") + +# (Optional) Estimate cost before running +est = job.estimate_cost() +print(f"Estimated max cost (FC): {est:.2f}") + +# Upload and start +job.upload() +job.start() +job.monitor() # blocks until done + +# Download and load results +sim_data = job.load(path="out/simulation.hdf5") + +# Persist the job metadata for later reuse +job.to_file("data/job.json") + +# Later (even in a new session), restore and load results: +job2 = Job.from_file("data/job.json") +sim_data2 = job2.load(path="data/simulation.hdf5") +``` + + + +## Convenient methods + +upload() – Upload the job (no run yet). + +start() – Start running the job. + +monitor() – Show progress until completion. + +download(path) – Download results (.hdf5). + +load(path) – Download and load as SimulationData. + +estimate_cost(verbose=True) – Maximum FlexCredit estimate (assumes full run time). + +real_cost(verbose=True) – Final billed cost. diff --git a/docs/faq/web.abort.md b/docs/faq/web.abort.md new file mode 100644 index 0000000..17a43a7 --- /dev/null +++ b/docs/faq/web.abort.md @@ -0,0 +1,27 @@ +# Web.abort? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + +The [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html) function allows you to stop a running task on the server and abort any associated data processing. + +When you call `abort`, the server cancels the specified task and returns a `TaskInfo` object. This object contains details about the aborted task, including its status, size, and credit usage. + +Note that the input parameter for [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html) is the **task_id**, not the [`Simulation`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html) object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html) method when a task is created. + + +## Example + + +```python +import tidy3d.web as web + +# Abort the task +task_info = web.abort(task_id) + +print("Task status:", task_info.status) +``` + + diff --git a/docs/faq/web.account.md b/docs/faq/web.account.md new file mode 100644 index 0000000..57e336f --- /dev/null +++ b/docs/faq/web.account.md @@ -0,0 +1,37 @@ +# Web.account? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + + +[`web.account`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.account.html) is a helper function that retrieves **account details** for the currently authenticated user. It shows your FlexCredit balance, expiration dates, and limits on daily free simulations. + +## Example + + +```python +from tidy3d import web + +# Get account information +account_info = web.account() +``` + + + +Example output: + + + +```python +Current FlexCredit balance: 10.00 and expiration date: 2024-12-31 23:59:59. Remaining daily free simulations: 3. + +# available FlexCredit balance: +available_flexcredits = account_info.credit + +# expiration date +expiration = account_info.credit_expiration +``` + + diff --git a/docs/faq/web.estimate_cost.md b/docs/faq/web.estimate_cost.md new file mode 100644 index 0000000..a749028 --- /dev/null +++ b/docs/faq/web.estimate_cost.md @@ -0,0 +1,33 @@ +# Web.estimate_cost? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + +[`web.estimate_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.estimate_cost.html) returns the **maximum** possible FlexCredit cost of running a simulation before it starts. This helps prevent accidentally launching overly expensive tasks. + +The real cost after running the simulation can be checked with the [`web.real_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.real_cost.html) method. + +Note that the input parameter for `web.estimate_cost` and `web.real_cost` is the **task_id**, not the `Simulation` object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html) method when a task is created. + +## Example + + +```python +from tidy3d import web + +# Create a job and upload it +job = web.Job(simulation=sim, task_name="job_example", verbose=True) + +# Estimate its maximum cost before running +estimated_cost = web.estimate_cost(job.task_id) +print(f"Estimated maximum cost: {estimated_cost:.3f} FlexCredits") +``` + + + +A minimum simulation cost may apply, depending on task details. + +The estimate is conservative: it assumes the simulation runs its full allocated time. For more information on the real cost and how to correctly estimate the simulation time, refer to [this](https://www.flexcompute.com/tidy3d/learning-center/tidy3d-gui/Lecture-8-Run-Time-and-Shutoff/) tutorial. + diff --git a/docs/faq/web.get_tasks.md b/docs/faq/web.get_tasks.md new file mode 100644 index 0000000..2692792 --- /dev/null +++ b/docs/faq/web.get_tasks.md @@ -0,0 +1,29 @@ +# Web.get_tasks? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + +[`web.get_tasks`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.get_tasks.html) is a function in `tidy3d.web.api.webapi` that **retrieves metadata about past simulation tasks** from your account. It’s useful for reviewing recent runs, checking their IDs, and organizing workflows. + +## What does it do? +- Returns a list of dictionaries with task metadata (e.g., ID, status, name). +- Lets you specify how many tasks to fetch and in what order. +- Can filter tasks by folder name. + +## Example + + +```python +python +from tidy3d import web + +# Get the 5 most recent tasks from the default folder +tasks = web.get_tasks(num_tasks=5, order="new", folder="default") + +for t in tasks: + print(f"Task {t['name']} (ID: {t['id']}) - Status: {t['status']}") +``` + + diff --git a/docs/faq/web.load.md b/docs/faq/web.load.md new file mode 100644 index 0000000..4dadf2f --- /dev/null +++ b/docs/faq/web.load.md @@ -0,0 +1,31 @@ +# Web.load? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + +The [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html) function is a convenient utility in Tidy3D that allows you to **download and load simulation results** directly into a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html), [HeatChargeSimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulationData.html), or [ModeSolverData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolverData.html), depending on the simulation. + +It is particularly useful for retrieving results from simulations created and run through the Tidy3D GUI or API. + + +## Parameters +- **task_id (str)**: Unique identifier for the simulation task (returned when uploading). +- **path (str)**: Local path where the results file (`.hdf5`) will be saved. Default: `"simulation_data.hdf5"`. +- **replace_existing (bool)**: If `True`, overwrites existing files at the same path. + +--- + +## Example + + +```python +from tidy3d import web + +sim_data = web.load(task_id, path="out/sim.hdf5", verbose=True) + +# Now you can postprocess or visualize your simulation data +``` + + diff --git a/docs/faq/web.run.md b/docs/faq/web.run.md new file mode 100644 index 0000000..915aba4 --- /dev/null +++ b/docs/faq/web.run.md @@ -0,0 +1,37 @@ +# Web.run? + +| Date | Category | +|------------|-------------| +| 2025-09-11 18:22:50 | Web API | + + +The [`web.run`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.run.html) function is a high-level API method for submitting a simulation to Flexcompute’s cloud server. It automatically uploads the simulation, runs it remotely, monitors progress, downloads the results, and loads them as a data object. + +It is the general method to submit a task to the cloud, and it works with the [Simulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html), [HeatChargeSimulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulation.html), [web.Batch](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html), and [ModeSolver](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolver.html) objects. + + +## Example + + +```python +from tidy3d import web + +# Submit and run the simulation +sim_data = web.run( + simulation, + task_name="my_task", + path="out/sim.hdf5" +) +``` + + + +The `web.run` function requires the `task_name` string. + +Optional arguments: + +`folder_name`: Where to store the task in the web UI (default: "default"). + +`path`: Local file path to save results (.hdf5). + +`verbose`: If True, shows progress (default). diff --git a/docs/index.rst b/docs/index.rst index 31f6d4c..1c8fe77 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,3 +24,4 @@ FAQ |:mag_right:| sources structures symmetry + web-api diff --git a/docs/web-api.rst b/docs/web-api.rst new file mode 100644 index 0000000..b4da2b6 --- /dev/null +++ b/docs/web-api.rst @@ -0,0 +1,15 @@ +Web API +======= + +.. toctree:: + :maxdepth: 2 + + faq/web.Job.md + faq/web.run.md + faq/web.get_tasks.md + faq/web.abort.md + faq/web.Batch.md + faq/web.account.md + faq/web.estimate_cost.md + faq/td.SimulationData.from_file.md + faq/web.load.md diff --git a/faq_categories.json b/faq_categories.json index bbd3f34..53c0755 100644 --- a/faq_categories.json +++ b/faq_categories.json @@ -332,5 +332,20 @@ "_faqs/how-do-i-set-a-charge-simulation.md", "_faqs/how-can-i-set-charge-boundary-conditions.md" ] + }, + { + "category": "Web API", + "id": "web-api", + "faqs": [ + "_faqs/web.Job.md", + "_faqs/web.run.md", + "_faqs/web.get_tasks.md", + "_faqs/web.abort.md", + "_faqs/web.Batch.md", + "_faqs/web.account.md", + "_faqs/web.estimate_cost.md", + "_faqs/td.SimulationData.from_file.md", + "_faqs/web.load.md" + ] } ] \ No newline at end of file From 5129c1c9744d52ca53cc4b663b0730b43d37fa4e Mon Sep 17 00:00:00 2001 From: "filipe@flexcompute.com" Date: Tue, 16 Sep 2025 13:51:00 -0300 Subject: [PATCH 2/2] comments --- _faqs/td.SimulationData.from_file.md | 4 ++-- _faqs/web.Batch.md | 4 ++-- _faqs/web.Job.md | 4 ++-- _faqs/web.abort.md | 13 +++++-------- _faqs/web.account.md | 2 +- _faqs/web.estimate_cost.md | 8 ++++---- _faqs/web.get_tasks.md | 2 +- _faqs/web.load.md | 8 +++++++- _faqs/web.run.md | 6 +++--- docs/faq/td.SimulationData.from_file.md | 4 ++-- docs/faq/web.Batch.md | 4 ++-- docs/faq/web.Job.md | 4 ++-- docs/faq/web.abort.md | 13 +++++-------- docs/faq/web.account.md | 2 +- docs/faq/web.estimate_cost.md | 8 ++++---- docs/faq/web.get_tasks.md | 2 +- docs/faq/web.load.md | 8 +++++++- docs/faq/web.run.md | 6 +++--- 18 files changed, 54 insertions(+), 48 deletions(-) diff --git a/_faqs/td.SimulationData.from_file.md b/_faqs/td.SimulationData.from_file.md index b249098..d24453b 100644 --- a/_faqs/td.SimulationData.from_file.md +++ b/_faqs/td.SimulationData.from_file.md @@ -1,10 +1,10 @@ --- title: Td.simulationdata.from_file? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- -The `SimulationData.from_file` method allows you to load a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html){: .color-primary-hover} object directly from a locally saved file. It is a good alternative to the [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html){: .color-primary-hover} to avoid the time of downloading the task from the cloud. +The `SimulationData.from_file` method allows you to load a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html){: .color-primary-hover} object directly from a locally saved file. It is a good alternative to the [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html){: .color-primary-hover} to avoid the time of downloading the simulation from the cloud. The file can be saved with the `SimulationData.to_file` method. For more details, check [this](https://docs.flexcompute.com/projects/tidy3d/en/latest/faq/docs/faq/how-do-i-save-and-load-the-simulationdata-object.html){: .color-primary-hover} tutorial. diff --git a/_faqs/web.Batch.md b/_faqs/web.Batch.md index 032b96b..e58824f 100644 --- a/_faqs/web.Batch.md +++ b/_faqs/web.Batch.md @@ -1,10 +1,10 @@ --- title: Web.batch? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- -[`Batch`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html){: .color-primary-hover} is a container for submitting, running, monitoring, and downloading **multiple simulations** on the Tidy3D cloud in one go. It’s similar to a [`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html){: .color-primary-hover}, but for a whole set of tasks (FDTD, Heat/Charge, EME, Mode solver, etc.) that run in parallel. +[`Batch`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html){: .color-primary-hover} is a container for submitting, running, monitoring, and downloading **multiple simulations** on the Tidy3D cloud in one go. It’s similar to a [`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html){: .color-primary-hover}, but for a whole set of simulations (FDTD, Heat/Charge, EME, Mode solver, etc.) that run in parallel. ## Estimating cost diff --git a/_faqs/web.Job.md b/_faqs/web.Job.md index 69b9b5b..1961289 100644 --- a/_faqs/web.Job.md +++ b/_faqs/web.Job.md @@ -1,12 +1,12 @@ --- title: Web.job? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- [`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html){: .color-primary-hover} is a lightweight container that represents a single simulation task on the Tidy3D cloud. It keeps track of the task ID, manages upload/start/monitor/download, and lets you save/load the job metadata without manually handling the original Simulation or task ID. -Use Job when working with one simulation and you want to track the task ID, conveniently manage tasks (upload/start/monitor/download), and have the ability to save/restore your job state cleanly across sessions. +Use Job when working with one simulation and you want to track the task ID, conveniently manage simulations (upload/start/monitor/download), and have the ability to save/restore your job state cleanly across sessions. Minimal Example diff --git a/_faqs/web.abort.md b/_faqs/web.abort.md index c433cea..b33a2bc 100644 --- a/_faqs/web.abort.md +++ b/_faqs/web.abort.md @@ -1,24 +1,21 @@ --- title: Web.abort? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- -The [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html){: .color-primary-hover} function allows you to stop a running task on the server and abort any associated data processing. - -When you call `abort`, the server cancels the specified task and returns a `TaskInfo` object. This object contains details about the aborted task, including its status, size, and credit usage. - -Note that the input parameter for [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html){: .color-primary-hover} is the **task_id**, not the [`Simulation`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html){: .color-primary-hover} object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html){: .color-primary-hover} method when a task is created. +The [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html){: .color-primary-hover} function allows you to stop a running simulation on the server and abort any associated data processing. Note that simply stopping the Python script or killing the kernel **won’t** stop the simulation in the cloud. +When you call `abort`, the server cancels the specified simulation and returns a `TaskInfo` object. This object contains details about the aborted simulation, including its status, size, and credit usage. The input parameter for [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html){: .color-primary-hover} is the **task_id**, not the [`Simulation`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html){: .color-primary-hover} object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html){: .color-primary-hover} method when a simulation is created. ## Example
{% highlight python %} import tidy3d.web as web -# Abort the task +# Abort the simulation task_info = web.abort(task_id) -print("Task status:", task_info.status) +print("Simulation status:", task_info.status) {% endhighlight %} {% include copy-button.html %}
diff --git a/_faqs/web.account.md b/_faqs/web.account.md index 131402a..82d5534 100644 --- a/_faqs/web.account.md +++ b/_faqs/web.account.md @@ -1,6 +1,6 @@ --- title: Web.account? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- diff --git a/_faqs/web.estimate_cost.md b/_faqs/web.estimate_cost.md index 101a661..465d9e4 100644 --- a/_faqs/web.estimate_cost.md +++ b/_faqs/web.estimate_cost.md @@ -1,14 +1,14 @@ --- title: Web.estimate_cost? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- -[`web.estimate_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.estimate_cost.html){: .color-primary-hover} returns the **maximum** possible FlexCredit cost of running a simulation before it starts. This helps prevent accidentally launching overly expensive tasks. +[`web.estimate_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.estimate_cost.html){: .color-primary-hover} returns the **maximum** possible FlexCredit cost of running a simulation before it starts. This helps prevent accidentally launching overly expensive simulations. The real cost after running the simulation can be checked with the [`web.real_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.real_cost.html){: .color-primary-hover} method. -Note that the input parameter for `web.estimate_cost` and `web.real_cost` is the **task_id**, not the `Simulation` object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html){: .color-primary-hover} method when a task is created. +Note that the input parameter for `web.estimate_cost` and `web.real_cost` is the **task_id**, not the `Simulation` object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html){: .color-primary-hover} method when a simulation is created. ## Example
@@ -24,7 +24,7 @@ print(f"Estimated maximum cost: {estimated_cost:.3f} FlexCredits") {% endhighlight %} {% include copy-button.html %}
-A minimum simulation cost may apply, depending on task details. +A minimum simulation cost may apply, depending on simulation details. The estimate is conservative: it assumes the simulation runs its full allocated time. For more information on the real cost and how to correctly estimate the simulation time, refer to [this](https://www.flexcompute.com/tidy3d/learning-center/tidy3d-gui/Lecture-8-Run-Time-and-Shutoff/){: .color-primary-hover} tutorial. diff --git a/_faqs/web.get_tasks.md b/_faqs/web.get_tasks.md index 9e1244c..d0bde1c 100644 --- a/_faqs/web.get_tasks.md +++ b/_faqs/web.get_tasks.md @@ -1,6 +1,6 @@ --- title: Web.get_tasks? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- diff --git a/_faqs/web.load.md b/_faqs/web.load.md index de31e74..5ba6a9b 100644 --- a/_faqs/web.load.md +++ b/_faqs/web.load.md @@ -1,6 +1,6 @@ --- title: Web.load? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- @@ -14,6 +14,12 @@ It is particularly useful for retrieving results from simulations created and ru - **path (str)**: Local path where the results file (`.hdf5`) will be saved. Default: `"simulation_data.hdf5"`. - **replace_existing (bool)**: If `True`, overwrites existing files at the same path. +## Notes + +The *task_id* can be obtained in the GUI under the **Simulation Assets** tab, or from the **Action** menu on the [folder](https://tidy3d.simulation.cloud/home){: .color-primary-hover} page. + +For more information and templates on loading and visualizing data using `web.load`, see [this example](None){: .color-primary-hover}. + --- ## Example diff --git a/_faqs/web.run.md b/_faqs/web.run.md index 5cd6dad..58505ff 100644 --- a/_faqs/web.run.md +++ b/_faqs/web.run.md @@ -1,12 +1,12 @@ --- title: Web.run? -date: 2025-09-11 18:22:50 +date: 2025-09-16 13:50:36 enabled: true category: "Web API" --- The [`web.run`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.run.html){: .color-primary-hover} function is a high-level API method for submitting a simulation to Flexcompute’s cloud server. It automatically uploads the simulation, runs it remotely, monitors progress, downloads the results, and loads them as a data object. -It is the general method to submit a task to the cloud, and it works with the [Simulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html){: .color-primary-hover}, [HeatChargeSimulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulation.html){: .color-primary-hover}, [web.Batch](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html){: .color-primary-hover}, and [ModeSolver](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolver.html){: .color-primary-hover} objects. +It is the general method to submit a simulation to the cloud, and it works with the [Simulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html){: .color-primary-hover}, [HeatChargeSimulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulation.html){: .color-primary-hover}, [web.Batch](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html){: .color-primary-hover}, and [ModeSolver](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolver.html){: .color-primary-hover} objects. ## Example @@ -27,7 +27,7 @@ The `web.run` function requires the `task_name` string. Optional arguments: -`folder_name`: Where to store the task in the web UI (default: "default"). +`folder_name`: Where to store the simulation in the web UI (default: "default"). `path`: Local file path to save results (.hdf5). diff --git a/docs/faq/td.SimulationData.from_file.md b/docs/faq/td.SimulationData.from_file.md index 8edbfad..d40f0c8 100644 --- a/docs/faq/td.SimulationData.from_file.md +++ b/docs/faq/td.SimulationData.from_file.md @@ -2,10 +2,10 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | -The `SimulationData.from_file` method allows you to load a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html) object directly from a locally saved file. It is a good alternative to the [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html) to avoid the time of downloading the task from the cloud. +The `SimulationData.from_file` method allows you to load a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html) object directly from a locally saved file. It is a good alternative to the [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html) to avoid the time of downloading the simulation from the cloud. The file can be saved with the `SimulationData.to_file` method. For more details, check [this](https://docs.flexcompute.com/projects/tidy3d/en/latest/faq/docs/faq/how-do-i-save-and-load-the-simulationdata-object.html) tutorial. diff --git a/docs/faq/web.Batch.md b/docs/faq/web.Batch.md index 3ace2ac..0f118e4 100644 --- a/docs/faq/web.Batch.md +++ b/docs/faq/web.Batch.md @@ -2,10 +2,10 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | -[`Batch`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html) is a container for submitting, running, monitoring, and downloading **multiple simulations** on the Tidy3D cloud in one go. It’s similar to a [`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html), but for a whole set of tasks (FDTD, Heat/Charge, EME, Mode solver, etc.) that run in parallel. +[`Batch`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html) is a container for submitting, running, monitoring, and downloading **multiple simulations** on the Tidy3D cloud in one go. It’s similar to a [`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html), but for a whole set of simulations (FDTD, Heat/Charge, EME, Mode solver, etc.) that run in parallel. ## Estimating cost diff --git a/docs/faq/web.Job.md b/docs/faq/web.Job.md index 9430b80..370bf8f 100644 --- a/docs/faq/web.Job.md +++ b/docs/faq/web.Job.md @@ -2,12 +2,12 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | [`web.Job`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Job.html) is a lightweight container that represents a single simulation task on the Tidy3D cloud. It keeps track of the task ID, manages upload/start/monitor/download, and lets you save/load the job metadata without manually handling the original Simulation or task ID. -Use Job when working with one simulation and you want to track the task ID, conveniently manage tasks (upload/start/monitor/download), and have the ability to save/restore your job state cleanly across sessions. +Use Job when working with one simulation and you want to track the task ID, conveniently manage simulations (upload/start/monitor/download), and have the ability to save/restore your job state cleanly across sessions. Minimal Example diff --git a/docs/faq/web.abort.md b/docs/faq/web.abort.md index 17a43a7..cb4126c 100644 --- a/docs/faq/web.abort.md +++ b/docs/faq/web.abort.md @@ -2,15 +2,12 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | -The [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html) function allows you to stop a running task on the server and abort any associated data processing. - -When you call `abort`, the server cancels the specified task and returns a `TaskInfo` object. This object contains details about the aborted task, including its status, size, and credit usage. - -Note that the input parameter for [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html) is the **task_id**, not the [`Simulation`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html) object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html) method when a task is created. +The [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html) function allows you to stop a running simulation on the server and abort any associated data processing. Note that simply stopping the Python script or killing the kernel **won’t** stop the simulation in the cloud. +When you call `abort`, the server cancels the specified simulation and returns a `TaskInfo` object. This object contains details about the aborted simulation, including its status, size, and credit usage. The input parameter for [`web.abort`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.abort.html) is the **task_id**, not the [`Simulation`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html) object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html) method when a simulation is created. ## Example @@ -18,10 +15,10 @@ Note that the input parameter for [`web.abort`](https://docs.flexcompute.com/pro ```python import tidy3d.web as web -# Abort the task +# Abort the simulation task_info = web.abort(task_id) -print("Task status:", task_info.status) +print("Simulation status:", task_info.status) ``` diff --git a/docs/faq/web.account.md b/docs/faq/web.account.md index 57e336f..f220700 100644 --- a/docs/faq/web.account.md +++ b/docs/faq/web.account.md @@ -2,7 +2,7 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | diff --git a/docs/faq/web.estimate_cost.md b/docs/faq/web.estimate_cost.md index a749028..9526f8b 100644 --- a/docs/faq/web.estimate_cost.md +++ b/docs/faq/web.estimate_cost.md @@ -2,14 +2,14 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | -[`web.estimate_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.estimate_cost.html) returns the **maximum** possible FlexCredit cost of running a simulation before it starts. This helps prevent accidentally launching overly expensive tasks. +[`web.estimate_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.estimate_cost.html) returns the **maximum** possible FlexCredit cost of running a simulation before it starts. This helps prevent accidentally launching overly expensive simulations. The real cost after running the simulation can be checked with the [`web.real_cost`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.real_cost.html) method. -Note that the input parameter for `web.estimate_cost` and `web.real_cost` is the **task_id**, not the `Simulation` object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html) method when a task is created. +Note that the input parameter for `web.estimate_cost` and `web.real_cost` is the **task_id**, not the `Simulation` object. This ID is returned by the [`web.upload`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.upload.html) method when a simulation is created. ## Example @@ -27,7 +27,7 @@ print(f"Estimated maximum cost: {estimated_cost:.3f} FlexCredits") -A minimum simulation cost may apply, depending on task details. +A minimum simulation cost may apply, depending on simulation details. The estimate is conservative: it assumes the simulation runs its full allocated time. For more information on the real cost and how to correctly estimate the simulation time, refer to [this](https://www.flexcompute.com/tidy3d/learning-center/tidy3d-gui/Lecture-8-Run-Time-and-Shutoff/) tutorial. diff --git a/docs/faq/web.get_tasks.md b/docs/faq/web.get_tasks.md index 2692792..232d2be 100644 --- a/docs/faq/web.get_tasks.md +++ b/docs/faq/web.get_tasks.md @@ -2,7 +2,7 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | [`web.get_tasks`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.get_tasks.html) is a function in `tidy3d.web.api.webapi` that **retrieves metadata about past simulation tasks** from your account. It’s useful for reviewing recent runs, checking their IDs, and organizing workflows. diff --git a/docs/faq/web.load.md b/docs/faq/web.load.md index 4dadf2f..6f10f7b 100644 --- a/docs/faq/web.load.md +++ b/docs/faq/web.load.md @@ -2,7 +2,7 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | The [`web.load`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.load.html) function is a convenient utility in Tidy3D that allows you to **download and load simulation results** directly into a [SimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.components.data.sim_data.SimulationData.html), [HeatChargeSimulationData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulationData.html), or [ModeSolverData](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolverData.html), depending on the simulation. @@ -15,6 +15,12 @@ It is particularly useful for retrieving results from simulations created and ru - **path (str)**: Local path where the results file (`.hdf5`) will be saved. Default: `"simulation_data.hdf5"`. - **replace_existing (bool)**: If `True`, overwrites existing files at the same path. +## Notes + +The *task_id* can be obtained in the GUI under the **Simulation Assets** tab, or from the **Action** menu on the [folder](https://tidy3d.simulation.cloud/home) page. + +For more information and templates on loading and visualizing data using `web.load`, see [this example](None). + --- ## Example diff --git a/docs/faq/web.run.md b/docs/faq/web.run.md index 915aba4..0a15eb5 100644 --- a/docs/faq/web.run.md +++ b/docs/faq/web.run.md @@ -2,12 +2,12 @@ | Date | Category | |------------|-------------| -| 2025-09-11 18:22:50 | Web API | +| 2025-09-16 13:50:36 | Web API | The [`web.run`](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.webapi.run.html) function is a high-level API method for submitting a simulation to Flexcompute’s cloud server. It automatically uploads the simulation, runs it remotely, monitors progress, downloads the results, and loads them as a data object. -It is the general method to submit a task to the cloud, and it works with the [Simulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html), [HeatChargeSimulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulation.html), [web.Batch](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html), and [ModeSolver](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolver.html) objects. +It is the general method to submit a simulation to the cloud, and it works with the [Simulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.Simulation.html), [HeatChargeSimulation](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.HeatChargeSimulation.html), [web.Batch](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.api.container.Batch.html), and [ModeSolver](https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.plugins.mode.ModeSolver.html) objects. ## Example @@ -30,7 +30,7 @@ The `web.run` function requires the `task_name` string. Optional arguments: -`folder_name`: Where to store the task in the web UI (default: "default"). +`folder_name`: Where to store the simulation in the web UI (default: "default"). `path`: Local file path to save results (.hdf5).