Installation & Setup Guide

Before setting up iTensor, make sure you have the following prerequisites installed on your system:

• Python 3.9+ – required for running the Django backend (and libraries like NumPy/SymPy)
• Node.js 14+ (and npm or yarn) – required for running the Next.js frontend
• Git – if you are fetching the project from a Git repository
• (Optional) Virtual Environment Tool – such as venv or conda for Python, to isolate project dependencies

1. Clone the Repository

   First, obtain the iTensor code. For example, if hosted on GitHub, use:

   git clone https://github.com/YourOrg/itensor.git
   cd itensor

   This repository likely contains both frontend and backend subdirectories (e.g., frontend/ and backend/), or the Django project might live in a subfolder.

2. Create a Virtual Environment

   It's recommended to use a Python virtual environment to manage dependencies. For example:

   python3 -m venv venv
   source venv/bin/activate # (On Windows, use: venv\Scripts\activate)

3. Install Python Dependencies

   Navigate to the backend's directory (e.g., cd backend/ if applicable, or the project root if requirements are in root) and install required packages:

   pip install -r requirements.txt

   This will install Django, NumPy, SymPy, and any other libraries the backend depends on (e.g., django-rest-framework if used for the API).

4. Django Project Setup

   Apply any initial migrations and create a superuser (if the project uses Django's auth and database):

   python manage.py migrate
   python manage.py createsuperuser # optional, if you plan to use Django admin

   Ensure that the database (default SQLite or configured DB) is set up correctly. By default, iTensor may use SQLite for simplicity.

5. Configure Environment (Backend)

   iTensor's Django settings might require certain environment variables. For example:

   • DJANGO_SECRET_KEY – the secret key for the Django app
   • DEBUG – set to True for development (and False in production)
   • ALLOWED_HOSTS – for local dev, you can set ALLOWED_HOSTS = ["*"] or localhost

   CORS settings: If the frontend is served on a different host/port (e.g., Next.js dev server), ensure Django allows cross-origin requests. You may need to install and configure django-cors-headers to allow the frontend origin (e.g., http://localhost:3000). In settings.py, add the frontend URL to CORS_ALLOWED_ORIGINS or enable CORS_ALLOW_ALL_ORIGINS in development.

   These configurations can be done in a .env file or directly in the settings module. Follow any instructions in the repository's README regarding environment variables.

6. Run the Django Development Server

   Start the backend server by running:

   python manage.py runserver

   By default, this will start Django on http://127.0.0.1:8000/. You should see console output indicating that Django is running. Keep this process running as you work.

1. Install Node Dependencies

   In a new terminal (and keeping the backend running in the other), navigate to the frontend directory (e.g., cd frontend/). Run the package manager to install dependencies:

   npm install

   This will download all required Node modules as specified in package.json (such as React, Next.js, etc.).

2. Configure Environment (Frontend)

   The Next.js app might need to know the URL of the backend API. In development, this could be an environment variable like NEXT_PUBLIC_API_URL=http://localhost:8000. Check if there's an .env.local example or a configuration file.

   Set the API base URL so that the frontend knows where to send requests (for example, the frontend might call fetch('/api/tensors/…') which needs to be proxied to the Django server).

   If the Next.js app is configured to proxy API requests to the Django server (via Next.js rewrites or a proxy middleware), ensure that is set up. Otherwise, you'll configure the full URL in the code or env variable.

3. Run the Next.js Development Server

   Start the frontend dev server by running:

   npm run dev

   This will launch the Next.js application, usually at http://localhost:3000 by default. You should see output in the terminal indicating the server is ready and listening. Open a web browser to the localhost URL to verify the frontend loads. If it needs the backend to be accessible, ensure you have the Django server running as well.

4. Verify Frontend-Backend Connection

   Using the UI, try a simple operation (if the UI allows) or open the browser's developer console to check network requests. When the frontend makes a request to the iTensor API (e.g., submitting a tensor operation), you should see network calls to http://localhost:8000/api/tensors/... and responses coming back.

   If you encounter CORS errors or 404s, double-check the configuration:

   • CORS: Make sure the Django backend allowed the origin
   • URL paths: Ensure the frontend is calling the correct path (maybe adjust NEXT_PUBLIC_API_URL)

   If needed, adjust Next.js config (for example, in next.config.js you can set up a rewrite: { source: '/api/:path*', destination: 'http://127.0.0.1:8000/api/:path*' } to forward API calls during development).

With both servers running, you have a fully functional development setup. Some additional tips for local development:

• Hot Reloading

  Both Django and Next.js support hot reloading. Django will reload if you edit Python files (with DEBUG=True), and Next.js will live-reload the page as you edit React/TypeScript files. This helps in quickly iterating on features.

• Running Tests

  If the project includes tests, you can run Python tests (e.g., python manage.py test) for backend logic and npm test or npm run test for frontend tests. Ensure that all tests pass after setup.

• Linting and Formatting

  The project may include configurations for code style (for instance, flake8 or black for Python, ESLint/Prettier for JS). Running these linters can help maintain code quality. For example, use flake8 or black . in the backend directory, and npm run lint in the frontend.

• Troubleshooting

  If you run into issues:

  • Backend not responding: Check the Django server console for errors (e.g. import errors, missing migrations)
  • Frontend build errors: Check the terminal output where npm run dev was executed; fix any syntax or module errors indicated
  • Module not found: Ensure all dependencies are installed (both pip and npm). If a package is missing, install it (pip install <name> or npm install <name>) and add to the respective requirements/package.json if needed