Optical

Mie efficiency curves per species, refractive-index couples, 2-D response surfaces and scattering phase functions. Theory: Mie.

AeroViz.plot.optical

Functions:

Q_plot

Q_plot(species: Literal['AS', 'AN', 'OM', 'Soil', 'SS', 'BC', 'Water'] | list[Literal['AS', 'AN', 'OM', 'Soil', 'SS', 'BC', 'Water']], x: Literal['dp', 'sp'] = 'dp', y: Literal['Q', 'MEE'] = 'Q', mode: Literal['ext', 'sca', 'abs'] = 'ext', **kwargs) -> tuple[Figure, Axes]

Generate a plot showing optical efficiency or mass optical efficiency for different particle species.

Parameters:

Name	Type	Description	Default
species	Union[Literal['AS', 'AN', 'OM', 'Soil', 'SS', 'BC', 'Water'], list[Literal['AS', 'AN', 'OM', 'Soil', 'SS', 'BC', 'Water']]]	The particle species or list of particle species to plot. Valid species include 'AS' (Ammonium Sulfate), 'AN' (Ammonium Nitrate), 'OM' (Organic Matter), 'Soil', 'SS' (Sea Salt), 'BC' (Black Carbon), and 'Water'.	required
x	Literal['dp', 'sp']	The x-axis parameter. 'dp' represents particle diameter, and 'sp' represents size parameter (alpha). Default is 'dp'.	'dp'
y	Literal['Q', 'MEE']	The y-axis parameter. 'Q' represents optical efficiency (Q_ext, Q_sca, Q_abs), and 'MEE' represents mass optical efficiency (MEE, MSE, MAE). Default is 'Q'.	'Q'
mode	Literal['ext', 'sca', 'abs']	The mode of efficiency to plot. 'ext' for extinction efficiency, 'sca' for scattering efficiency, and 'abs' for absorption efficiency. Default is 'ext'.	'ext'
**kwargs		Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated plot.

Examples:

Example usage of the Q_plot function:

>>> Q_plot('AS', x='dp', y='Q', mode='ext')
>>> Q_plot(['AS', 'AN'], x='sp', y='MEE')

RI_couple

RI_couple(**kwargs) -> tuple[Figure, Axes]

Generate a plot to test the influence of imaginary parts on scattering and absorption efficiencies.

Parameters:

Name	Type	Description	Default
**kwargs		Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated plot.

Examples:

Example usage of the IJ_couple function:

>>> ax = RI_couple()

RRI_2D

RRI_2D(mode: Literal['ext', 'sca', 'abs'] = 'ext', **kwargs) -> tuple[Figure, Axes]

Generate a 2D plot of scattering efficiency (Q) against real and imaginary parts of the refractive index.

Parameters:

Name	Type	Description	Default
mode	(ext, sca, abs)	The mode of scattering efficiency to plot: - 'ext' for extinction efficiency (Q_ext) - 'sca' for scattering efficiency (Q_sca) - 'abs' for absorption efficiency (Q_abs) Default is 'ext'.	'ext'
**kwargs		Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated 2D plot.

Examples:

Example usage of the RRI_2D function:

>>> RRI_2D(mode='sca', xlabel='Real Part (n)', ylabel='Imaginary Part (k)', title='Scattering Efficiency 2D Plot')

scattering_phase

scattering_phase(m: complex = 1.55 + 0.01j, wave: float = 600, dp: float = 200) -> tuple[Figure, Axes]

Generate a polar plot to visualize the scattering phase function.

Parameters:

Name	Type	Description	Default
m	complex	The complex refractive index of the scattering medium. Default is 1.55 + 0.01j.	1.55 + 0.01j
wave	float	The wavelength of the incident light in nanometers. Default is 600 nm.	600
dp	float	The particle diameter in nanometers. Default is 200 nm.	200

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated polar plot.

Examples:

Example usage of the scattering_phase function:

>>> ax = scattering_phase(m=1.55 + 0.01j, wave=600, dp=200)

response_surface

response_surface(real_range=(1.33, 1.7), gmd_range=(10, 500), num=50, **kwargs) -> tuple[Figure, Axes]

Generate a response surface plot for sensitivity tests of extinction based on Mie scattering.

Parameters:

