Pythonライブラリ「quantities」詳解：物理量と単位をエレガントに扱う

はじめに：なぜ`quantities`なのか？ 🤔

科学技術計算、特に物理学や工学の分野でPythonを使用する際、数値だけでなく「単位」を一緒に扱いたい場面は非常に多いです。例えば、「10 メートル」と「5 秒」から速度を計算する場合、結果が「2 メートル毎秒」であることを保証したいですよね。単位の計算ミスは、時に致命的な結果（例：マーズ・クライメイト・オービターの事故）を招くこともあります。

ここで登場するのが、`quantities` ライブラリです。このライブラリは、数値（大きさ）と単位（次元）を組み合わせた「物理量 (Quantity)」オブジェクトを提供し、単位付きの計算や単位変換を直感的かつ安全に行うことを可能にします。

`quantities`は、科学技術計算のデファクトスタンダードであるNumPyをベースにしており、NumPy配列やユニバーサル関数（ufunc）との連携もスムーズです。これにより、ベクトルや行列演算においても単位情報を保持したまま計算を進めることができます。

この記事では、`quantities`ライブラリの基本的な使い方から、単位変換、NumPyとの連携、さらには少し高度な機能まで、具体的なコード例を交えながら詳しく解説していきます。物理量計算の手間やミスを減らし、より本質的な計算に集中するための一助となれば幸いです。🚀

インストール：さあ、始めよう！ 💻

`quantities`ライブラリを使用するには、まずインストールが必要です。`quantities`はNumPyに依存しているため、NumPyがまだインストールされていない場合は、先にNumPyをインストールしてください。

インストールは、Pythonのパッケージインストーラーである`pip`を使うのが最も簡単です。ターミナルまたはコマンドプロンプトを開き、以下のコマンドを実行してください。

pip install numpy
pip install quantities

通常、これでNumPyと`quantities`の両方がインストールされます。NumPyが既にインストールされている場合は、2行目の`pip install quantities`だけでOKです。

インストールが成功したか確認するには、Pythonインタプリタを起動し、`quantities`をインポートしてみましょう。エラーが出なければ成功です。

import quantities as pq

print(f"quantities version: {pq.__version__}")

慣例として、`quantities`は`pq`という別名でインポートされることが多いです（”physical quantities” または “python quantities” の略）。これにより、コード内で単位や関数を呼び出す際に `pq.meter` や `pq.Quantity(…)` のように記述でき、可読性が向上します。

基本的な使い方：Quantityオブジェクトの作成と操作 ✨

`quantities`の中心となるのは`Quantity`オブジェクトです。これは数値（大きさ）と単位のペアを表します。`Quantity`オブジェクトを作成する最も簡単な方法は、数値と`pq`モジュールで定義されている単位オブジェクトを掛け合わせることです。

import quantities as pq
import numpy as np

# スカラー値で作成
distance = 10.0 * pq.meter
time = 5.0 * pq.second

print(f"Distance: {distance}")
print(f"Time: {time}")
print(f"Type of distance: {type(distance)}")

# リストやNumPy配列でも作成可能
lengths = [1, 2, 3] * pq.kilometer
pressures = np.array([101.3, 102.5, 100.1]) * pq.kPa # kPa = kiloPascal

print(f"Lengths: {lengths}")
print(f"Pressures: {pressures}")

出力を見ると、数値と単位が一緒に表示されていることがわかります。`type()`で確認すると、`quantities.quantity.Quantity`クラスのインスタンスになっていることが確認できます。

`Quantity`オブジェクトの数値部分（大きさ）と単位部分（次元）には、それぞれ`.magnitude`属性と`.dimensionality`（または`.units`）属性でアクセスできます。

speed = 25.0 * pq.m / pq.s # メートル毎秒

print(f"Speed: {speed}")
print(f"Magnitude: {speed.magnitude}") # 数値部分を取得
print(f"Dimensionality: {speed.dimensionality}") # 次元（単位）を取得
print(f"Units: {speed.units}") # .unitsでも同じ

# .magnitudeはNumPy配列を返す
print(f"Magnitude of pressures: {pressures.magnitude}")
print(f"Type of magnitude: {type(pressures.magnitude)}")

