cmath --- توابع ریاضی برای اعداد مختلط

---

این ماژول دسترسی به توابع ریاضی مربوط به اعداد مختلط را فراهم می‌کند. توابع این ماژول اعداد صحیح، اعداد ممیز شناور یا اعداد مختلط را به‌عنوان آرگومان می‌پذیرند. این توابع همچنین هر شیء پایتونی را که دارای متد __complex__() یا __float__() باشد نیز می‌پذیرند: این متدها به‌ترتیب برای تبدیل شیء به عدد مختلط یا ممیز شناور استفاده می‌شوند و سپس تابع بر نتیجه‌ی تبدیل اعمال می‌شود.

توجه

برای توابع دارای اسلایس‌های شاخه، مسئله‌ی تصمیم‌گیری درباره‌ی نحوه‌ی تعریف آن توابع روی خود اسلایس وجود دارد. با پیروی از مقاله‌ی Kahan با عنوان «Branch cuts for complex elementary functions»، و همچنین پیوست G از C99 و استانداردهای بعدی C، از علامت صفر برای تمایز یک سمت اسلایس شاخه از سمت دیگر استفاده می‌کنیم: برای اسلایس شاخه در امتداد (بخشی از) محور حقیقی، علامت بخش موهومی را در نظر می‌گیریم، در حالی که برای اسلایس شاخه در امتداد محور موهومی، علامت بخش حقیقی را در نظر می‌گیریم.

برای مثال، تابع cmath.sqrt() دارای یک اسلایس شاخه‌ای در امتداد محور حقیقی منفی است. با آرگومانی به مقدار -2-0j به‌گونه‌ای رفتار می‌شود که گویی در زیر اسلایس شاخه‌ای قرار دارد، و بنابراین نتیجه‌ای روی محور موهومی منفی می‌دهد:

>>> cmath.sqrt(-2-0j)
-1.4142135623730951j

اما آرگومانِ -2+0j به‌گونه‌ای رفتار می‌شود که گویی در بالای اسلایس شاخه (branch cut) قرار دارد:

>>> cmath.sqrt(-2+0j)
1.4142135623730951j

تبدیل‌ها به مختصات قطبی و از مختصات قطبی
phase(z)	فاز z را برمی‌گرداند
polar(z)	بازگرداندن نمایش z در مختصات قطبی
rect(r, phi)	عدد مختلط z را با مختصات قطبی r و phi برمی‌گرداند
توابع توانی و لگاریتمی
exp(z)	e به توان z را برمی‌گرداند
log(z[, base])	لگاریتم z را در مبنای base داده‌شده برمی‌گرداند (به‌طور پیش‌فرض e)
log10(z)	لگاریتم z در مبنای ۱۰ را برمی‌گرداند
sqrt(z)	ریشه دوم z را برمی‌گرداند
توابع مثلثاتی
acos(z)	آرک‌کسینوس z را برمی‌گرداند
asin(z)	برگرداندن سینوس معکوس z
atan(z)	تانژانت معکوس z را برمی‌گرداند
cos(z)	کسینوس z را برمی‌گرداند
sin(z)	سینوس z را برمی‌گرداند
tan(z)	تانژانت z را برمی‌گرداند
توابع هذلولی
acosh(z)	بازگرداندن کسینوس هیپربولیک معکوس z
asinh(z)	سینوس هذلولی معکوس z را برمی‌گرداند
atanh(z)	تانژانت هیپربولیک معکوس z را برمی‌گرداند
cosh(z)	کسینوس هذلولی z را برمی‌گرداند
sinh(z)	سینوس هذلولی z را برمی‌گرداند
tanh(z)	تانژانت هیپربولیک z را برمی‌گرداند
توابع طبقه‌بندی
isfinite(z)	بررسی متناهی بودن همه‌ی کامپوننت‌های z
isinf(z)	بررسی کنید که آیا هیچ‌یک از کامپوننت‌های z بی‌نهایت است یا خیر
isnan(z)	بررسی کنید که آیا یکی از کامپوننت‌های z یک NaN است یا خیر
isclose(a, b, *, rel_tol, abs_tol)	بررسی کنید که آیا مقادیر a و b به یکدیگر نزدیک هستند
ثابت‌ها
pi	π = 3.141592...
e	e = 2.718281...
tau	τ = 2π = 6.283185...
inf	بی‌نهایت مثبت
infj	بی‌نهایت موهومی خالص
nan	«عدد نامعتبر» (NaN)
nanj	NaN موهومی خالص

تبدیل‌ها به مختصات قطبی و بالعکس

یک عدد مختلط در پایتون z به‌صورت داخلی با استفاده از مختصات مستطیلی یا دکارتی ذخیره می‌شود. این عدد به‌طور کامل توسط بخش حقیقی z.real و بخش موهومی z.imag آن تعیین می‌شود.

