إضافة وثائق مبدئية للمعادلات الرياضية لحساب الزكاة

README.ar.md

@@ -61,6 +61,8 @@
 
 - [آلية الزكاة: خوارزمية الغرف والصناديق](./docs/algorithm.ar.md)
 
+- [صيغة الزكاة: تمثيل رياضي للصدقة الإسلامية](./docs/mathematics.ar.md)
+
 ### ابدأ الآن:
 
 قم بتثبيت مكتبة الزكاة (Zakat) باستخدام pip:

README.md

@@ -21,9 +21,9 @@ Zakat is a user-friendly Python library designed to simplify the tracking and ca
 
 - Automated Zakat Calculation: Automatically calculate Zakat due based on the Nisab (minimum threshold), Haul (time cycles) and the current market price of silver, simplifying compliance with Islamic financial principles.
 
-- Customizable Nisab: Set your own Nisab value based on your preferred calculation method or personal financial situation.
+- Customizable "Nisab": Set your own "Nisab" value based on your preferred calculation method or personal financial situation.
 
-- Customizable Haul: Set your own Haul cycle based on your preferred calender method or personal financial situation.
+- Customizable "Haul": Set your own "Haul" cycle based on your preferred calender method or personal financial situation.
 
 - Multiple Accounts: Manage Zakat for different assets or accounts separately for greater financial clarity.
 
@@ -59,6 +59,8 @@ Zakat is a user-friendly Python library designed to simplify the tracking and ca
 
 - [Mechanism of Zakat: The Rooms and Boxes Algorithm](./docs/algorithm.md)
 
+- [The Zakat Formula: A Mathematical Representation of Islamic Charity](./docs/mathematics.md)
+
 ### Get Started:
 
 Install the Zakat library using pip:

docs/mathematics.ar.md

