Skip to content

PartBuilder

Builder for creating particle definitions with a fluent API.

PartBuilder 

PartBuilder(part_id=None)

Bases: Builder[Particle]

Builder for creating PART namelists.

Provides a fluent API for constructing Lagrangian particle classes including water droplets, aerosols, and other particle types.

PARAMETER DESCRIPTION
part_id

Unique particle class identifier. Can also be set via with_id().

TYPE: str DEFAULT: None

Examples:

>>> # Water droplet for sprinkler
>>> droplet = (PartBuilder("WATER_DROP")
...           .as_water_droplet(diameter=0.001, temp=20.0)
...           .with_breakup(True)
...           .with_color("BLUE")
...           .build())

>>> # Smoke aerosol
>>> smoke = (PartBuilder("SMOKE")
...         .as_aerosol(diameter=0.00001, spec_id="SOOT")
...         .with_color("GRAY")
...         .build())

>>> # Custom particle
>>> particle = (PartBuilder("CUSTOM")
...            .with_diameter(0.0005)
...            .with_density(800.0)
...            .with_lifetime(60.0)
...            .build())

>>> # Using with_id() method
>>> particle = (PartBuilder()
...            .with_id("TRACER")
...            .as_tracer()
...            .build())

Initialize the PartBuilder.

PARAMETER DESCRIPTION
part_id

Unique particle class identifier

TYPE: str DEFAULT: None

Source code in src/pyfds/builders/part.py 
48
49
50
51
52
53
54
55
56
57
58
59
def __init__(self, part_id: str | None = None):
    """
    Initialize the PartBuilder.

    Parameters
    ----------
    part_id : str, optional
        Unique particle class identifier
    """
    super().__init__()
    self._id = part_id
    self._params: dict = {}

Functions

with_id 

with_id(part_id)

Set the particle class identifier.

PARAMETER DESCRIPTION
part_id

Unique particle class identifier

TYPE: str

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def with_id(self, part_id: str) -> "PartBuilder":
    """
    Set the particle class identifier.

    Parameters
    ----------
    part_id : str
        Unique particle class identifier

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._id = part_id
    return self

as_water_droplet 

as_water_droplet(diameter, temp=20.0)

Configure as water droplet.

Sets standard water droplet properties including density, boiling temperature, and heat of vaporization.

PARAMETER DESCRIPTION
diameter

Droplet diameter (m)

TYPE: float

temp

Initial temperature (°C), default: 20.0

TYPE: float DEFAULT: 20.0

RETURNS DESCRIPTION
PartBuilder

Self for method chaining

Examples:

>>> droplet = PartBuilder("WATER").as_water_droplet(0.001, temp=20.0).build()
Source code in src/pyfds/builders/part.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def as_water_droplet(self, diameter: float, temp: float = 20.0) -> "PartBuilder":
    """
    Configure as water droplet.

    Sets standard water droplet properties including density,
    boiling temperature, and heat of vaporization.

    Parameters
    ----------
    diameter : float
        Droplet diameter (m)
    temp : float, optional
        Initial temperature (°C), default: 20.0

    Returns
    -------
    PartBuilder
        Self for method chaining

    Examples
    --------
    >>> droplet = PartBuilder("WATER").as_water_droplet(0.001, temp=20.0).build()
    """
    self._params.update(
        {
            "liquid_droplet": True,
            "diameter": diameter,
            "density": 1000.0,
            "initial_temperature": temp,
            "boiling_temperature": 100.0,
            "heat_of_vaporization": 2260.0,
        }
    )
    return self

as_aerosol 

as_aerosol(diameter, spec_id)

Configure as aerosol particle.

PARAMETER DESCRIPTION
diameter

Particle diameter (m)

TYPE: float

spec_id

Gas species ID for aerosol

TYPE: str

RETURNS DESCRIPTION
PartBuilder

Self for method chaining

Examples:

>>> aerosol = PartBuilder("SMOKE").as_aerosol(0.00001, "SOOT").build()
Source code in src/pyfds/builders/part.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def as_aerosol(self, diameter: float, spec_id: str) -> "PartBuilder":
    """
    Configure as aerosol particle.

    Parameters
    ----------
    diameter : float
        Particle diameter (m)
    spec_id : str
        Gas species ID for aerosol

    Returns
    -------
    PartBuilder
        Self for method chaining

    Examples
    --------
    >>> aerosol = PartBuilder("SMOKE").as_aerosol(0.00001, "SOOT").build()
    """
    self._params.update(
        {
            "diameter": diameter,
            "spec_id": spec_id,
            "massless": False,
        }
    )
    return self

as_tracer 

as_tracer()

Configure as massless tracer particle.

RETURNS DESCRIPTION
PartBuilder

Self for method chaining

Examples:

>>> tracer = PartBuilder("TRACER").as_tracer().with_color("GREEN").build()
Source code in src/pyfds/builders/part.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def as_tracer(self) -> "PartBuilder":
    """
    Configure as massless tracer particle.

    Returns
    -------
    PartBuilder
        Self for method chaining

    Examples
    --------
    >>> tracer = PartBuilder("TRACER").as_tracer().with_color("GREEN").build()
    """
    self._params["massless"] = True
    return self

with_diameter 

with_diameter(diameter)

Set particle diameter.

PARAMETER DESCRIPTION
diameter

Particle diameter (m)

TYPE: float

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
def with_diameter(self, diameter: float) -> "PartBuilder":
    """
    Set particle diameter.

    Parameters
    ----------
    diameter : float
        Particle diameter (m)

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["diameter"] = diameter
    return self