Name	Type	Description	Default
real_range	tuple	The range of real part (refractive index) values for sensitivity testing. Default is (1.33, 1.7).	(1.33, 1.7)
gmd_range	tuple	The range of geometric mean diameter (GMD) values for sensitivity testing. Default is (60, 400).	(10, 500)
num	int	The number of points to generate within the specified ranges. Default is 50.	50
**kwargs		Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated response surface plot.

Examples:

Example usage of the response_surface function:

>>> response_surface(real_range=(1.4, 1.6), gmd_range=(100, 300), num=30, xlabel='Real Part (n)',
...                  ylabel='GMD (nm)', zlabel='Extinction (1/Mm)', title='Sensitivity Tests of Extinction')

mie_contribution

mie_contribution(m: complex = 1.8 + 0.1j, wavelengths: float | list[float] = 550, *, geo_mean: float = 140, geo_std: float = 1.95, total_number: float | None = None, total_volume: float | None = None, total_mass: float | None = None, density: float | None = None, mode: str = 'number', dp_range: tuple = (5, 10000), n_bins: int = 500, **kwargs) -> tuple[Figure, tuple[Axes, Axes]]

Which particle sizes of a lognormal mode produce its scattering and absorption.

Top panel: the mode as dN/dlogDp (left axis) and dV/dlogDp (right axis). Bottom panel: per-size contributions dσ_sca/dlogDp and dσ_abs/dlogDp (Mm⁻¹) for each wavelength, the integrated σ_sca / σ_abs in the legend. The area under each lower curve is the bulk coefficient :func:AeroViz.optical.mie_lognormal returns for the same inputs.

Parameters:

Name	Type	Description	Default
m	complex	Refractive index n + ik.	1.8 + 0.1j
wavelengths	float or list of float	Wavelength(s) in nm; several wavelengths share colours and differ in line style.	550
geo_mean	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
geo_std	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
total_number	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
total_volume	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
total_mass	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
density	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
mode	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
dp_range	tuple	Diameter grid (nm).	(5, 10000)
n_bins	tuple	Diameter grid (nm).	(5, 10000)

Returns:

Type	Description
(fig, (ax_psd, ax_sigma))

Modules

optical

Classes

Unit

Methods:

load_jsonfile classmethod

load_jsonfile()

讀取 JSON 檔中數據并將其變成屬性

update_jsonfile classmethod

update_jsonfile(key, value)

更新JSON檔

del_jsonfile classmethod

del_jsonfile(key)

更新JSON檔

Functions:

Q_plot

Q_plot(species: Literal['AS', 'AN', 'OM', 'Soil', 'SS', 'BC', 'Water'] | list[Literal['AS', 'AN', 'OM', 'Soil', 'SS', 'BC', 'Water']], x: Literal['dp', 'sp'] = 'dp', y: Literal['Q', 'MEE'] = 'Q', mode: Literal['ext', 'sca', 'abs'] = 'ext', **kwargs) -> tuple[Figure, Axes]

Generate a plot showing optical efficiency or mass optical efficiency for different particle species.

Parameters:

Name	Type	Description	Default
species	Union[Literal['AS', 'AN', 'OM', 'Soil', 'SS', 'BC', 'Water'], list[Literal['AS', 'AN', 'OM', 'Soil', 'SS', 'BC', 'Water']]]	The particle species or list of particle species to plot. Valid species include 'AS' (Ammonium Sulfate), 'AN' (Ammonium Nitrate), 'OM' (Organic Matter), 'Soil', 'SS' (Sea Salt), 'BC' (Black Carbon), and 'Water'.	required
x	Literal['dp', 'sp']	The x-axis parameter. 'dp' represents particle diameter, and 'sp' represents size parameter (alpha). Default is 'dp'.	'dp'
y	Literal['Q', 'MEE']	The y-axis parameter. 'Q' represents optical efficiency (Q_ext, Q_sca, Q_abs), and 'MEE' represents mass optical efficiency (MEE, MSE, MAE). Default is 'Q'.	'Q'
mode	Literal['ext', 'sca', 'abs']	The mode of efficiency to plot. 'ext' for extinction efficiency, 'sca' for scattering efficiency, and 'abs' for absorption efficiency. Default is 'ext'.	'ext'
**kwargs		Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated plot.

Examples:

Example usage of the Q_plot function:

>>> Q_plot('AS', x='dp', y='Q', mode='ext')
>>> Q_plot(['AS', 'AN'], x='sp', y='MEE')

RI_couple

RI_couple(**kwargs) -> tuple[Figure, Axes]