`.magnitude`は元の数値（スカラーまたはNumPy配列）を返します。`.dimensionality`や`.units`は、単位を表す`Dimensionality`オブジェクトを返します。

`Quantity`コンストラクタの使用

`pq.Quantity()`コンストラクタを使って`Quantity`オブジェクトを作成することもできます。この方法では、単位を文字列で指定することも可能です。

# 単位を文字列で指定
energy_str = pq.Quantity(100.0, 'J') # 'J' はジュール
print(f"Energy (from string): {energy_str}")

# 単位オブジェクトで指定
energy_obj = pq.Quantity(100.0, pq.joule)
print(f"Energy (from object): {energy_obj}")

# NumPy配列と単位文字列
temps_c = pq.Quantity(np.array([0, 25, 100]), 'degC') # 摂氏温度
print(f"Temperatures (Celsius): {temps_c}")

# 文字列での単位指定では、複数形も認識される場合がある
length_feet_str = pq.Quantity(10.0, 'feet')
print(f"Length (feet, from string): {length_feet_str}")
# ただし、pq.feetのような変数名は単数形のみ (pq.foot)
# length_feet_obj = 10.0 * pq.feet # これはエラーになる

文字列で単位を指定する場合、`’meter’`、`’second’`、`’kg’`、`’Joule’`、`’m/s’`、`’kg*m/s**2’` のような一般的な単位記号や名称、それらの組み合わせが利用できます。ただし、`pq`モジュール内の単位変数（`pq.meter`など）を使用する方が、タイプミスを防ぎやすく、エディタの補完機能も利用できるため推奨されます。

単位の変更

既存の`Quantity`オブジェクトの単位を、互換性のある別の単位に「再スケール」せずに、単純に単位情報だけを変更することも可能です（通常は推奨されませんが、特定の状況で役立つ場合があります）。これは`.units`属性に新しい単位を代入することで行います。ただし、これは値の変換を行わず、単位ラベルだけを付け替える操作なので注意が必要です。値も含めて変換する場合は後述の`.rescale()`を使用します。

# 例：1 メートルを、値を変えずに単位だけフィートにする (非推奨な使い方)
q_m = 1.0 * pq.m
print(f"Original: {q_m}")

q_m.units = pq.ft # 値は1.0のまま、単位だけ 'ft' になる
print(f"Units reassigned (incorrect value): {q_m}")
# 本来 1 m は約 3.28 ft なので、値が不正確になっている

単位変換：`.rescale()` メソッド 🔄

`quantities`ライブラリの最も強力な機能の一つが、単位変換です。物理的に互換性のある単位間（例：メートルとフィート、ジュールとカロリー）で、値を適切にスケールしながら変換を行うことができます。これには`.rescale()`メソッドを使用します。

import quantities as pq

# 長さの変換
length_m = 10.0 * pq.meter
print(f"Original length: {length_m}")

length_ft = length_m.rescale(pq.foot) # メートルをフィートに変換
print(f"Length in feet: {length_ft}")

length_km = length_m.rescale(pq.kilometer) # メートルをキロメートルに変換
print(f"Length in kilometers: {length_km}")

# エネルギーの変換
energy_j = 1000.0 * pq.J # ジュール
print(f"Original energy: {energy_j}")

energy_cal = energy_j.rescale(pq.cal) # ジュールをカロリーに変換 (thermochemical calorie)
print(f"Energy in calories: {energy_cal}")

energy_kcal = energy_j.rescale(pq.kcal) # ジュールをキロカロリーに変換
print(f"Energy in kilocalories: {energy_kcal}")

# 速度の変換
speed_mps = 20.0 * pq.m / pq.s # メートル毎秒
print(f"Original speed: {speed_mps}")

speed_kmh = speed_mps.rescale(pq.km / pq.h) # メートル毎秒をキロメートル毎時に変換
print(f"Speed in km/h: {speed_kmh}")

# NumPy配列の単位変換も同様
distances_mile = np.array([1.0, 5.0, 10.0]) * pq.mile
print(f"Distances in miles: {distances_mile}")