with_density 

with_density(density)

Set particle density.

PARAMETER DESCRIPTION
density

Particle density (kg/m³)

TYPE: float

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def with_density(self, density: float) -> "PartBuilder":
    """
    Set particle density.

    Parameters
    ----------
    density : float
        Particle density (kg/m³)

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["density"] = density
    return self

with_mass 

with_mass(mass)

Set particle mass.

PARAMETER DESCRIPTION
mass

Particle mass (kg)

TYPE: float

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
def with_mass(self, mass: float) -> "PartBuilder":
    """
    Set particle mass.

    Parameters
    ----------
    mass : float
        Particle mass (kg)

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["mass"] = mass
    return self

with_breakup 

with_breakup(enabled=True)

Enable or disable droplet breakup.

PARAMETER DESCRIPTION
enabled

Enable droplet breakup, default: True

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
PartBuilder

Self for method chaining

Examples:

>>> droplet = PartBuilder("WATER").as_water_droplet(0.001).with_breakup(True).build()
Source code in src/pyfds/builders/part.py 
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def with_breakup(self, enabled: bool = True) -> "PartBuilder":
    """
    Enable or disable droplet breakup.

    Parameters
    ----------
    enabled : bool, optional
        Enable droplet breakup, default: True

    Returns
    -------
    PartBuilder
        Self for method chaining

    Examples
    --------
    >>> droplet = PartBuilder("WATER").as_water_droplet(0.001).with_breakup(True).build()
    """
    self._params["breakup"] = enabled
    return self

with_breakup_parameters 

with_breakup_parameters(cns_min, cns_max)

Set breakup CNS parameters.

PARAMETER DESCRIPTION
cns_min

Minimum CNS for breakup

TYPE: float

cns_max

Maximum CNS for breakup

TYPE: float

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
def with_breakup_parameters(self, cns_min: float, cns_max: float) -> "PartBuilder":
    """
    Set breakup CNS parameters.

    Parameters
    ----------
    cns_min : float
        Minimum CNS for breakup
    cns_max : float
        Maximum CNS for breakup

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["breakup_cns_min"] = cns_min
    self._params["breakup_cns_max"] = cns_max
    return self

with_color 

with_color(color)

Set particle color for visualization.

PARAMETER DESCRIPTION
color

Color name (e.g., "BLUE", "RED", "GREEN")

TYPE: str

RETURNS DESCRIPTION
PartBuilder

Self for method chaining

Examples:

>>> particle = PartBuilder("SMOKE").with_color("GRAY").build()
Source code in src/pyfds/builders/part.py 
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
def with_color(self, color: str) -> "PartBuilder":
    """
    Set particle color for visualization.

    Parameters
    ----------
    color : str
        Color name (e.g., "BLUE", "RED", "GREEN")

    Returns
    -------
    PartBuilder
        Self for method chaining

    Examples
    --------
    >>> particle = PartBuilder("SMOKE").with_color("GRAY").build()
    """
    self._params["color"] = color
    return self

with_rgb 

with_rgb(r, g, b)

Set particle RGB color.

PARAMETER DESCRIPTION
r

Red value (0-255)

TYPE: int

g

Green value (0-255)

TYPE: int

b

Blue value (0-255)

TYPE: int

RETURNS DESCRIPTION
PartBuilder

Self for method chaining

Examples:

>>> particle = PartBuilder("CUSTOM").with_rgb(128, 128, 128).build()
Source code in src/pyfds/builders/part.py 
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
def with_rgb(self, r: int, g: int, b: int) -> "PartBuilder":
    """
    Set particle RGB color.

    Parameters
    ----------
    r : int
        Red value (0-255)
    g : int
        Green value (0-255)
    b : int
        Blue value (0-255)

    Returns
    -------
    PartBuilder
        Self for method chaining

    Examples
    --------
    >>> particle = PartBuilder("CUSTOM").with_rgb(128, 128, 128).build()
    """
    self._params["rgb"] = (r, g, b)
    return self

with_lifetime 

with_lifetime(lifetime)

Set particle lifetime.

PARAMETER DESCRIPTION
lifetime

Particle lifetime (s)

TYPE: float

RETURNS DESCRIPTION
PartBuilder

Self for method chaining

Examples:

>>> particle = PartBuilder("TEMP").with_lifetime(60.0).build()
Source code in src/pyfds/builders/part.py 
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
def with_lifetime(self, lifetime: float) -> "PartBuilder":
    """
    Set particle lifetime.

    Parameters
    ----------
    lifetime : float
        Particle lifetime (s)

    Returns
    -------
    PartBuilder
        Self for method chaining

    Examples
    --------
    >>> particle = PartBuilder("TEMP").with_lifetime(60.0).build()
    """
    self._params["lifetime"] = lifetime
    return self

with_initial_age 

with_initial_age(age)

Set initial particle age.

PARAMETER DESCRIPTION
age

Initial age (s)

TYPE: float

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
def with_initial_age(self, age: float) -> "PartBuilder":
    """
    Set initial particle age.

    Parameters
    ----------
    age : float
        Initial age (s)

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["age"] = age
    return self

