|
| 1 | +Configuration Guide |:gear:| |
| 2 | +============================ |
| 3 | + |
| 4 | +.. highlight:: python |
| 5 | + |
| 6 | +Working with cloud simulations usually requires a handful of settings such as |
| 7 | +your API key, the active environment, and any local tweaks you make while |
| 8 | +experimenting. The ``tidy3d.config`` module keeps all of this in one place |
| 9 | +through a single object called ``config``. This page explains how it behaves, |
| 10 | +where values are stored, and how to keep your changes consistent across |
| 11 | +sessions. |
| 12 | + |
| 13 | +Getting Started |
| 14 | +--------------- |
| 15 | + |
| 16 | +Most users only need the following import:: |
| 17 | + |
| 18 | + from tidy3d.config import config |
| 19 | + |
| 20 | +You can then read or update sections just like attributes:: |
| 21 | + |
| 22 | + # read values |
| 23 | + print(config.web.api_endpoint) |
| 24 | + print(config.logging.level) |
| 25 | + |
| 26 | + # update values |
| 27 | + config.logging.level = "DEBUG" |
| 28 | + config.web.timeout = 60 |
| 29 | + config.save() |
| 30 | + |
| 31 | +The ``save()`` call writes your edits to disk so the same settings load the |
| 32 | +next time you import ``tidy3d``. |
| 33 | + |
| 34 | +Where Settings Are Stored |
| 35 | +------------------------- |
| 36 | + |
| 37 | +Tidy3D chooses a configuration directory the first time you import the module. |
| 38 | +The location depends on your operating system: |
| 39 | + |
| 40 | +.. list-table:: Default configuration directory |
| 41 | + :widths: 30 70 |
| 42 | + :header-rows: 1 |
| 43 | + |
| 44 | + * - Platform |
| 45 | + - Path |
| 46 | + * - macOS / Linux |
| 47 | + - ``~/.config/tidy3d`` |
| 48 | + * - Windows |
| 49 | + - ``C:\\Users\\<you>\\.config\\tidy3d`` |
| 50 | + |
| 51 | +You can override this by setting the ``TIDY3D_BASE_DIR`` environment variable |
| 52 | +*before* importing ``tidy3d``. When it is present, the config files are kept in |
| 53 | +``<base>/.tidy3d``. If the chosen location is not writable, Tidy3D falls back to |
| 54 | +a temporary directory and warns that the settings will not persist. |
| 55 | + |
| 56 | +Files Inside the Directory |
| 57 | +~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 58 | + |
| 59 | +- ``config.toml`` – base settings shared by all profiles. |
| 60 | +- ``profiles/<name>.toml`` – optional overrides for custom profiles. Each file |
| 61 | + only contains the differences from the base settings. |
| 62 | + |
| 63 | +Priority Order |
| 64 | +-------------- |
| 65 | + |
| 66 | +Whenever you read ``config.<section>.<field>``, the value comes from the highest |
| 67 | +priority source in the list below. Lower entries only apply when the ones above |
| 68 | +them do not set a value. |
| 69 | + |
| 70 | +1. Runtime changes you make in the current Python session. |
| 71 | +2. Environment variables (``TIDY3D_<SECTION>__<FIELD>``). |
| 72 | +3. Profile overrides from ``profiles/<name>.toml``. |
| 73 | +4. The base ``config.toml`` file. |
| 74 | +5. Built-in profiles (for example ``prod`` and ``dev``) bundled with Tidy3D. |
| 75 | +6. Default values defined by the software. |
| 76 | + |
| 77 | +This means environment variables always win over ``config.toml``, and any |
| 78 | +attribute you set in code wins over everything else until you discard it or |
| 79 | +call ``save()``. |
| 80 | + |
| 81 | +Making Changes That Last |
| 82 | +------------------------ |
| 83 | + |
| 84 | +Runtime Updates |
| 85 | +~~~~~~~~~~~~~~~ |
| 86 | + |
| 87 | +Assignments like ``config.logging.level = "INFO"`` apply immediately but only |
| 88 | +live in memory. They affect new simulations started in the same interpreter but |
| 89 | +disappear when the process exits. |
| 90 | + |
| 91 | +Saving to Disk |
| 92 | +~~~~~~~~~~~~~~ |
| 93 | + |
| 94 | +Call ``config.save()`` to write the current profile to disk. The method removes |
| 95 | +environment-variable overrides automatically so you never persist an API key or |
| 96 | +other secret that was loaded from the shell. To store the full set of values, |
| 97 | +including defaults, pass ``include_defaults=True``:: |
| 98 | + |
| 99 | + config.save(include_defaults=True) |
| 100 | + |
| 101 | +Profiles |
| 102 | +-------- |
| 103 | + |
| 104 | +Tidy3D ships with built-in profiles such as ``prod`` and ``dev``. Switch between |
| 105 | +them with:: |
| 106 | + |
| 107 | + config.switch_profile("dev") |
| 108 | + |
| 109 | +To create your own profile, switch to a new name, edit settings, then call |
| 110 | +``save()``:: |
| 111 | + |
| 112 | + config.switch_profile("customer") |
| 113 | + config.web.api_endpoint = "https://example.com" |
| 114 | + config.save() |
| 115 | + |
| 116 | +This writes ``profiles/customer.toml`` containing only the adjustments you |
| 117 | +made. Use ``config.profiles.list()`` to discover available built-in and user |
| 118 | +profiles. |
| 119 | + |
| 120 | +Environment Variables |
| 121 | +--------------------- |
| 122 | + |
| 123 | +Environment variables let you override individual options without touching any |
| 124 | +files. The naming pattern is ``TIDY3D_<SECTION>__<FIELD>``, for example:: |
| 125 | + |
| 126 | + export TIDY3D_LOGGING__LEVEL=WARNING |
| 127 | + |
| 128 | +Supported variables take effect the next time you import ``tidy3d``. Remove a |
| 129 | +variable or clear the shell environment to restore the lower priority setting. |
| 130 | + |
| 131 | +Plugin Settings |
| 132 | +--------------- |
| 133 | + |
| 134 | +Plugins can register their own sections so their options appear under |
| 135 | +``config.plugins``. A typical plugin exposes a model decorated with |
| 136 | +``@register_plugin``:: |
| 137 | + |
| 138 | + from tidy3d.config.sections import ConfigSection |
| 139 | + from tidy3d.config import register_plugin |
| 140 | + |
| 141 | + @register_plugin("sample") |
| 142 | + class SamplePluginConfig(ConfigSection): |
| 143 | + enabled: bool = False |
| 144 | + threshold: float = 0.5 |
| 145 | + |
| 146 | +After the plugin is imported, you can read or modify its settings with:: |
| 147 | + |
| 148 | + config.plugins.sample.enabled = True |
| 149 | + config.save() |
| 150 | + |
| 151 | +If the plugin registers later in the session, previously saved values are |
| 152 | +loaded automatically. |
| 153 | + |
| 154 | +Command Line Helpers |
| 155 | +-------------------- |
| 156 | + |
| 157 | +Use ``tidy3d configure`` to store your API key in ``config.toml``. The command |
| 158 | +creates the directory if it is missing and updates only the ``web`` section. |
| 159 | + |
| 160 | +If you have older files in ``~/.tidy3d``, run ``tidy3d config migrate`` to move |
| 161 | +them into the new location described above. The command copies the legacy files |
| 162 | +into the canonical directory, leaving the originals untouched unless you pass |
| 163 | +``--delete-legacy``. Use ``--overwrite`` if you have already started using the |
| 164 | +new location and want to replace those files with the legacy versions. |
| 165 | + |
| 166 | +Legacy Access Points |
| 167 | +-------------------- |
| 168 | + |
| 169 | +Older code paths such as ``tidy3d.config.logging_level`` and ``tidy3d.config.Env`` |
| 170 | +still work. They emit a ``DeprecationWarning`` each time you use them to help |
| 171 | +you transition to the modern interface. See :doc:`migration` for advice on |
| 172 | +updating scripts that depend on these names. |
| 173 | + |
| 174 | +Next Steps |
| 175 | +---------- |
| 176 | + |
| 177 | +- :doc:`migration` |
| 178 | +- :doc:`../api/configuration` |
0 commit comments