Note: the cost of running the entire notebook is larger than 1 FlexCredit.

In this notebook, we will show an example of using tidy3d to evaluate device performance over a set of many design parameters.

This example will also provide a walkthrough of Tidy3D's Job and Batch features for managing both individual simulations and sets of simulations.

Note: as of version 1.8, the tidy3d.web.run_async function handles the same functionality as the batch, with a simpler syntax. As such, it could be a good alternative for parameter scan depending on how your script is set up.

Additionally, we will show how to do this problem using tidy3d.plugins.design, which provides convenience methods for defining and running parameter scans, which has a full tutorial here.

For demonstration, we look at the splitting ratio of a directional coupler as we vary the coupling length between two waveguides. The sidewall of the waveguides is slanted, deviating from the vertical direction by sidewall_angle.

Setup¶

First we set up some global parameters

Define waveguide bends and coupler¶

Here is where we define our directional coupler shape programmatically in terms of the geometric parameters

Create Simulation and Submit Job¶

The following function creates a tidy3d simulation object for a set of design parameters.

Note that the simulation has not been run yet, just created.

Inspect Simulation¶

Let's create and inspect a single simulation to make sure it was defined correctly before doing the full scan. The sidewalls of the waveguides deviate from the vertical direction by 30 degrees. We also add an in-plane field monitor to have a look at the field evolution in this one simulation. We will not use such a monitor in the batch to avoid storing unnecessarily large amounts of data.

Create and Submit Job¶

The Job object provides an interface for managing simulations.

job = Job(simulation) will create a job and upload the simulation to our server to run.

Then, one may call various methods of job to monitor progress, download results, and get information.

For more information, refer to the API reference.

Postprocessing¶

The following function takes a completed simulation (with data loaded into it) and computes the quantities of interest.

For this case, we measure both the total transmission in the right ports and also the ratio of power between the top and bottom ports.

1D Parameter Scan¶

Now we will scan through the coupling length parameter to see the effect on splitting ratio.

To do this, we will create a list of simulations corresponding to each parameter combination.

We will use this list to create a Batch object, which has similar functionality to Job but allows one to manage a set of jobs.

First, we create arrays to store the input and output values.

Create Batch¶

We now create our list of simulations and use them to initialize a Batch.

For more information, refer to the API reference.

Monitor Batch¶

Here we can perform real-time monitoring of how many of the jobs in the batch have completed.

Load and Visualize Results¶

Finally, we can compute the output quantities and load them into the arrays we created initially.

Then we may plot the results.

Final Remarks¶

Batches provide some other convenient functionality for managing large numbers of jobs.

For example, one can save the batch information to file and load the batch at a later time, if needing to disconnect from the service while the jobs are running.

For more reference, refer to our documentation.

Using the design Plugin¶

In Tidy3D version 2.6.0, we introduced a Design plugin, which allows users to programmatically define and run their parameter scans while also providing a convenient container for managing the resulting data.

For more details, please refer to our full tutorial on the Design plugin.

We import the plugin through tidy3d.plugins.design below.

Then we define our sweep dimensions as tdd.ParameterFloat instances and give them each a range.

Note: we need to ensure that the name arguments match the function argument names in our make_sim() function, which we will use to construct the simulations for the parameter scan.

For this example, we will do a grid search over these points, which we can define a tdd.MethodGrid and then combine everything into a tdd.DesignSpace.

To run the sweep, we need to pass the design space our evaluation function. Here we will define it through pre and post processing functions, which enables the design plugin to take advantage of parallelism to perform Batch processing under the hood.

The functions make_sim and measure_transmission already almost work perfectly as pre and post processing functions. We'll just wrap measure_transmission to return a dictionary of the amplitudes, so that the dictionary keys can be used to label the outputs in the resulting dataset.

Finally, we pass our pre-processing and post-processing functions to the DesignSpace.run_batch() method to get our results.

Let's get a pandas.DataFrame of the results and print out the first 5 elements.

And we can also use DataFrame visualization methods, documented here.

If you are interested in this approach to parameter sweeps, we highly recommend checking out our Design plugin tutorial for a deep dive and also the documentation for pandas.DataFrame.

Parameter Scan using Signac¶

For users who might need more structure to their parameter scans, the open source tool "signac" is a fantastic resource. Here we will reproduce some of the previous parameter scan using signac to give an introduction to how to apply it to Tidy3D projects. You can see detailed tutorials and examples at their documentation page.

After importing the package, we need to define a project, which also tells signac to store our parameter scan data in a local directory of our choice.

With siganc (and more generally in parameter sweeps), it is very useful to have a single function to define the inputs and outputs of your parameter scan. In our case, we have a single input (coupling length l) and two outputs: coupling efficiency (eff) and the split ratio (ratio). We write a function to link these inputs and outputs through a Tidy3D simulation.

The signac project contains a set of job objects, which each define a specific data point of our parameter scan. As such, we define another function that wraps compute but instead simply accepts a job instance, which makes our lives easier for managing parameter sweeps in signac.

This function basically will open a job, grab its inputs (l value in our case), compute the output quantities, and save them to both the job.document record and also the .txt files storing the parameter scan results.

With this, we can start our parameter scan, we simply loop through our desired l values, construct a job for each, and pass it to our compute_transmission function.

Note: If intermediate simulation results are needed, it should be possible to modify compute to return also the SimulationData associated with our task, which we could then store in the job.document or elsewhere.

We will compute only 3 values between our ranges of 5 and 12 to save time.

Note, the job instances each have their own unique ID, similar to Tidy3D task_id, this is what is being printed below with each job being computed.

Let's take a look at our project and what data we've computed and stored so far.

signac also provides the ability to create a "linked view", which gives us a human-readable filesystem for looking at our jobs.

We can also initialize many data points to compute later, and feed them to the compute_transmission function with a very basic "caching" implemented by checking if our inputs already exist in the record.

After initializing our statepoints (input values), they are stored in our project and we can loop through them and compute any that don't have records.

While we used td.web.Batch in our original example, signac lets us also leverage parallel processing tools in python to perform something similar.

Let's initialize 9 total statepoints now (5 have already been computed) and feed them to a ThreadPool. We notice that the jobs will be computed in parallel depending on how many threads are available on your machine.

Finally, we can consolidate and plot our results.

For more information, we highly recommend you visit signac documentation page, which includes explanations about all of the many other features not covered here, which could assist you in your parameter scans using Tidy3D.