with_drag_law 

with_drag_law(drag_law)

Set drag law.

PARAMETER DESCRIPTION
drag_law

Drag law: "SPHERE", "CYLINDER", or "SCREEN"

TYPE: str

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
def with_drag_law(self, drag_law: str) -> "PartBuilder":
    """
    Set drag law.

    Parameters
    ----------
    drag_law : str
        Drag law: "SPHERE", "CYLINDER", or "SCREEN"

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["drag_law"] = drag_law.upper()
    return self

with_sampling_factor 

with_sampling_factor(factor)

Set statistical sampling factor.

PARAMETER DESCRIPTION
factor

Sampling factor (>= 1)

TYPE: int

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
def with_sampling_factor(self, factor: int) -> "PartBuilder":
    """
    Set statistical sampling factor.

    Parameters
    ----------
    factor : int
        Sampling factor (>= 1)

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["sampling_factor"] = factor
    return self

as_static 

as_static()

Configure as static particle (doesn't move).

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
368
369
370
371
372
373
374
375
376
377
378
def as_static(self) -> "PartBuilder":
    """
    Configure as static particle (doesn't move).

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["static"] = True
    return self

with_orientation 

with_orientation(x, y, z)

Set particle orientation vector.

PARAMETER DESCRIPTION
x

X component

TYPE: float

y

Y component

TYPE: float

z

Z component

TYPE: float

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
def with_orientation(self, x: float, y: float, z: float) -> "PartBuilder":
    """
    Set particle orientation vector.

    Parameters
    ----------
    x : float
        X component
    y : float
        Y component
    z : float
        Z component

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["orientation"] = (x, y, z)
    return self

with_surface 

with_surface(surf_id)

Set surface ID for particle interaction.

PARAMETER DESCRIPTION
surf_id

Surface ID

TYPE: str

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
def with_surface(self, surf_id: str) -> "PartBuilder":
    """
    Set surface ID for particle interaction.

    Parameters
    ----------
    surf_id : str
        Surface ID

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["surf_id"] = surf_id
    return self

with_property 

with_property(prop_id)

Set property ID.

PARAMETER DESCRIPTION
prop_id

Property ID

TYPE: str

RETURNS DESCRIPTION
PartBuilder

Self for method chaining
Source code in src/pyfds/builders/part.py 
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
def with_property(self, prop_id: str) -> "PartBuilder":
    """
    Set property ID.

    Parameters
    ----------
    prop_id : str
        Property ID

    Returns
    -------
    PartBuilder
        Self for method chaining
    """
    self._params["prop_id"] = prop_id
    return self

Overview

PartBuilder creates particle definitions (&PART namelists) for sprinklers, droplets, tracers, and other particle-based phenomena.

Quick Examples

Water Droplets for Sprinklers

from pyfds.builders import PartBuilder

# Water droplet particles
water = (
    PartBuilder("WATER")
    .as_water_droplet()
    .with_diameter(500)  # microns
    .build()
)

Tracer Particles

# Tracer particles for flow visualization
tracer = (
    PartBuilder("TRACER")
    .as_tracer()
    .with_color("BLUE")
    .build()
)

See Also