add Web API FAQ (#48)

add Web API FAQ

Author: FilipeFcp

_faqs/td.SimulationData.from_file.md

@@ -0,0 +1,19 @@
+---
+title: Td.simulationdata.from_file?
+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 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.
+
+## Example
+<div markdown class="code-snippet">
+{% highlight python %}
+python
+# Load a Simulation from an HDF5 file
+sim_data = SimulationData.from_file(fname="folder/sim.hdf5")
+{% endhighlight %}
+{% include copy-button.html %}</div>
+

_faqs/web.Batch.md

@@ -0,0 +1,59 @@
+---
+title: Web.batch?
+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 simulations (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
+
+<div markdown class="code-snippet">
+{% 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 %}</div>

_faqs/web.Job.md

@@ -0,0 +1,56 @@
+---
+title: Web.job?
+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 simulations (upload/start/monitor/download), and have the ability to save/restore your job state cleanly across sessions.
+
+Minimal Example
+
+<div markdown class="code-snippet">
+{% 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 %}</div>
+
+## 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.

_faqs/web.abort.md

@@ -0,0 +1,21 @@
+---
+title: Web.abort?
+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 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
+<div markdown class="code-snippet">
+{% highlight python %}
+import tidy3d.web as web
+
+# Abort the simulation
+task_info = web.abort(task_id)
+
+print("Simulation status:", task_info.status)
+{% endhighlight %}
+{% include copy-button.html %}</div>

_faqs/web.account.md

@@ -0,0 +1,32 @@
+---
+title: Web.account?
+date: 2025-09-16 13:50:36
+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
+<div markdown class="code-snippet">
+{% highlight python %}
+from tidy3d import web
+
+# Get account information
+account_info = web.account()
+{% endhighlight %}
+{% include copy-button.html %}</div>
+
+Example output:
+
+<div markdown class="code-snippet">
+{% 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 %}</div>

_faqs/web.estimate_cost.md

@@ -0,0 +1,30 @@
+---
+title: Web.estimate_cost?
+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 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 simulation is created.
+
+## Example
+<div markdown class="code-snippet">
+{% 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 %}</div>
+
+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.
+

_faqs/web.get_tasks.md

@@ -0,0 +1,26 @@
+---
+title: Web.get_tasks?
+date: 2025-09-16 13:50:36
+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
+<div markdown class="code-snippet">
+{% 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 %}</div>

_faqs/web.load.md

@@ -0,0 +1,34 @@
+---
+title: Web.load?
+date: 2025-09-16 13:50:36
+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.
+
+## 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
+<div markdown class="code-snippet">
+{% 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 %}</div>

_faqs/web.run.md

@@ -0,0 +1,34 @@
+---
+title: Web.run?
+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 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
+<div markdown class="code-snippet">
+{% 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 %}</div>
+
+The `web.run` function requires the `task_name` string.
+
+Optional arguments:
+
+`folder_name`: Where to store the simulation in the web UI (default: "default").
+
+`path`: Local file path to save results (.hdf5).
+
+`verbose`: If True, shows progress (default).

docs/faq/td.SimulationData.from_file.md

@@ -0,0 +1,22 @@
+# Td.simulationdata.from_file?
+
+| Date       | Category    |
+|------------|-------------|
+| 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 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.
+
+## Example
+
+
+```python
+python
+# Load a Simulation from an HDF5 file
+sim_data = SimulationData.from_file(fname="folder/sim.hdf5")
+```
+
+
+