distances_km = distances_mile.rescale(pq.km) # マイルをキロメートルに変換
print(f"Distances in km: {distances_km}")

`.rescale()`メソッドは、変換先の単位を引数として受け取ります。単位は`pq.foot`のように単位オブジェクトで指定することも、`’km/h’`のように文字列で指定することも可能です。

try:
    length_m.rescale(pq.kg) # メートルをキログラムに変換しようとする
except ValueError as e:
    print(f"Error: {e}") # => Error: Unable to convert between units of "m" and "kg"

`.rescale()`は新しい`Quantity`オブジェクトを返すため、元のオブジェクトは変更されません。インプレース（元のオブジェクトを直接変更）で単位変換を行いたい場合は、`.rescale_inplace()`メソッドを使用できますが、通常は新しいオブジェクトを生成する`.rescale()`の方が安全で推奨されます。

物理量の演算：単位を意識した計算 ➕➖✖️➗

`quantities`オブジェクト同士、あるいは`quantities`オブジェクトと通常の数値（スカラーまたはNumPy配列）の間で、四則演算（`+`, `-`, `*`, `/`）やべき乗（`**`）などの数学演算を行うことができます。演算結果の単位は、物理法則に従って自動的に計算されます。

加算と減算

加算と減算は、同じ物理次元を持つ`Quantity`オブジェクト間でのみ可能です。単位が異なる場合でも、互換性があれば自動的に一方の単位に揃えられて計算されます（通常は左辺の単位）。

import quantities as pq

# 同じ単位での加算・減算
length1 = 10.0 * pq.m
length2 = 5.0 * pq.m
total_length_m = length1 + length2
diff_length_m = length1 - length2
print(f"{length1} + {length2} = {total_length_m}")
print(f"{length1} - {length2} = {diff_length_m}")

# 異なる互換単位での加算・減算
length_km = 1.0 * pq.km
total_length_mixed = length1 + length_km # 10 m + 1 km
print(f"{length1} + {length_km} = {total_length_mixed}") # 結果は左辺の単位 'm' になる
# => 10.0 m + 1.0 km = 1010.0 m

# .rescale() を使って単位を揃えてから計算も可能
total_length_km_explicit = length1.rescale(pq.km) + length_km
print(f"{length1.rescale(pq.km)} + {length_km} = {total_length_km_explicit}") # 結果は 'km'
# => 0.01 km + 1.0 km = 1.01 km

乗算と除算

乗算と除算は、異なる単位を持つ`Quantity`オブジェクト間でも可能です。結果の単位は、それぞれの単位の積または商になります。

import quantities as pq

distance = 100.0 * pq.m
time = 10.0 * pq.s

# 速度 = 距離 / 時間
velocity = distance / time
print(f"Velocity ({distance} / {time}) = {velocity}") # 結果の単位は m/s

# 力 = 質量 * 加速度
mass = 5.0 * pq.kg
acceleration = 9.8 * pq.m / pq.s**2
force = mass * acceleration
print(f"Force ({mass} * {acceleration}) = {force}") # 結果の単位は kg*m/s**2 (ニュートン)

# 力の単位をニュートンに変換して表示
print(f"Force in Newtons: {force.rescale(pq.N)}")

# 仕事 = 力 * 距離
work = force * distance
print(f"Work ({force} * {distance}) = {work}") # 結果の単位は kg*m**2/s**2 (ジュール)

# 仕事の単位をジュールに変換して表示
print(f"Work in Joules: {work.rescale(pq.J)}")

べき乗

`Quantity`オブジェクトのべき乗も計算できます。単位も適切に累乗されます。

import quantities as pq

length = 5.0 * pq.m

# 面積 = 長さ^2
area = length**2
print(f"Area ({length}**2) = {area}") # 結果の単位は m**2

# 体積 = 長さ^3
volume = length**3
print(f"Volume ({length}**3) = {volume}") # 結果の単位は m**3

# 逆数 (単位も逆数になる)
inv_length = length**-1
print(f"Inverse Length ({length}**-1) = {inv_length}") # 結果の単位は 1/m

単位のない数値（次元なし）との演算

