tidy3d.web.Batch
tidy3d.web.Batch#
- class tidy3d.web.Batch(*, type: Literal['Batch'] = 'Batch', simulations: Dict[str, Union[tidy3d.components.simulation.Simulation, tidy3d.components.heat.simulation.HeatSimulation]], folder_name: str = 'default', verbose: bool = True, solver_version: str = None, callback_url: str = None, simulation_type: str = 'tidy3d', parent_tasks: Dict[str, Tuple[str, ...]] = None, jobs: Dict[str, tidy3d.web.api.container.Job] = None)#
Bases:
tidy3d.web.api.container.WebContainer
Interface for submitting several Union[
Simulation
,HeatSimulation
] objects to sever.- Parameters
simulations (Mapping[str, Union[Simulation, HeatSimulation]]) – Mapping of task names to Simulations to run as a batch.
folder_name (str = default) – Name of folder to store member of each batch on web UI.
verbose (bool = True) – Whether to print info messages and progressbars.
solver_version (Optional[str] = None) – callback_url : Optional[str] = None Http PUT url to receive simulation finish event. The body content is a json file with fields
{'id', 'status', 'name', 'workUnit', 'solverVersion'}
.simulation_type (str = tidy3d) – Type of each simulation in the batch, used internally only.
parent_tasks (Optional[Mapping[str, Tuple[str, ...]]] = None) – Collection of parent task ids for each job in batch, used internally only.
jobs (Optional[Mapping[str, Job]] = None) – Mapping of task names to individual Job object for each task in the batch. Set by
Batch.upload
, leave as None.
- __init__(**kwargs)#
Init method, includes post-init validators.
Methods
__init__
(**kwargs)Init method, includes post-init validators.
Automatically place "type" field with model name in the model field dictionary.
construct
([_fields_set])Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data.
copy
(**kwargs)Copy a Tidy3dBaseModel.
delete
()Delete server-side data associated with each task in the batch.
dict
(*[, include, exclude, by_alias, ...])Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
dict_from_file
(fname[, group_path])Loads a dictionary containing the model from a .yaml, .json, .hdf5, or .hdf5.gz file.
dict_from_hdf5
(fname[, group_path, ...])Loads a dictionary containing the model contents from a .hdf5 file.
dict_from_hdf5_gz
(fname[, group_path, ...])Loads a dictionary containing the model contents from a .hdf5.gz file.
dict_from_json
(fname)Load dictionary of the model from a .json file.
dict_from_yaml
(fname)Load dictionary of the model from a .yaml file.
download
([path_dir])Download results of each task.
Compute the maximum FlexCredit charge for a given
Batch
.from_file
(fname[, group_path])Loads a
Tidy3dBaseModel
from .yaml, .json, .hdf5, or .hdf5.gz file.from_hdf5
(fname[, group_path, custom_decoders])Loads
Tidy3dBaseModel
instance to .hdf5 file.from_hdf5_gz
(fname[, group_path, ...])Loads
Tidy3dBaseModel
instance to .hdf5.gz file.from_json
(fname, **parse_obj_kwargs)Load a
Tidy3dBaseModel
from .json file.from_orm
(obj)from_yaml
(fname, **parse_obj_kwargs)Loads
Tidy3dBaseModel
from .yaml file.Generates a docstring for a Tidy3D mode and saves it to the __doc__ of the class.
get_info
()Get information about each task in the
Batch
.get information about a each of the tasks in the
Batch
.get_sub_model
(group_path, model_dict)Get the sub model for a given group path.
Return a dictionary of this object's sub-models indexed by their hash values.
get_tuple_group_name
(index)Get the group name of a tuple element.
get_tuple_index
(key_name)Get the index into the tuple based on its group name.
help
([methods])Prints message describing the fields and methods of a
Tidy3dBaseModel
.json
(*[, include, exclude, by_alias, ...])Generate a JSON representation of the model, include and exclude arguments as per dict().
load
([path_dir])Download results and load them into
BatchData
object.monitor
()Monitor progress of each of the running tasks.
parse_file
(path, *[, content_type, ...])parse_obj
(obj)parse_raw
(b, *[, content_type, encoding, ...])Get the sum of billed costs for each task associated with this batch.
run
([path_dir])Upload and run each simulation in
Batch
.schema
([by_alias, ref_template])schema_json
(*[, by_alias, ref_template])start
()Start running all tasks in the
Batch
.to_file
(fname)Exports
Tidy3dBaseModel
instance to .yaml, .json, or .hdf5 fileto_hdf5
(fname[, custom_encoders])Exports
Tidy3dBaseModel
instance to .hdf5 file.to_hdf5_gz
(fname[, custom_encoders])Exports
Tidy3dBaseModel
instance to .hdf5.gz file.to_json
(fname)Exports
Tidy3dBaseModel
instance to .json fileto_yaml
(fname)Exports
Tidy3dBaseModel
instance to .yaml file.tuple_to_dict
(tuple_values)How we generate a dictionary mapping new keys to tuple values for hdf5.
update_forward_refs
(**localns)Try to update ForwardRefs on fields based on this Model, globalns and localns.
updated_copy
(**kwargs)Make copy of a component instance with
**kwargs
indicating updated field values.validate
(value)Attributes
simulations
folder_name
verbose
solver_version
callback_url
simulation_type
parent_tasks
jobs
- class Config#
Bases:
object
Sets config for all
Tidy3dBaseModel
objects.- allow_population_by_field_namebool = True
Allow properties to stand in for fields(?).
- arbitrary_types_allowedbool = True
Allow types like numpy arrays.
- extrastr = ‘forbid’
Forbid extra kwargs not specified in model.
- json_encodersDict[type, Callable]
Defines how to encode type in json file.
- validate_allbool = True
Validate default values just to be safe.
- validate_assignmentbool
Re-validate after re-assignment of field in model.
- __eq__(other)#
Define == for two Tidy3DBaseModels.
- __ge__(other)#
define >= for getting unique indices based on hash.
- __gt__(other)#
define > for getting unique indices based on hash.
- __hash__() int #
Hash method.
- classmethod __init_subclass__() None #
Things that are done to each of the models.
- __iter__() TupleGenerator #
so dict(model) works
- __le__(other)#
define <= for getting unique indices based on hash.
- __lt__(other)#
define < for getting unique indices based on hash.
- __pretty__(fmt: Callable[[Any], Any], **kwargs: Any) Generator[Any, None, None] #
Used by devtools (https://python-devtools.helpmanual.io/) to provide a human readable representations of objects
- __repr_name__() str #
Name of the instance’s class, used in __repr__.
- __rich_repr__() RichReprResult #
Get fields for Rich library
- classmethod __try_update_forward_refs__(**localns: Any) None #
Same as update_forward_refs but will not raise exception when forward references are not defined.
- classmethod add_type_field() None #
Automatically place “type” field with model name in the model field dictionary.
- classmethod construct(_fields_set: Optional[SetStr] = None, **values: Any) Model #
Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values
- copy(**kwargs) tidy3d.components.base.Tidy3dBaseModel #
Copy a Tidy3dBaseModel. With
deep=True
as default.
- delete() None #
Delete server-side data associated with each task in the batch.
- dict(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, by_alias: bool = False, skip_defaults: Optional[bool] = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) DictStrAny #
Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
- classmethod dict_from_file(fname: str, group_path: Optional[str] = None) dict #
Loads a dictionary containing the model from a .yaml, .json, .hdf5, or .hdf5.gz file.
- Parameters
fname (str) – Full path to the file to load the
Tidy3dBaseModel
from.group_path (str, optional) – Path to a group inside the file to use as the base level.
- Returns
A dictionary containing the model.
- Return type
dict
Example
>>> simulation = Simulation.from_file(fname='folder/sim.json')
- classmethod dict_from_hdf5(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None) dict #
Loads a dictionary containing the model contents from a .hdf5 file.
- Parameters
fname (str) – Full path to the .hdf5 file to load the
Tidy3dBaseModel
from.group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.
- Returns
Dictionary containing the model.
- Return type
dict
Example
>>> sim_dict = Simulation.dict_from_hdf5(fname='folder/sim.hdf5')
- classmethod dict_from_hdf5_gz(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None) dict #
Loads a dictionary containing the model contents from a .hdf5.gz file.
- Parameters
fname (str) – Full path to the .hdf5.gz file to load the
Tidy3dBaseModel
from.group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.
- Returns
Dictionary containing the model.
- Return type
dict
Example
>>> sim_dict = Simulation.dict_from_hdf5(fname='folder/sim.hdf5.gz')
- classmethod dict_from_json(fname: str) dict #
Load dictionary of the model from a .json file.
- Parameters
fname (str) – Full path to the .json file to load the
Tidy3dBaseModel
from.- Returns
A dictionary containing the model.
- Return type
dict
Example
>>> sim_dict = Simulation.dict_from_json(fname='folder/sim.json')
- classmethod dict_from_yaml(fname: str) dict #
Load dictionary of the model from a .yaml file.
- Parameters
fname (str) – Full path to the .yaml file to load the
Tidy3dBaseModel
from.- Returns
A dictionary containing the model.
- Return type
dict
Example
>>> sim_dict = Simulation.dict_from_yaml(fname='folder/sim.yaml')
- download(path_dir: str = '.') None #
Download results of each task.
- Parameters
path_dir (str = './') – Base directory where data will be downloaded, by default the current working directory.
Note
To load the data into Union[
SimulationData
,HeatSimulationData
] objets, can callBatch.items()
.The data for each task will be named as
{path_dir}/{task_name}.hdf5
. TheBatch
hdf5 file will be automatically saved as{path_dir}/batch.hdf5
, allowing one to load thisBatch
later usingbatch = Batch.from_file()
.
- estimate_cost() float #
Compute the maximum FlexCredit charge for a given
Batch
.- Returns
Estimated maximum cost for each Union[
Simulation
,HeatSimulation
] associated with givenBatch
.- Return type
float
Note
Cost is calculated assuming the simulation runs for the full
run_time
. If early shut-off is triggered, the cost is adjusted proporionately.- Returns
Estimated total cost of the tasks in FlexCredits.
- Return type
float
- classmethod from_file(fname: str, group_path: Optional[str] = None, **parse_obj_kwargs) tidy3d.components.base.Tidy3dBaseModel #
Loads a
Tidy3dBaseModel
from .yaml, .json, .hdf5, or .hdf5.gz file.- Parameters
fname (str) – Full path to the file to load the
Tidy3dBaseModel
from.group_path (str, optional) – Path to a group inside the file to use as the base level. Only for hdf5 files. Starting / is optional.
**parse_obj_kwargs – Keyword arguments passed to either pydantic’s
parse_obj
function when loading model.
- Returns
An instance of the component class calling
load
.- Return type
Tidy3dBaseModel
Example
>>> simulation = Simulation.from_file(fname='folder/sim.json')
- classmethod from_hdf5(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None, **parse_obj_kwargs) tidy3d.components.base.Tidy3dBaseModel #
Loads
Tidy3dBaseModel
instance to .hdf5 file.- Parameters
fname (str) – Full path to the .hdf5 file to load the
Tidy3dBaseModel
from.group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only. Starting / is optional.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s
parse_obj
method.
Example
>>> simulation = Simulation.from_hdf5(fname='folder/sim.hdf5')
- classmethod from_hdf5_gz(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None, **parse_obj_kwargs) tidy3d.components.base.Tidy3dBaseModel #
Loads
Tidy3dBaseModel
instance to .hdf5.gz file.- Parameters
fname (str) – Full path to the .hdf5.gz file to load the
Tidy3dBaseModel
from.group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only. Starting / is optional.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s
parse_obj
method.
Example
>>> simulation = Simulation.from_hdf5_gz(fname='folder/sim.hdf5.gz')
- classmethod from_json(fname: str, **parse_obj_kwargs) tidy3d.components.base.Tidy3dBaseModel #
Load a
Tidy3dBaseModel
from .json file.- Parameters
fname (str) – Full path to the .json file to load the
Tidy3dBaseModel
from.- Returns
Tidy3dBaseModel
– An instance of the component class calling load.**parse_obj_kwargs – Keyword arguments passed to pydantic’s
parse_obj
method.
Example
>>> simulation = Simulation.from_json(fname='folder/sim.json')
- classmethod from_yaml(fname: str, **parse_obj_kwargs) tidy3d.components.base.Tidy3dBaseModel #
Loads
Tidy3dBaseModel
from .yaml file.- Parameters
fname (str) – Full path to the .yaml file to load the
Tidy3dBaseModel
from.**parse_obj_kwargs – Keyword arguments passed to pydantic’s
parse_obj
method.
- Returns
An instance of the component class calling from_yaml.
- Return type
Tidy3dBaseModel
Example
>>> simulation = Simulation.from_yaml(fname='folder/sim.yaml')
- classmethod generate_docstring() str #
Generates a docstring for a Tidy3D mode and saves it to the __doc__ of the class.
- get_info() Dict[str, tidy3d.web.core.task_info.TaskInfo] #
Get information about each task in the
Batch
.- Returns
Mapping of task name to data about task associated with each task.
- Return type
Dict[str,
TaskInfo
]
- get_run_info() Dict[str, tidy3d.web.core.task_info.RunInfo] #
get information about a each of the tasks in the
Batch
.- Returns
Dict[str – Maps task names to run info for each task in the
Batch
.- Return type
RunInfo
]
- classmethod get_sub_model(group_path: str, model_dict: dict | list) dict #
Get the sub model for a given group path.
- get_submodels_by_hash() Dict[int, List[Union[str, Tuple[str, int]]]] #
Return a dictionary of this object’s sub-models indexed by their hash values.
- static get_tuple_group_name(index: int) str #
Get the group name of a tuple element.
- static get_tuple_index(key_name: str) int #
Get the index into the tuple based on its group name.
- help(methods: bool = False) None #
Prints message describing the fields and methods of a
Tidy3dBaseModel
.- Parameters
methods (bool = False) – Whether to also print out information about object’s methods.
Example
>>> simulation.help(methods=True)
- json(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, by_alias: bool = False, skip_defaults: Optional[bool] = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Optional[Callable[[Any], Any]] = None, models_as_dict: bool = True, **dumps_kwargs: Any) str #
Generate a JSON representation of the model, include and exclude arguments as per dict().
encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().
- load(path_dir: str = '.') tidy3d.web.api.container.BatchData #
Download results and load them into
BatchData
object.- Parameters
path_dir (str = './') – Base directory where data will be downloaded, by default current working directory.
- Returns
BatchData
– Contains Union[SimulationData
,HeatSimulationData
] for each Union[Simulation
,HeatSimulation
] inBatch
.The
Batch
hdf5 file will be automatically saved as{path_dir}/batch.hdf5
,allowing one to load this
Batch
later usingbatch = Batch.from_file()
.
- monitor() None #
Monitor progress of each of the running tasks.
Note
To loop through the data of completed simulations, can call
Batch.items()
.
- real_cost() float #
Get the sum of billed costs for each task associated with this batch.
- run(path_dir: str = '.') tidy3d.web.api.container.BatchData #
Upload and run each simulation in
Batch
.- Parameters
path_dir (str) – Base directory where data will be downloaded, by default current working directory.
- Returns
Contains Union[
SimulationData
,HeatSimulationData
] for each Union[Simulation
,HeatSimulation
] inBatch
.- Return type
Note
A typical usage might look like:
>>> batch_data = batch.run() >>> for task_name, sim_data in batch_data.items(): ... # do something with data.
bach_data
does not store all of the Union[SimulationData
,HeatSimulationData
] objects in memory, rather it iterates over the task names and loads the corresponding Union[SimulationData
,HeatSimulationData
] from file one by one. If no file exists for that task, it downloads it.
- start() None #
Start running all tasks in the
Batch
.Note
To monitor the running simulations, can call
Batch.monitor()
.
- to_file(fname: str) None #
Exports
Tidy3dBaseModel
instance to .yaml, .json, or .hdf5 file- Parameters
fname (str) – Full path to the .yaml or .json file to save the
Tidy3dBaseModel
to.
Example
>>> simulation.to_file(fname='folder/sim.json')
- to_hdf5(fname: str, custom_encoders: Optional[List[Callable]] = None) None #
Exports
Tidy3dBaseModel
instance to .hdf5 file.- Parameters
fname (str) – Full path to the .hdf5 file to save the
Tidy3dBaseModel
to.custom_encoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, value: Any) that take the
value
supplied and write it to the hdf5fname
atgroup_path
.
Example
>>> simulation.to_hdf5(fname='folder/sim.hdf5')
- to_hdf5_gz(fname: str, custom_encoders: Optional[List[Callable]] = None) None #
Exports
Tidy3dBaseModel
instance to .hdf5.gz file.- Parameters
fname (str) – Full path to the .hdf5.gz file to save the
Tidy3dBaseModel
to.custom_encoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, value: Any) that take the
value
supplied and write it to the hdf5fname
atgroup_path
.
Example
>>> simulation.to_hdf5_gz(fname='folder/sim.hdf5.gz')
- to_json(fname: str) None #
Exports
Tidy3dBaseModel
instance to .json file- Parameters
fname (str) – Full path to the .json file to save the
Tidy3dBaseModel
to.
Example
>>> simulation.to_json(fname='folder/sim.json')
- to_yaml(fname: str) None #
Exports
Tidy3dBaseModel
instance to .yaml file.- Parameters
fname (str) – Full path to the .yaml file to save the
Tidy3dBaseModel
to.
Example
>>> simulation.to_yaml(fname='folder/sim.yaml')
- classmethod tuple_to_dict(tuple_values: tuple) dict #
How we generate a dictionary mapping new keys to tuple values for hdf5.
- classmethod update_forward_refs(**localns: Any) None #
Try to update ForwardRefs on fields based on this Model, globalns and localns.
- updated_copy(**kwargs) tidy3d.components.base.Tidy3dBaseModel #
Make copy of a component instance with
**kwargs
indicating updated field values.