مختصات قطبی روشی جایگزین برای نمایش یک عدد مختلط ارائه می‌دهد. در مختصات قطبی، یک عدد مختلط z با اندازه‌ی r و زاویه‌ی فاز phi تعریف می‌شود. اندازه‌ی r فاصله‌ی z تا مبدأ است، در حالی که فاز phi زاویه‌ای در خلاف جهت عقربه‌های ساعت است که بر حسب رادیان، از محور x مثبت تا پاره‌خطی که مبدأ را به z متصل می‌کند، اندازه‌گیری می‌شود.

می‌توان از توابع زیر برای تبدیل از مختصات مستطیلی ذاتی به مختصات قطبی و بالعکس استفاده کرد.

cmath.phase(z)

فاز z (که همچنین به‌عنوان آرگومان z نیز شناخته می‌شود) را به‌صورت یک شناور برمی‌گرداند. phase(z) معادل math.atan2(z.imag, z.real) است. نتیجه در بازه‌ی [-π, π] قرار دارد و اسلایس شاخه‌ی این عملیات در امتداد محور حقیقی منفی قرار دارد. علامت نتیجه همان علامت z.imag است، حتی زمانی که z.imag صفر باشد:

>>> phase(-1+0j)
3.141592653589793
>>> phase(-1-0j)
-3.141592653589793

توجه

مدول (قدر مطلق) یک عدد مختلط z را می‌توان با استفاده از تابع توکار abs() محاسبه کرد. برای این عملیات، تابع جداگانه‌ای در ماژول cmath وجود ندارد.

cmath.polar(z)

بازگرداندن نمایش z در مختصات قطبی. یک جفت (r, phi) برمی‌گرداند که در آن r اندازه‌ی z و phi فاز z است. polar(z) معادل (abs(z), phase(z)) است.

cmath.rect(r, phi)

عدد مختلط z با مختصات قطبی r و phi را برمی‌گرداند. معادل complex(r * math.cos(phi), r * math.sin(phi)) است.

توابع توانی و لگاریتمی

cmath.exp(z)

مقدار e به توان z را برمی‌گرداند، که e پایه‌ی لگاریتم طبیعی است.

cmath.log(z[, base])

لگاریتم z را در base داده‌شده برمی‌گرداند. اگر base مشخص نشده باشد، لگاریتم طبیعی z را برمی‌گرداند. یک اسلایس شاخه (branch cut) از ۰ در امتداد محور حقیقی منفی تا -∞ وجود دارد.

cmath.log10(z)

لگاریتم z در مبنای ۱۰ را برمی‌گرداند. این تابع همان اسلایس شاخه‌ی log() را دارد.

cmath.sqrt(z)

ریشه دوم z را برمی‌گرداند. این تابع همان اسلایس شاخه‌ی log() را دارد.

توابع مثلثاتی

cmath.acos(z)

آرک‌کسینوس z را برمی‌گرداند. دو اسلایس شاخه وجود دارد: یکی از ۱ به سمت راست در امتداد محور حقیقی تا ∞ ادامه دارد. دیگری از -۱ به سمت چپ در امتداد محور حقیقی تا -∞ ادامه دارد.

cmath.asin(z)

آرک‌سینوس z را برمی‌گرداند. این همان اسلایس‌های شاخه‌ای acos() را دارد.

cmath.atan(z)

آرک‌تانژانت z را برمی‌گرداند. دو اسلایس شاخه وجود دارد: یکی از 1j در امتداد محور موهومی تا ∞j ادامه دارد. دیگری از -1j در امتداد محور موهومی تا -∞j ادامه دارد.

cmath.cos(z)

کسینوس z را برمی‌گرداند.

cmath.sin(z)

سینوس z را برمی‌گرداند.

cmath.tan(z)

تانژانت z را برمی‌گرداند.

توابع هذلولی

cmath.acosh(z)

کسینوس هیپربولیک معکوس z را برمی‌گرداند. یک اسلایس شاخه وجود دارد که از ۱ به سمت چپ در امتداد محور حقیقی تا -∞ ادامه دارد.

cmath.asinh(z)

سینوس هذلولی معکوس z را برمی‌گرداند. دو اسلایس شاخه وجود دارد: یکی از 1j در امتداد محور موهومی تا ∞j کشیده شده است. دیگری از -1j در امتداد محور موهومی تا -∞j کشیده شده است.

cmath.atanh(z)

تانژانت هیپربولیک معکوس z را بازمی‌گرداند. دو اسلایس شاخه وجود دارد: یکی از 1 در امتداد محور حقیقی تا ∞ ادامه دارد. دیگری از -1 در امتداد محور حقیقی تا -∞ ادامه دارد.

cmath.cosh(z)

کسینوس هذلولی z را برمی‌گرداند.

cmath.sinh(z)

سینوس هذلولی z را برمی‌گرداند.

cmath.tanh(z)

تانژانت هذلولی z را برمی‌گرداند.

توابع طبقه‌بندی

cmath.isfinite(z)

اگر هر دو بخش حقیقی و موهومی z متناهی باشند، True و در غیر این صورت False را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.2.

cmath.isinf(z)

اگر بخش حقیقی یا موهومی z بی‌نهایت باشد، True را برمی‌گرداند و در غیر این صورت False را برمی‌گرداند.