`Quantity`オブジェクトと単位のない通常の数値（スカラーまたはNumPy配列）との乗算・除算は可能です。結果は元の`Quantity`オブジェクトと同じ単位を持ちます。

import quantities as pq
import numpy as np

length = 10.0 * pq.m
scalar = 2.0
arr = np.array([1, 2, 3])

result1 = length * scalar
result2 = length / scalar
result3 = length * arr

print(f"{length} * {scalar} = {result1}")
print(f"{length} / {scalar} = {result2}")
print(f"{length} * {arr} = {result3}")

しかし、`Quantity`オブジェクトと単位のない数値との間で加算・減算を行おうとすると、次元が一致しないため`ValueError`が発生します。これは、物理的に意味のない計算（例：長さに単なる数を足す）を防ぐための重要な機能です。

try:
    error_result = length + scalar
except ValueError as e:
    print(f"Error adding Quantity and scalar: {e}")
    # => Error: Unable to convert between units of "m" and "dimensionless"

NumPy との連携：科学計算の強力な味方 🤝

`quantities`の大きな利点の一つは、NumPyとのシームレスな統合です。`Quantity`オブジェクトはNumPyの`ndarray`をサブクラス化（継承）しているため、多くのNumPy関数や操作を単位情報を保持したまま利用できます。

import quantities as pq
import numpy as np

# NumPy配列からQuantityオブジェクトを作成
velocities_mps = np.array([10.0, 20.0, 30.0]) * pq.m / pq.s
print(f"Velocities: {velocities_mps}")

# NumPyのufunc（ユニバーサル関数）の適用
mean_velocity = np.mean(velocities_mps)
std_dev_velocity = np.std(velocities_mps)
print(f"Mean velocity: {mean_velocity}") # 結果もQuantityオブジェクト
print(f"Standard deviation: {std_dev_velocity}") # 結果もQuantityオブジェクト

# 平方根 (単位も平方根が取られる)
energies = np.array([100, 400, 900]) * pq.J
sqrt_energies = np.sqrt(energies)
print(f"Energies: {energies}")
print(f"Square root of energies: {sqrt_energies}") # 単位は J**0.5

# 三角関数 (引数が角度の単位を持つ必要がある)
angles_deg = np.array([0, 30, 90]) * pq.deg # 度単位
angles_rad = angles_deg.rescale(pq.rad) # ラジアンに変換

sin_values = np.sin(angles_rad) # NumPyのsin関数はラジアンを期待する
print(f"Angles in degrees: {angles_deg}")
print(f"Angles in radians: {angles_rad}")
# sin関数の結果は次元なし (dimensionless) Quantity になる
print(f"Sine of angles: {sin_values}")
print(f"Result type: {type(sin_values)}")
print(f"Result dimensionality: {sin_values.dimensionality}")

# 単位が不適切な場合のエラー
try:
    np.sin(angles_deg) # 度単位のままsin関数に渡す
except ValueError as e:
    # (注意: quantitiesのバージョンやNumPyの実装によってはエラーにならない場合もあるが、
    #  通常、三角関数にはラジアンが期待されるため、単位変換が推奨される)
    print(f"Potential issue with sin(degrees): {e}") # エラーが出る場合がある

多くのNumPy関数（`mean`, `sum`, `std`, `min`, `max`, `sqrt`, `log`, `exp`など）は、`Quantity`オブジェクトを入力として受け付け、結果も単位情報を持った`Quantity`オブジェクトとして返します。

三角関数（`sin`, `cos`, `tan`など）のように、特定の単位（通常はラジアン）を期待する関数については、入力`Quantity`オブジェクトを`.rescale()`で適切な単位に変換してから渡す必要があります。結果は通常、次元のない（dimensionless）`Quantity`オブジェクトになります。

配列の結合や操作

NumPyの配列操作関数（`concatenate`, `vstack`, `hstack`など）を使用する際には注意が必要です。これらの関数は`Quantity`オブジェクトの単位情報を正しく扱えない場合があります。

import quantities as pq
import numpy as np

arr1 = np.array([1, 2, 3]) * pq.m
arr2 = np.array([4, 5, 6]) * pq.m

