simnexus 0.1.1__tar.gz

simnexus-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Michael Borck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simnexus-0.1.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.1
+Name: simnexus
+Version: 0.1.1
+Summary: This Python package provides a set of classes for simulating various business-related scenarios. It is designed for educational use, allowing students to experiment with modeling, analysis, and decision-making in different contexts.
+Author: Michael Borck
+Author-email: michael@borck.me
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Requires-Dist: poetry-plugin-export (>=1.7.1,<2.0.0)
+Requires-Dist: pycparser (>=2.22,<3.0)
+Requires-Dist: pymdown-extensions (>=10.8.1,<11.0.0)
+Project-URL: Documentation, https://simnexus.readthedocs.io/en/latest/
+Project-URL: Homepage, http://yourhomepage.com
+Project-URL: Repository, https://github.com/teaching-repositories/simnexus
+Description-Content-Type: text/markdown
+
+# SimNexus: Business Simulation Toolkit
+
+This Python package provides a set of classes for simulating various
+business-related scenarios. It is designed for educational use, allowing
+students to experiment with modeling, analysis, and decision-making in different
+contexts.
+
+## Installation
+
+To install SimNexus
+
+```bash
+pip install simnexus
+```
+
+## Available Simulations
+
+- **Stock Market Simulation:** Simulate stock price fluctuations, incorporate
+  technical indicators, and develop simple trading strategies.
+- **Resource Fluctuations Simulation:** Model changes in the price of a
+  resource, analyze supply/demand dynamics, and implement hedging strategies.
+- **Product Popularity Simulation:** Simulate the rise and fall of product
+  demand, investigate virality factors, and examine different marketing
+  strategies.
+
+## Documentation
+
+For more detailed information about using SimNexus, see the [documentation](https://yourproject.readthedocs.io/).
+
+
+## Basic Usage Example
+
+Here is an example of how to use the Resource Fluctuations Simulation:
+
+```python
+from simnexus import ResourceFluctuationsSimulation
+
+# Create a resource simulation
+sim = ResourceFluctuationsSimulation(start_price=100, days=365, volatility=0.05, drift=0.01,
+                         supply_disruption_day=180, disruption_severity=0.2)
+
+# Run the simulation and get results
+prices = sim.run_simulation()
+
+# Visualize or analyze the results here
+```
+
+## Project Goals (For Students)
+
+- Gain familiarity with using simulations to model dynamic systems.
+- Understand the impact of different parameters on simulation outcomes.
+- Develop data analysis and visualization skills in the context of business problems.
+- Practice translating business concepts into simulation parameters.
+
+## Contributing
+
+We welcome contributions to the SimNexus project! If you have suggestions or improvements, feel free to fork the repository and submit a pull request. Please ensure your code adheres to the existing style, and include tests for new features or bug fixes.
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for more details.
+

simnexus-0.1.1/README.md

@@ -0,0 +1,61 @@
+# SimNexus: Business Simulation Toolkit
+
+This Python package provides a set of classes for simulating various
+business-related scenarios. It is designed for educational use, allowing
+students to experiment with modeling, analysis, and decision-making in different
+contexts.
+
+## Installation
+
+To install SimNexus
+
+```bash
+pip install simnexus
+```
+
+## Available Simulations
+
+- **Stock Market Simulation:** Simulate stock price fluctuations, incorporate
+  technical indicators, and develop simple trading strategies.
+- **Resource Fluctuations Simulation:** Model changes in the price of a
+  resource, analyze supply/demand dynamics, and implement hedging strategies.
+- **Product Popularity Simulation:** Simulate the rise and fall of product
+  demand, investigate virality factors, and examine different marketing
+  strategies.
+
+## Documentation
+
+For more detailed information about using SimNexus, see the [documentation](https://yourproject.readthedocs.io/).
+
+
+## Basic Usage Example
+
+Here is an example of how to use the Resource Fluctuations Simulation:
+
+```python
+from simnexus import ResourceFluctuationsSimulation
+
+# Create a resource simulation
+sim = ResourceFluctuationsSimulation(start_price=100, days=365, volatility=0.05, drift=0.01,
+                         supply_disruption_day=180, disruption_severity=0.2)
+
+# Run the simulation and get results
+prices = sim.run_simulation()
+
+# Visualize or analyze the results here
+```
+
+## Project Goals (For Students)
+
+- Gain familiarity with using simulations to model dynamic systems.
+- Understand the impact of different parameters on simulation outcomes.
+- Develop data analysis and visualization skills in the context of business problems.
+- Practice translating business concepts into simulation parameters.
+
+## Contributing
+
+We welcome contributions to the SimNexus project! If you have suggestions or improvements, feel free to fork the repository and submit a pull request. Please ensure your code adheres to the existing style, and include tests for new features or bug fixes.
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for more details.

simnexus-0.1.1/pyproject.toml

@@ -0,0 +1,31 @@
+[tool.poetry]
+name = "simnexus"
+version = "0.1.1"
+description = "This Python package provides a set of classes for simulating various business-related scenarios. It is designed for educational use, allowing students to experiment with modeling, analysis, and decision-making in different contexts."
+authors = ["Michael Borck <michael@borck.me>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+numpy = "^1.26.4"
+pymdown-extensions = "^10.8.1"
+pycparser = "^2.22"
+poetry-plugin-export = "^1.7.1"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.2.0"
+mkdocs = "^1.6.0"
+mkdocstrings = "^0.25.0"
+mypy = "^1.10.0"
+flake8 = "^7.0.0"
+mkdocs-material = "^9.5.20"
+mkdocstrings-python = "^1.10.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.urls]
+"Homepage" = "http://yourhomepage.com"
+"Documentation" = "https://simnexus.readthedocs.io/en/latest/"
+"Repository" = "https://github.com/teaching-repositories/simnexus"

simnexus-0.1.1/simnexus/__init__.py

@@ -0,0 +1,9 @@
+from .product_popularity_simulation import ProductPopularitySimulation
+from .resource_fluctuations_simulation import ResourceFluctuationsSimulation
+from .stock_market_simulation import StockMarketSimulation
+
+__all__ = [
+    "ProductPopularitySimulation",
+    "ResourceFluctuationsSimulation",
+    "StockMarketSimulation"
+]

simnexus-0.1.1/simnexus/product_popularity_simulation.py

@@ -0,0 +1,71 @@
+import numpy as np
+from typing import List, Optional
+
+
+class ProductPopularitySimulation:
+    """
+    A simulation class to model the dynamics of product popularity over time,
+    incorporating factors like natural growth, marketing impact, and promotional campaigns.
+
+    Attributes:
+        start_demand (int): Initial demand for the product.
+        days (int): Duration of the simulation in days.
+        growth_rate (float): Natural growth rate of product demand.
+        marketing_impact (float): Impact of ongoing marketing efforts on demand.
+        promotion_day (Optional[int]): Day on which a major marketing campaign starts (default is None).
+        promotion_effectiveness (float): Effectiveness of the marketing campaign.
+        random_seed (Optional[int]): The seed for the random number generator to ensure reproducibility (default is None).
+
+    Methods:
+        run_simulation(): Runs the simulation and returns a list of demand values over time.
+    """
+
+    def __init__(
+        self, start_demand: float, days: int, growth_rate: float, marketing_impact: float,
+        promotion_day: Optional[int] = None, promotion_effectiveness: float = 0,
+        random_seed: Optional[int] = None
+    ) -> None:
+        """
+        Initializes the ProductPopularitySimulation with all necessary parameters.
+
+        Parameters:
+            start_demand (int): The initial level of demand for the product.
+            days (int): The total number of days to simulate.
+            growth_rate (float): The natural daily growth rate of demand, as a decimal.
+            marketing_impact (float): Daily impact of marketing on demand, as a decimal.
+            promotion_day (Optional[int]): The specific day on which a promotional event occurs (defaults to None).
+            promotion_effectiveness (float): Multiplicative impact of the promotion on demand.
+            random_seed (Optional[int]): Seed for the random number generator to ensure reproducible results (defaults to None).
+        """
+        self.start_demand = start_demand
+        self.days = days
+        self.growth_rate = growth_rate
+        self.marketing_impact = marketing_impact
+        self.promotion_day = promotion_day
+        self.promotion_effectiveness = promotion_effectiveness
+        self.random_seed = random_seed
+
+    def run_simulation(self) -> List[float]:
+        """
+        Simulates the demand for a product over a specified number of days based on the initial settings.
+
+        Returns:
+            List[int]: A list containing the demand for the product for each day of the simulation.
+        """
+        if self.random_seed is not None:
+            np.random.seed(self.random_seed)
+
+        demand = [self.start_demand]
+        for day in range(1, self.days):
+            previous_demand = demand[-1]
+            natural_growth = previous_demand * (1 + self.growth_rate)
+            marketing_influence = previous_demand * self.marketing_impact
+
+            new_demand = natural_growth + marketing_influence
+
+            if day == self.promotion_day:
+                new_demand = (natural_growth + marketing_influence) * (1 + self.promotion_effectiveness)
+
+            demand.append(new_demand)
+
+        return demand

simnexus-0.1.1/simnexus/resource_fluctuations_simulation.py

@@ -0,0 +1,63 @@
+import numpy as np
+from typing import List, Optional
+
+
+class ResourceFluctuationsSimulation:
+    """
+    A simulation class to model the fluctuations of resource prices over time,
+    considering factors like volatility, market trends (drift), and supply disruptions.
+
+    Attributes:
+        start_price (float): The initial price of the resource.
+        days (int): The duration of the simulation in days.
+        volatility (float): The volatility of price changes, representing day-to-day variability.
+        drift (float): The average daily price change, indicating the trend over time.
+        supply_disruption_day (Optional[int]): The specific day a supply disruption occurs (default is None).
+        disruption_severity (float): The magnitude of the disruption's impact on price (default is 0).
+        random_seed (Optional[int]): The seed for the random number generator to ensure reproducibility (default is None).
+    """
+    def __init__(self, start_price: float, days: int, volatility: float, drift: float,
+                 supply_disruption_day: Optional[int] = None, disruption_severity: float = 0,
+                 random_seed: Optional[int] = None) -> None:
+        """
+        Initializes the ResourceSimulation with all necessary parameters.
+
+        Parameters:
+            start_price (float): The initial price of the resource.
+            days (int): The total number of days to simulate.
+            volatility (float): The volatility of the resource price, representing the randomness of day-to-day price changes.
+            drift (float): The expected daily percentage change in price, which can be positive or negative.
+            supply_disruption_day (Optional[int]): Day on which a supply disruption occurs (defaults to None).
+            disruption_severity (float): The severity of the supply disruption, affecting prices multiplicatively.
+            random_seed (Optional[int]): Seed for the random number generator to ensure reproducible results (defaults to None).
+        """
+        self.start_price = start_price
+        self.days = days
+        self.volatility = volatility
+        self.drift = drift
+        self.supply_disruption_day = supply_disruption_day
+        self.disruption_severity = disruption_severity
+        self.random_seed = random_seed
+
+    def run_simulation(self) -> List[float]:
+        """
+        Simulates the price of the resource over a specified number of days based on the initial settings.
+
+        Returns:
+            List[float]: A list containing the price of the resource for each day of the simulation.
+        """
+        if self.random_seed is not None:
+            np.random.seed(self.random_seed)
+
+        prices = [self.start_price]
+        for day in range(1, self.days):
+            previous_price = prices[-1]
+            random_change = np.random.normal(self.drift, self.volatility)
+            new_price = previous_price * (1 + random_change)
+
+            if day == self.supply_disruption_day:
+                new_price = previous_price * (1 + self.disruption_severity)
+
+            prices.append(new_price)
+
+        return prices

simnexus-0.1.1/simnexus/stock_market_simulation.py

@@ -0,0 +1,69 @@
+import numpy as np
+from typing import List, Optional
+
+
+class StockMarketSimulation:
+    """
+    A simulation class to model the fluctuations of stock prices over time, accounting for volatility,
+    general market trends (drift), and specific market events.
+
+    Attributes:
+        start_price (float): The initial price of the stock.
+        days (int): The duration of the simulation in days.
+        volatility (float): The volatility of stock price changes, representing day-to-day variability.
+        drift (float): The average daily price change, indicating the trend over time.
+        event_day (Optional[int]): The specific day a major market event occurs (default is None).
+        event_impact (float): The magnitude of the event's impact on stock prices (default is 0).
+        random_seed (Optional[int]): The seed for the random number generator to ensure reproducibility (default is None).
+
+    Methods:
+        run_simulation(): Runs the simulation and returns a list of stock prices over the simulation period.
+    """
+
+    def __init__(
+        self, start_price: float, days: int, volatility: float, drift: float,
+        event_day: Optional[int] = None, event_impact: float = 0,
+        random_seed: Optional[int] = None
+    ) -> None:
+        """
+        Initializes the StockMarketSimulation with all necessary parameters.
+
+        Parameters:
+            start_price (float): The initial stock price.
+            days (int): The total number of days to simulate.
+            volatility (float): The volatility of the stock price, representing the randomness of day-to-day price changes.
+            drift (float): The expected daily percentage change in price, which can be positive or negative.
+            event_day (Optional[int]): Day on which a major market event occurs (defaults to None).
+            event_impact (float): The severity of the market event, affecting prices multiplicatively.
+            random_seed (Optional[int]): Seed for the random number generator to ensure reproducible results (defaults to None).
+        """
+        self.start_price = start_price
+        self.days = days
+        self.volatility = volatility
+        self.drift = drift
+        self.event_day = event_day
+        self.event_impact = event_impact
+        self.random_seed = random_seed
+
+    def run_simulation(self) -> List[float]:
+        """
+        Simulates the stock price over a specified number of days based on the initial settings.
+
+        Returns:
+            List[float]: A list containing the stock prices for each day of the simulation.
+        """
+        if self.random_seed is not None:
+            np.random.seed(self.random_seed)
+
+        prices = [self.start_price]
+        for day in range(1, self.days):
+            previous_price = prices[-1]
+            random_change = np.random.normal(self.drift, self.volatility)
+            new_price = previous_price * (1 + random_change)
+
+            if day == self.event_day:
+                new_price = previous_price * (1 + self.event_impact)
+
+            prices.append(new_price)
+
+        return prices