Generate a plot to test the influence of imaginary parts on scattering and absorption efficiencies.

Parameters:

Name	Type	Description	Default
**kwargs		Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated plot.

Examples:

Example usage of the IJ_couple function:

>>> ax = RI_couple()

RRI_2D

RRI_2D(mode: Literal['ext', 'sca', 'abs'] = 'ext', **kwargs) -> tuple[Figure, Axes]

Generate a 2D plot of scattering efficiency (Q) against real and imaginary parts of the refractive index.

Parameters:

Name	Type	Description	Default
mode	(ext, sca, abs)	The mode of scattering efficiency to plot: - 'ext' for extinction efficiency (Q_ext) - 'sca' for scattering efficiency (Q_sca) - 'abs' for absorption efficiency (Q_abs) Default is 'ext'.	'ext'
**kwargs		Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated 2D plot.

Examples:

Example usage of the RRI_2D function:

>>> RRI_2D(mode='sca', xlabel='Real Part (n)', ylabel='Imaginary Part (k)', title='Scattering Efficiency 2D Plot')

scattering_phase

scattering_phase(m: complex = 1.55 + 0.01j, wave: float = 600, dp: float = 200) -> tuple[Figure, Axes]

Generate a polar plot to visualize the scattering phase function.

Parameters:

Name	Type	Description	Default
m	complex	The complex refractive index of the scattering medium. Default is 1.55 + 0.01j.	1.55 + 0.01j
wave	float	The wavelength of the incident light in nanometers. Default is 600 nm.	600
dp	float	The particle diameter in nanometers. Default is 200 nm.	200

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated polar plot.

Examples:

Example usage of the scattering_phase function:

>>> ax = scattering_phase(m=1.55 + 0.01j, wave=600, dp=200)

response_surface

response_surface(real_range=(1.33, 1.7), gmd_range=(10, 500), num=50, **kwargs) -> tuple[Figure, Axes]

Generate a response surface plot for sensitivity tests of extinction based on Mie scattering.

Parameters:

Name	Type	Description	Default
real_range	tuple	The range of real part (refractive index) values for sensitivity testing. Default is (1.33, 1.7).	(1.33, 1.7)
gmd_range	tuple	The range of geometric mean diameter (GMD) values for sensitivity testing. Default is (60, 400).	(10, 500)
num	int	The number of points to generate within the specified ranges. Default is 50.	50
**kwargs		Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
ax	Axes	Matplotlib Axes object containing the generated response surface plot.

Examples:

Example usage of the response_surface function:

>>> response_surface(real_range=(1.4, 1.6), gmd_range=(100, 300), num=30, xlabel='Real Part (n)',
...                  ylabel='GMD (nm)', zlabel='Extinction (1/Mm)', title='Sensitivity Tests of Extinction')

mie_contribution

mie_contribution(m: complex = 1.8 + 0.1j, wavelengths: float | list[float] = 550, *, geo_mean: float = 140, geo_std: float = 1.95, total_number: float | None = None, total_volume: float | None = None, total_mass: float | None = None, density: float | None = None, mode: str = 'number', dp_range: tuple = (5, 10000), n_bins: int = 500, **kwargs) -> tuple[Figure, tuple[Axes, Axes]]

Which particle sizes of a lognormal mode produce its scattering and absorption.

Top panel: the mode as dN/dlogDp (left axis) and dV/dlogDp (right axis). Bottom panel: per-size contributions dσ_sca/dlogDp and dσ_abs/dlogDp (Mm⁻¹) for each wavelength, the integrated σ_sca / σ_abs in the legend. The area under each lower curve is the bulk coefficient :func:AeroViz.optical.mie_lognormal returns for the same inputs.

Parameters:

Name	Type	Description	Default
m	complex	Refractive index n + ik.	1.8 + 0.1j
wavelengths	float or list of float	Wavelength(s) in nm; several wavelengths share colours and differ in line style.	550
geo_mean	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
geo_std	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
total_number	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
total_volume	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
total_mass	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
density	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
mode	float	The lognormal mode, exactly as :func:generate_lognormal_psd takes it (amount by number, volume or mass + density; mode='volume' reads geo_mean as the volume-mode median).	140
dp_range	tuple	Diameter grid (nm).	(5, 10000)
n_bins	tuple	Diameter grid (nm).	(5, 10000)

Returns:

Type	Description
(fig, (ax_psd, ax_sigma))