# NumPyのconcatenateを使うと単位情報が失われるか、'dimensionless'になることがある
concatenated_np = np.concatenate([arr1, arr2])
print(f"Concatenated with np.concatenate: {concatenated_np}")
print(f"Dimensionality: {concatenated_np.dimensionality}") # 'dimensionless' になることが多い

# 正しく単位を維持するには、一度magnitudeを取り出してから再結合し、単位を付け直す
magnitudes = np.concatenate([arr1.magnitude, arr2.magnitude])
concatenated_correct = magnitudes * pq.m
# または concatenated_correct = pq.Quantity(magnitudes, pq.m)
print(f"Concatenated correctly: {concatenated_correct}")
print(f"Dimensionality: {concatenated_correct.dimensionality}")

2018年頃の情報では、`np.concatenate`などが`Quantity`オブジェクトの単位を維持せず、結果が`dimensionless`になるという報告があります。安全のため、配列を結合する際は、一度`.magnitude`で数値部分（NumPy配列）を取り出し、NumPy関数で結合した後、再度`Quantity`オブジェクトを作成するのが確実です。

このように、`quantities`はNumPyのエコシステムと深く連携しており、科学技術計算における単位付きデータの扱を大幅に簡便化・安全化します。ただし、一部のNumPy関数との互換性には注意が必要です。

高度な機能とヒント 💡

`quantities`には、基本的な使い方以外にも便利な機能がいくつかあります。

単位の単純化 (`.simplified`)

複雑な計算を行うと、結果の単位が `kg*m**2/(s**2*A)` のように基本的な単位の組み合わせで表現されることがあります。`.simplified`属性を使うと、これをより一般的な（通常はSI基本単位系の）既約な形式に変換できます。

import quantities as pq

force = 10.0 * pq.N # ニュートン
distance = 5.0 * pq.m # メートル
time = 2.0 * pq.s # 秒

# 複雑な計算例
complex_quantity = force * distance / time**2
print(f"Complex quantity: {complex_quantity}") # => 25.0 N*m/s**2

# 単位を単純化 (SI基本単位に)
simplified_quantity = complex_quantity.simplified
print(f"Simplified quantity (SI): {simplified_quantity}") # => 25.0 kg*m**2/s**4

# ジュール (J = kg*m**2/s**2) の単純化
joule_simplified = pq.J.simplified
print(f"Joule simplified (SI): {joule_simplified}") # => 1.0 kg*m**2/s**2

# デフォルトの単純化単位系を変更 (例: cgs単位系)
pq.set_default_units('cgs')
joule_simplified_cgs = pq.J.simplified
print(f"Joule simplified (CGS): {joule_simplified_cgs}") # => 10000000.0 g*cm**2/s**2

# デフォルトをSIに戻す (特定の単位を指定も可能)
pq.set_default_units(length='m', mass='kg', time='s') # SI基本単位を指定
joule_simplified_back_to_SI = pq.J.simplified
print(f"Joule simplified (back to SI): {joule_simplified_back_to_SI}")

`.simplified`は、単位の次元が正しいかを確認したり、異なる計算結果を標準的な形式で比較したりするのに役立ちます。`pq.set_default_units()`を使うことで、単純化の基準となる単位系（’SI’、’cgs’など）を変更することも可能です。

物理定数 (`pq.constants`)

`quantities`には、よく使われる物理定数が`pq.constants`モジュール内に`Quantity`オブジェクトとして定義されています。これにより、定数の値を手入力する手間やミスを防ぐことができます。

import quantities as pq
from quantities import constants as const # or import quantities.constants as const

# 光速
print(f"Speed of light (c): {const.c}")
print(f"Speed of light in km/s: {const.c.rescale(pq.km/pq.s)}")

# プランク定数
print(f"Planck constant (h): {const.h}")

# ボルツマン定数
print(f"Boltzmann constant (k): {const.k}") # ドキュメントでは k_B となっている場合もあるが、k でアクセス可能

# アボガドロ定数
print(f"Avogadro constant (N_A): {const.N_A}")