@@ -0,0 +1,144 @@
+<div dir="rtl">
+
+# صيغة الزكاة: تمثيل رياضي للصدقة الإسلامية
+
+الزكاة هي أحد أركان الإسلام الخمسة، وهي شكل إلزامي من الصدقة للمسلمين الذين يستوفون معايير ثروة محددة. تعمل الزكاة كوسيلة لتطهير ثروة الفرد وإعادة توزيعها على المحتاجين. في حين أن مبادئ الزكاة راسخة، فإن حساب المبلغ المستحق يمكن أن يختلف تبعًا لنوع الأصول وقيمتها وفقًا لأسعار الصرف في وقت الزكاة.
+
+تركز هذه الورقة على تمثيل رياضي محدد لصيغة الزكاة باستخدام LaTeX، وهو نظام التنضيد المستخدم على نطاق واسع للمستندات العلمية والرياضية.
+
+### صيغة الزكاة
+
+يمكن التعبير عن صيغة الزكاة باستخدام المعادلة الرياضية التالية:
+</div>
+
+```math
+Z_(السنة n) = [ P - \sum_(i=1)^(n-1) Z_(السنة i) ] × Z
+```
+<div dir="rtl">
+حيث:
+
+
+*   ($Z_(السنة n)$): الزكاة للسنة n (المبلغ المستحق في سنة محددة)
+*   (P): رأس المال الأولي (المبلغ الأصلي للثروة الخاضعة للزكاة)
+*   ($\sum_(i=1)^(n-1) Z_(السنة i)$): مجموع الزكاة المدفوعة في السنوات السابقة (من السنة الأولى إلى السنة التي تسبق السنة الحالية، أي n - 1)
+*   (Z): معدل الزكاة (عادة 2.5٪ من الثروة التي تتجاوز حدًا معينًا)
+
+**فهم الصيغة**
+
+الفكرة الأساسية للصيغة هي حساب الزكاة لسنة معينة بناءً على الثروة المتبقية بعد خصم الزكاة المدفوعة في السنوات السابقة. يأخذ هذا النهج في الاعتبار أن الزكاة تطهر الثروة بمرور الوقت، وقد ينخفض المبلغ المستحق سنويًا إذا ظلت الثروة مستقرة نسبيًا.
+
+يرمز رمز الجمع (\(\sum_(i=1)^(n-1)\)) إلى الزكاة التراكمية المدفوعة من السنة الأولى (i = 1) إلى السنة التي تسبق السنة الحالية (n - 1). بطرح هذه الزكاة التراكمية من رأس المال الأولي (P)، نحصل على الثروة المتبقية الخاضعة للزكاة في السنة الحالية (n).
+
+بضرب هذه الثروة المتبقية في معدل الزكاة (Z)، نحصل على مبلغ الزكاة المستحق للسنة.
+
+**مثال**
+
+لنفترض أن شخصًا ما لديه ثروة أولية قدرها 100,000 دولار، ومعدل الزكاة 2.5٪. في السنة الأولى، تكون الزكاة المستحقة:
+
+```math
+Z_(السنة 1) = (100000 - 0) × 0.025 = 2500
+```
+في السنة الثانية، تكون الزكاة المستحقة:
+
+```math
+Z_(السنة 2) = (100000 - 2500) × 0.025 = 2437.50
+```
+تستمر هذه العملية لكل سنة لاحقة، مع انخفاض مبلغ الزكاة تدريجيًا مع انكماش الثروة المتبقية.
+
+### منهجية الغرف والصناديق
+
+لتكييف صيغة الزكاة لسيناريو يتم فيه تخزين المعاملات في صناديق داخل الغرف (على غرار الحسابات)، نحتاج إلى مراعاة التعديل التالي.
+
+صيغة الزكاة المعدلة:
+
+
+```math
+Z_(الغرفة r, السنة n) = [ \sum_(j=1)^m (P_(r,j) -  \sum_(i=1)^(n-1) Z_(r,j,i)) ] × Z
+```
+حيث:
+
+*   ($Z_(الغرفة r, السنة n)$): الزكاة للغرفة r في السنة n
+*   ($P_(r,j)$): رأس المال الأولي في الصندوق j من الغرفة r
+*   ($\sum_(j=1)^m$): الجمع على جميع الصناديق (j = 1 إلى m) في الغرفة r
+*   ($\sum_(i=1)^(n-1) Z_(r,j,i)$): مجموع الزكاة المدفوعة في السنوات السابقة للصندوق j في الغرفة r (من السنة 1 إلى السنة n-1)
+*   (Z): معدل الزكاة (عادة 2.5%)
+
+**شرح التعديلات:**
+
+*   **مؤشر الغرفة (r):** تتضمن الصيغة الآن مؤشرًا 'r' لتمثيل الغرف المختلفة (الحسابات). هذا يسمح بحساب الزكاة لكل غرفة على حدة.
+*   **مؤشر الصندوق (j):** يتم إدخال مؤشر 'j' لتمثيل الصناديق المختلفة (المعاملات) داخل كل غرفة. نقوم بالتكرار على جميع الصناديق في الغرفة لحساب إجمالي الزكاة المستحقة لتلك الغرفة.
+*   **الجمع على الصناديق:** نستخدم رمز الجمع (\(\sum_(j=1)^m\)) لإضافة مبالغ الزكاة المحسوبة لكل صندوق داخل الغرفة. هذا يعطينا إجمالي الزكاة المستحقة للغرفة بأكملها.
+*   **تاريخ الزكاة لكل صندوق:** يأخذ المصطلح (\(\sum_(i=1)^(n-1) Z_(r,j,i)\)) في الاعتبار تاريخ الزكاة لكل صندوق على حدة. هذا يضمن أننا نحسب الزكاة فقط على الرصيد المتبقي في كل صندوق بعد خصم مدفوعات الزكاة السابقة.
+
+**التنفيذ العملي:**
+
+لتنفيذ هذه الصيغة المعدلة، عادة ما تتبع هذه الخطوات:
+
+1.  **تحديد الغرف/الحسابات المؤهلة:** تحديد الغرف/الحسابات التي تستوفي معايير الزكاة (مثل الحد الأدنى للثروة).
+2.  **حساب الزكاة لكل صندوق:** لكل صندوق في غرفة مؤهلة، احسب الزكاة المستحقة بناءً على رأس المال الأولي ومدفوعات الزكاة السابقة.
+3.  **تجميع الزكاة لكل غرفة:** اجمع مبالغ الزكاة لجميع الصناديق داخل الغرفة للحصول على إجمالي الزكاة المستحقة لتلك الغرفة.
+4.  **كرر لجميع الغرف:** كرر الخطوات 2 و 3 لجميع الغرف المؤهلة لتحديد إجمالي التزام الزكاة.
+
+**اعتبارات إضافية:**
+
+*   **توقيت المعاملات:** تفترض الصيغة أن جميع المعاملات تتم في بداية السنة. إذا حدثت معاملات على مدار السنة، فقد تحتاج إلى تعديل الصيغة لمراعاة التوقيت.
+*   **أنواع الأصول:** تفترض الصيغة أن جميع الأصول تخضع لنفس معدل الزكاة. إذا كان لديك أنواع مختلفة من الأصول بمعدلات زكاة متفاوتة، فستحتاج إلى حساب الزكاة بشكل منفصل لكل نوع من الأصول.
+
+من خلال دمج هذه التعديلات والاعتبارات، يمكنك إنشاء نظام حساب زكاة أكثر شمولاً يعكس بدقة هيكل حساباتك ومعاملاتك.
+
+**أسعار صرف الغرف**
+
+بالتأكيد! لدمج أسعار الصرف في صيغة الزكاة لعملات مختلفة داخل كل غرفة (حساب)، يمكننا إدخال معلمة إضافية لمراعاة تحويل العملة.
+
+### صيغة الزكاة المحسنة بأسعار الصرف:
+
+```math
+Z_(الغرفة r, السنة n) = [ \sum_(j=1)^m (P_(r,j) × ER_(r,j) -  \sum_(i=1)^(n-1) Z_(r,j,i)) ] × Z
+```
+
+حيث:
+
+*   \( Z_(الغرفة r, السنة n) \): الزكاة للغرفة _r_ في السنة _n_
+*   \( P_(r,j) \): رأس المال الأولي في الصندوق _j_ من الغرفة _r_
+*   \( ER_(r,j) \): سعر الصرف للعملة في الصندوق _j_ من الغرفة _r_ (بالنسبة إلى العملة الأساسية المستخدمة لحساب الزكاة)
+*   \( \sum_(j=1)^m \): الجمع على جميع الصناديق (j = 1 إلى m) في الغرفة _r_
+*   \( \sum_{i=1}^{n-1} Z_{r,j,i} \): مجموع الزكاة المدفوعة في السنوات السابقة للصندوق _j_ في الغرفة _r_ (من السنة 1 إلى السنة n-1)
+*   \( Z \): معدل الزكاة (عادة 2.5%)
+
+### شرح تعديل سعر الصرف:
+
+تتيح لنا إضافة (ER_(r,j)) تحويل رأس المال الأولي في كل صندوق إلى عملة أساسية مشتركة. يعد هذا ضروريًا عند التعامل مع عملات متعددة داخل حسابات مختلفة. بضرب رأس المال الأولي (P_(r,j)) في سعر الصرف المقابل (ER_(r,j))، نضمن أن جميع المبالغ معبر عنها بنفس العملة لحساب الزكاة بشكل متسق.
+
+### التنفيذ العملي:
+
+1.  **تحديد العملة الأساسية:** اختيار عملة أساسية لحساب الزكاة (مثل العملة المحلية أو عملة دولية مستقرة).
+2.  **الحصول على أسعار الصرف:** جمع أسعار الصرف لجميع العملات الموجودة في الصناديق / المعاملات المختلفة داخل كل غرفة / حساب.
+3.  **تحويل رأس المال إلى العملة الأساسية:** ضرب رأس المال الأولي في كل صندوق بسعر الصرف المقابل لتحويله إلى العملة الأساسية.
+4.  **تطبيق الصيغة المعدلة:** استخدام صيغة الزكاة المحسنة لحساب الزكاة المستحقة لكل صندوق، ثم تجميع المبالغ لكل غرفة، وأخيرًا لجميع الغرف المؤهلة.
+
+### مثال:
+
+لنفترض أن لديك غرفة (حساب) بصندوقين:
+
+*   **الصندوق 1:** 5000 دولار أمريكي (سعر الصرف إلى العملة الأساسية: 3.75)
+*   **الصندوق 2:** 2000 يورو (سعر الصرف إلى العملة الأساسية: 4.20)
+
+بعد التحويل إلى العملة الأساسية، يصبح رأس المال:
+
+*   **الصندوق 1:** 5000 دولار أمريكي × 3.75 = 18750 وحدة عملة أساسية
+*   **الصندوق 2:** 2000 يورو × 4.20 = 8400 وحدة عملة أساسية
+
+ثم ستطبق صيغة الزكاة المعدلة على هذه المبالغ المحولة، إلى جانب أي مدفوعات زكاة سابقة، لتحديد الزكاة المستحقة لتلك الغرفة.
+
+### اعتبارات هامة:
+
+*   **تقلبات أسعار الصرف:** يمكن أن تتغير أسعار الصرف بمرور الوقت. اختر إطارًا زمنيًا مناسبًا للحصول على أسعار الصرف (مثل سعر الصرف في بداية سنة الزكاة).
+*   **الزكاة على مكاسب صرف العملات:** إذا كان لديك مكاسب كبيرة من صرف العملات، فقد تحتاج إلى استشارة عالم لديه معرفة لتحديد ما إذا كانت الزكاة مستحقة على تلك المكاسب.
+
+من خلال دمج أسعار الصرف في صيغة الزكاة، يمكنك ضمان حساب دقيق وعادل لالتزامات الزكاة للأفراد والمؤسسات التي تحتفظ بأصول بعملات متعددة.
+
+
+**استنتاج**
+
+توفر صيغة الزكاة، كما هو موضح في LaTeX، طريقة موجزة وصارمة رياضيًا لحساب التزامات الزكاة. تتماشى هذه الصيغة مع مبدأ أن الزكاة هي عملية مستمرة لتنقية وإعادة توزيع الثروة، بهدف تقليل التفاوت في الثروة وتخفيف حدة الفقر داخل المجتمع المسلم. من خلال فهم وتطبيق هذه الصيغة، يمكن للأفراد والمؤسسات ضمان الوفاء بالتزامات الزكاة الخاصة بهم بدقة والمساهمة في الصالح العام للمجتمع.
+</div>