zwitschi
39c45e720c
- Create .env.example for environment variables - Update README with project structure and development setup instructions - Implement FastAPI application with API routes for scenarios and parameters - Add database models for scenarios, parameters, and simulation results - Introduce validation middleware for JSON requests - Create services for running simulations and generating reports - Add testing strategy and directory structure in documentation
121 lines
5.4 KiB
Markdown
121 lines
5.4 KiB
Markdown
# CalMiner
|
|
|
|
A web application to plan mining projects and estimate costs, returns and profitability.
|
|
|
|
Focuses on ore mining operations and covering parameters such as capital and operational expenditures, resource consumption, production output, and Monte Carlo simulations for risk analysis.
|
|
|
|
The system is designed to help mining companies make informed decisions by simulating various scenarios and analyzing potential outcomes based on stochastic variables.
|
|
|
|
A range of features are implemented to support these functionalities.
|
|
|
|
## Features
|
|
|
|
- **Scenario Management**: The database supports different scenarios for what-if analysis, with parent-child relationships between scenarios.
|
|
- **Monte Carlo Simulation**: The system can perform Monte Carlo simulations for risk analysis and probabilistic forecasting.
|
|
- **Stochastic Variables**: The model handles uncertainty by defining variables with probability distributions.
|
|
- **Cost Tracking**: It tracks capital (`capex`) and operational (`opex`) expenditures.
|
|
- **Consumption Tracking**: It monitors the consumption of resources like chemicals, fuel, water, and scrap materials.
|
|
- **Production Output**: The database stores production results, including tons produced, recovery rates, and revenue.
|
|
- **Process Parameters**: It allows for defining and storing various parameters for different processes and scenarios.
|
|
- **Equipment Management**: The system manages equipment and their operational data.
|
|
- **Maintenance Logging**: It includes a log for equipment maintenance events.
|
|
|
|
## Architecture
|
|
|
|
The architecture is documented in [docs/architecture.md](docs/architecture.md).
|
|
|
|
## Project Structure
|
|
|
|
The project is organized into several key directories:
|
|
|
|
- `models/`: Contains SQLAlchemy models representing database tables.
|
|
- `routes/`: Defines FastAPI routes for API endpoints.
|
|
- `services/`: Business logic and service layer.
|
|
- `components/`: Frontend components (to be defined).
|
|
- `config/`: Configuration files and settings.
|
|
- `middleware/`: Custom middleware for request/response processing.
|
|
- `tests/`: Unit and integration tests.
|
|
- `templates/`: HTML templates (if applicable).
|
|
- `docs/`: Documentation files.
|
|
|
|
Key files include:
|
|
|
|
- `main.py`: FastAPI application entry point.
|
|
- `.env`: Environment variables for configuration.
|
|
- `requirements.txt`: Python dependencies.
|
|
|
|
## Development
|
|
|
|
The development setup instructions are provided in [docs/development_setup.md](docs/development_setup.md).
|
|
|
|
To get started locally:
|
|
|
|
```powershell
|
|
# Clone the repository
|
|
git clone https://git.allucanget.biz/allucanget/calminer.git
|
|
cd calminer
|
|
|
|
# Create and activate a virtual environment
|
|
python -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Start the development server
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
## Testing
|
|
|
|
Testing guidelines and best practices are outlined in [docs/testing.md](docs/testing.md).
|
|
|
|
## Database Objects
|
|
|
|
The database is composed of several tables that store different types of information.
|
|
|
|
- **CAPEX** — `capex`: Stores data on capital expenditures.
|
|
- **OPEX** — `opex`: Contains information on operational expenditures.
|
|
- **Chemical consumption** — `chemical_consumption`: Tracks the consumption of chemical reagents.
|
|
- **Fuel consumption** — `fuel_consumption`: Records the amount of fuel consumed.
|
|
- **Water consumption** — `water_consumption`: Monitors the use of water.
|
|
- **Scrap consumption** — `scrap_consumption`: Tracks the consumption of scrap materials.
|
|
- **Production output** — `production_output`: Stores data on production output, such as tons produced and recovery rates.
|
|
- **Equipment operation** — `equipment_operation`: Contains operational data for each piece of equipment.
|
|
- **Ore batch** — `ore_batch`: Stores information on ore batches, including their grade and other characteristics.
|
|
- **Exchange rate** — `exchange_rate`: Contains currency exchange rates.
|
|
- **Simulation result** — `simulation_result`: Stores the results of the Monte Carlo simulations.
|
|
|
|
## Static Parameters
|
|
|
|
These are values that are not expected to change frequently and are used for configuration purposes. Some examples include:
|
|
|
|
- **Currencies**: `currency_code`, `currency_name`.
|
|
- **Distribution types**: `distribution_name`.
|
|
- **Units**: `unit_name`, `unit_symbol`, `unit_system`, `conversion_to_base`.
|
|
- **Parameter categories**: `category_name`.
|
|
- **Material types**: `type_name`, `category`.
|
|
- **Chemical reagents**: `reagent_name`, `chemical_formula`.
|
|
- **Fuel**: `fuel_name`.
|
|
- **Water**: `water_type`.
|
|
- **Scrap material**: `scrap_name`.
|
|
|
|
## Variables
|
|
|
|
These are dynamic data points that are recorded over time and used in calculations and simulations. Some examples include:
|
|
|
|
- **CAPEX**: `amount`.
|
|
- **OPEX**: `amount`.
|
|
- **Chemical consumption**: `quantity`, `efficiency`, `waste_factor`.
|
|
- **Fuel consumption**: `quantity`.
|
|
- **Water consumption**: `quantity`.
|
|
- **Scrap consumption**: `quantity`.
|
|
- **Production output**: `tons_produced`, `recovery_rate`, `metal_content`, `metallurgical_loss`, `net_revenue`.
|
|
- **Equipment operation**: `hours_operated`, `downtime_hours`.
|
|
- **Ore batch**: `ore_grade`, `moisture`, `sulfur`, `chlorine`.
|
|
- **Exchange rate**: `rate`.
|
|
- **Parameter values**: `value`.
|
|
- **Simulation result**: NPV (`npv`), IRR (`irr`), EBITDA (`ebitda`), `net_revenue`.
|
|
- **Cementation parameters**: `temperature`, pH (`ph`), `reaction_time`, `copper_concentration`, `iron_surface_area`.
|
|
- **Precipitate product**: `density`, `melting_point`, `boiling_point`.
|