# 定数を使った計算例: 光子のエネルギー E = h * c / lambda
wavelength = 500 * pq.nm # 500ナノメートル
photon_energy = const.h * const.c / wavelength
print(f"Energy of a 500nm photon: {photon_energy}")
print(f"Photon energy in electron volts (eV): {photon_energy.rescale(pq.eV)}")

これらの定数は単位情報を持っているため、他の`Quantity`オブジェクトとの計算にそのまま使用できます。利用可能な定数の一覧は、`quantities`のドキュメントや `dir(pq.constants)` で確認できます。

ユーザー定義単位

`quantities`に定義されていない独自の単位を作成することも可能です。`pq.UnitQuantity`クラスを使います。

import quantities as pq

# 例: 1マイクロケルビン (uK) を定義
# UnitQuantity(名前, 基準単位での値, 記号)
uK = pq.UnitQuantity('microkelvin', pq.K / 1e6, symbol='uK')

print(f"Definition of microkelvin: {uK}")

# 作成した単位を使用
temperature = 1500 * uK
print(f"Temperature: {temperature}")

# 他の単位に変換
temp_in_K = temperature.rescale(pq.K)
print(f"Temperature in Kelvin: {temp_in_K}")
temp_in_mK = temperature.rescale(pq.mK) #ミリケルビン
print(f"Temperature in milliKelvin: {temp_in_mK}")

`UnitQuantity`の第一引数に単位の名称（文字列）、第二引数にその単位が基準となる単位（通常はSI単位）でどのくらいの大きさかを示す`Quantity`オブジェクト、第三引数（オプション）に記号（`symbol`）を指定します。

不確かさ (Uncertainty)

`quantities`のドキュメントでは、「possibly an uncertainty（不確かさも持つ可能性がある）」と言及されていますが、具体的な不確かさの伝播計算に関する機能は、コアライブラリには明確に実装されていないようです（あるいは別ライブラリとの連携が必要かもしれません）。物理量の不確かさを厳密に扱いたい場合は、`uncertainties`ライブラリなど、他の専門ライブラリとの併用を検討する必要があるかもしれません。

他の単位計算ライブラリとの比較 🆚

Pythonには、`quantities`以外にも物理単位を扱うためのライブラリがいくつか存在します。代表的なものとして`Pint`と`Astropy Units`があります。それぞれの特徴と`quantities`との違いを簡単に比較します。

また、シンプルな単位付き数値の入力・出力に特化した`QuantiPhy`や、自然言語テキストから数量と単位を抽出する`quantulum3`といったライブラリも存在します。用途に応じて適切なライブラリを選択することが重要です。

まとめ：`quantities`で安全な物理量計算を！ 🎉

Pythonライブラリ`quantities`は、物理量（数値と単位のペア）を扱うための強力で便利なツールです。主な利点を再確認しましょう。

• ✅ 単位の自動管理: 計算中に単位が自動的に追跡され、次元的に整合性のない演算を防ぎます。
• ✅ 簡単な単位変換: `.rescale()`メソッドにより、互換性のある単位間での変換が容易に行えます。
• ✅ NumPyとの高い親和性: NumPy配列や多くのufuncとシームレスに連携し、ベクトル・行列演算でも単位を保持できます。
• ✅ 豊富な定義済み単位・定数: SI単位系を中心に、多くの単位や物理定数が組み込まれています。
• ✅ 可読性の向上: コード内で単位が明示されるため、計算の意味が分かりやすくなります。

一方で、いくつかの注意点もあります。

• ⚠️ 一部のNumPy関数（配列結合など）では単位情報が失われる可能性があり、対処が必要です。
• ⚠️ 不確かさの扱いは標準機能としては限定的かもしれません。
• ⚠️ ミッションクリティカルな用途での利用は、テストカバレッジの観点から非推奨とされています（開発状況による）。

`quantities`を使うことで、科学技術計算における単位管理の手間を大幅に削減し、計算ミスを防ぎ、コードの信頼性と可読性を向上させることができます。物理シミュレーション、データ解析、工学計算など、単位が重要となるあらゆる場面で、`quantities`はあなたの強力な味方となるでしょう。

ぜひ`pip install quantities`して、その便利さを体験してみてください！ 😊