cmath.isnan(z)

اگر بخش حقیقی یا موهومی z برابر با NaN باشد، True و در غیر این صورت False برمی‌گرداند.

cmath.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

اگر مقادیر a و b به یکدیگر نزدیک باشند، True و در غیر این صورت False برمی‌گرداند.

نزدیک بودن یا نبودن دو مقدار بر اساس تحمل‌های مطلق و نسبی داده‌شده تعیین می‌شود. اگر هیچ خطایی رخ ندهد، نتیجه به‌صورت زیر خواهد بود: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol).

rel_tol مدارای نسبی است — این مقدار حداکثر اختلاف مجاز بین a و b، نسبت به قدر مطلق بزرگ‌تر بین a و b است. برای مثال، برای تنظیم مدارای ۵٪، مقدار rel_tol=0.05 را ارسال کنید. مدارای پیش‌فرض 1e-09 است، که تضمین می‌کند دو مقدار تا حدود ۹ رقم اعشاری یکسان باشند. rel_tol باید غیرمنفی و کمتر از 1.0 باشد.

abs_tol تحمل مطلق است؛ پیش‌فرض آن 0.0 است و باید غیرمنفی باشد. هنگامی که x را با 0.0 مقایسه می‌کنید، isclose(x, 0) به‌صورت abs(x) <= rel_tol  * abs(x) محاسبه می‌شود، که برای هر x و rel_tol کمتر از 1.0، False است. بنابراین آرگومان abs_tol مثبت مناسبی به فراخوانی اضافه کنید.

مقادیر ویژه‌ی IEEE 754 یعنی NaN، inf و -inf طبق قوانین IEEE مدیریت می‌شوند. به‌طور مشخص، NaN نزدیک به هیچ مقدار دیگری، از جمله NaN، در نظر گرفته نمی‌شود. inf و -inf تنها به خودشان نزدیک در نظر گرفته می‌شوند.

اضافه شده در نسخه‌ی 3.5.

همچنین ملاحظه نمائید

PEP 485 -- تابعی برای آزمون برابری تقریبی

ثابت‌ها

cmath.pi

ثابت ریاضی π، به‌عنوان یک عدد اعشاری .

cmath.e

ثابت ریاضی e، به‌عنوان یک float.

cmath.tau

ثابت ریاضی τ، به‌صورت یک عدد اعشاری.

اضافه شده در نسخه‌ی 3.6.

cmath.inf

بی‌نهایت مثبت از نوع ممیز شناور. معادل float('inf').

اضافه شده در نسخه‌ی 3.6.

cmath.infj

عدد مختلط با بخش حقیقی صفر و بخش موهومی بی‌نهایت مثبت. معادل complex(0.0, float('inf')).

اضافه شده در نسخه‌ی 3.6.

cmath.nan

یک مقدار ممیز شناور «نه یک عدد» (NaN). معادل float('nan'). همچنین math.nan را ببینید.

اضافه شده در نسخه‌ی 3.6.

cmath.nanj

عدد مختلط با بخش حقیقی صفر و بخش موهومی NaN. معادل با complex(0.0, float('nan')).

اضافه شده در نسخه‌ی 3.6.

توجه داشته باشید که انتخاب توابع مشابه، اما نه یکسان، با انتخاب توابع در ماژول math است. دلیل وجود دو ماژول این است که برخی کاربران علاقه‌ای به اعداد مختلط ندارند، و شاید حتی ندانند این اعداد چه هستند. آن‌ها ترجیح می‌دهند math.sqrt(-1) به‌جای برگرداندن یک عدد مختلط، یک استثنا پرتاب کند. همچنین توجه داشته باشید که توابع تعریف‌شده در cmath همیشه یک عدد مختلط برمی‌گردانند، حتی اگر پاسخ بتواند به‌صورت یک عدد حقیقی بیان شود (در این حالت عدد مختلط دارای بخش موهومی صفر است).

نکته‌ای درباره‌ی اسلایس‌های شاخه (branch cuts): این‌ها منحنی‌هایی هستند که تابع داده‌شده در امتداد آن‌ها پیوسته نیست. آن‌ها ویژگی ضروری بسیاری از توابع مختلط هستند. فرض بر این است که اگر نیاز به محاسبه با توابع مختلط دارید، درباره‌ی اسلایس‌های شاخه آگاه خواهید بود. برای روشن شدن موضوع، تقریباً به هر کتابی (نه خیلی مقدماتی) درباره‌ی متغیرهای مختلط مراجعه کنید. برای اطلاع از انتخاب مناسب اسلایس‌های شاخه برای اهداف عددی، یک مرجع خوب باید مورد زیر باشد:

همچنین ملاحظه نمائید

Kahan، W: برش‌های شاخه‌ای برای توابع ابتدایی مختلط؛ یا، هیاهوی بسیار بر سر بیت علامت هیچ. در Iserles، A. و Powell، M. (ویراستاران)، وضعیت کنونی تحلیل عددی. انتشارات Clarendon (۱۹۸۷)، صص. ۱۶۵--۲۱۱.