Setting Up the Environment for Creating OSP Simulations

In this tutorial you will learn how to prepare your development environment for building physics simulations in Java using IntelliJ IDEA and the ACM library, before moving on to the OSP framework itself. The goal is to guide you step by step through the entire process—from installing the IDE, to creating a new project, to writing your first application that simulates a pendulum without using any OSP classes.

What You Will Learn

• Installing and Configuring IntelliJ IDEA
  Downloading the Community or Ultimate edition, setting up the JDK, and basic settings for Java projects.
• Adding the ACM Library (acm.jar)
  How to download and link acm.jar in your project to use the graphical and interactive components provided by the ACM (Stanford CS) library.
• Creating a Java Project from Scratch
  Directory structure, module and dependency setup, and your first “Hello, World!” program.
• Developing the Mathematical Pendulum Simulation
  Defining the pendulum’s differential equations, numerical integration (Euler or Runge–Kutta method), and graphically displaying the pendulum’s motion using GraphicsProgram.
• Running and Testing
  How to create a run configuration in IntelliJ, launch your application, and verify the accuracy of the simulation.

Once you have successfully mastered this introductory section, you will be ready to move on to using the Open Source Physics (OSP) libraries and creating more advanced 2D and 3D simulations.

Installing Tools for OSP (IntelliJ IDEA)

Free Editions of IntelliJ IDEA

1. Community Edition – open-source, supports Java, Kotlin, Groovy, Scala, Android development.
2. Educational Edition – based on Community, with additional learning and practice tools.

Download and Installation

1. Windows

   1. Go to https://www.jetbrains.com/idea/download or for the Educational edition: https://www.jetbrains.com/edu-products/download/#section=idea.
   2. Select the Community Edition and click Download for Windows.
   3. Run the downloaded .exe file and follow the installer steps:
      • Next → Accept → Next → Install
      • At the end, leave the “Run IntelliJ IDEA Community Edition” checkbox checked and click Finish.
   4. On first launch:
      • No license is required for Community Edition.
      • It’s recommended to choose the Dark or Light theme.
      • IntelliJ will detect installed JDKs; if you don’t have a JDK, download one (e.g. Zulu/OpenJDK) and in the IDE select Configure → Project SDK → Add SDK, then point to the JDK folder.

2. Linux

   A) Using the official .tar.gz

   1. Go to https://www.jetbrains.com/idea/download and download the “.tar.gz” for the Community Edition.
   2. In a terminal, run:

      cd ~/Downloads
      tar -xzf ideaIC-*.tar.gz
      sudo mv idea-IC-* /opt/idea-community
      

   3. Create a launcher script:

      sudo tee /usr/local/bin/idea << 'EOF'
      #!/usr/bin/env bash
      /opt/idea-community/bin/idea.sh "$@"
      EOF
      sudo chmod +x /usr/local/bin/idea
      

      You can now launch IntelliJ by typing idea in your terminal.

   B) Using Snap (Ubuntu, Mint…)

   sudo snap install intellij-idea-community --classic

Installing the Educational Edition

1. On the download page, click the Other versions tab and choose the Educational Edition.
2. To add integrated learning tools in the Community Edition, go to File → Settings → Plugins, search for “Educational” and install the JetBrains Academy or Educational plugin.
3. After restarting, you will see a Learn menu for interactive courses and exercises.

Basic Settings in IntelliJ IDEA

Before diving into developing your simulations or any other Java projects, you need to properly configure your IDE. The following steps will guide you through the essential IntelliJ IDEA settings: from integrating the JDK, to installing additional plugins, and customizing keyboard shortcuts and themes.

1. Configuring the JDK

The first and most important step is to add your locally installed Java Development Kit (JDK) to IntelliJ IDEA. This enables compilation and execution of your Java applications.

1. Open the SDK settings:
   • Windows: File → Settings → Build, Execution, Deployment → SDKs
   • Linux/macOS: IntelliJ IDEA → Preferences → Build, Execution, Deployment → SDKs
2. Click the + → Add SDK → JDK button.
3. Select the root folder of your JDK (the one containing bin, lib, etc.):
   • C:\Program Files\Java\jdk-11.0.12 (Windows)
   • /usr/lib/jvm/java-11-openjdk (Linux)
4. Give it a descriptive name, for example “Java 11”, and click OK.
5. Finally, go to Project Structure → Project and in the Project SDK field select the JDK you just added.

2. Installing Plugins

To work with other languages and tools inside IntelliJ IDEA, install the appropriate plugins.

1. Open File → Settings → Plugins (or IntelliJ IDEA → Preferences → Plugins).
2. In the search box, type the name of the language or tool you need (e.g. “Scala”, “Python”, “Docker”).
3. Click Install, then Restart IDE when installation completes.

3. Customizing Keymaps and Theme

IntelliJ IDEA lets you choose among predefined keymaps and UI themes to make your workspace more comfortable.

1. Keymap: Settings → Keymap – select “Default”, “Eclipse”, “Visual Studio”, or another layout.
2. Theme: Settings → Appearance & Behavior → Theme – choose “Darcula” (dark) or “IntelliJ Light.”

4. Creating a Desktop Entry (Linux)

If you installed IntelliJ IDEA via the .tar.gz archive, on its first launch the IDE will offer to create a desktop entry for quick access from your application menu.

If that prompt does not appear automatically:

1. Open a terminal and create the launcher script:

   sudo tee /usr/local/bin/idea << 'EOF'
   #!/usr/bin/env bash
   /opt/idea-community/bin/idea.sh "$@"
   EOF
   sudo chmod +x /usr/local/bin/idea
   

2. You can now start IntelliJ by running idea or find it in your desktop environment’s applications menu.

Procedure for Configuring the JDK in IntelliJ IDEA

To ensure your Java project in IntelliJ IDEA runs without errors, you need to correctly add and configure the Java Development Kit (JDK). Below is a detailed step-by-step guide walking you through the entire process, from opening the settings to selecting the new Project SDK.

1. Open Settings:
   • Windows: select File → Settings
   • Linux/macOS: select IntelliJ IDEA → Preferences
2. Open Project Structure:
   Within the settings, find and select Project Structure (or press Ctrl+Alt+Shift+S).
3. Add a New SDK:
   Click the + icon next to the SDK list and choose JDK.
4. Locate the JDK Installation:
   Navigate to the root directory of your JDK installation—the one containing the bin and lib subfolders. For example:
   • C:\Program Files\Java\jdk-11.0.12 (Windows)
   • /usr/lib/jvm/java-11-openjdk (Linux)

   Important: Make sure to select the JDK’s root folder, not a subdirectory.

5. Define the SDK Name:
   Enter a descriptive name, such as Java 11, and click OK.
6. Set the Project SDK:
   Open Project Structure → Project again and in the Project SDK dropdown select the JDK you just added (e.g., Java 11).

After these steps, IntelliJ will use the selected JDK to compile and run your Java applications. You are now ready to continue working on your simulations or other Java projects.

Creating a Java Project Without the OSP Library

In the following section, we will guide you through setting up a brand-new Java project in IntelliJ IDEA without relying on the OSP libraries. Instead, we’ll use acm.jar from the Stanford Java Task Force, which is ideal for simple graphical and educational applications.

1. Creating a New Java Project

First, we’ll set up the basic project structure inside IntelliJ IDEA.

1. On the Welcome screen, click New Project.
2. In the New Project dialog choose:
   • Language: Java
   • Build System: IntelliJ (Maven/Gradle not required)
   • Project SDK: select the JDK 11 you configured earlier
   Then click Next and Finish.
3. IntelliJ will open an empty project with a default src directory.

2. Adding the acm.jar Library

The ACM library makes it easy to draw and use interactive GUI components for educational purposes. Follow these steps to download and include it:

1. Download acm.jar from the Stanford site:
   • Visit the Stanford Java Task Force
   • Under Java Libraries, click the acm.jar link directly: acm.jar
2. In IntelliJ IDEA:
   • Right-click your project module → Open Module Settings.
   • Under Dependencies, click + → JARs or directories….
   • Select the downloaded acm.jar and confirm with Compile scope.

3. Brief Introduction to acm.jar

acm.jar is a library developed by the Stanford team as part of the book The Art and Science of Java (Eric Roberts). It’s designed for students to build simple graphical applications.

• GraphicsProgram: base class for drawing on a canvas.
• ConsoleProgram: interactive text input/output.
• DialogProgram: basic dialog window.

Main advantages:

• Simplified GUI components (window, canvas, buttons).
• Easy drawing of lines, circles, and text.
• Rapid development of educational simulations.

4. Example Java Application Using acm.jar

The following code shows a simple GraphicsProgram that draws a circle on the screen:

import acm.program.*;
import acm.graphics.*;

public class PendulumWithoutOSP extends GraphicsProgram {
    public void run() {
        GOval circle = new GOval(100, 100, 50, 50);
        add(circle);
    }
    public static void main(String[] args) {
        new PendulumWithoutOSP().start(args);
    }
}
  

After running successfully, a window with a circle will appear. From there, you can implement the pendulum animation using numerical integration and periodic screen updates.

Explanation of the Mathematical Pendulum Simulation Code

Below is an overview of the main parts of the code and an explanation of what happens when you extend the ACM class GraphicsProgram, as well as how the animation of the pendulum is set up and executed in the run() method.

Main Method and Extending GraphicsProgram

In the public static void main(String[] args) method, we create an object of the MatematickoKlatno class and call start(args). This triggers the ACM application lifecycle:

• init() – initialization before run() is executed.
• run() – the main animation logic.
• start() and stop() – called when the program starts and stops.

Static Variables and Class Members

At the beginning of the class, we define constants to control the pendulum's behavior:

• PENDULUM_LENGTH – length of the pendulum in pixels.
• PERIOD – oscillation period in milliseconds.
• AMPLITUDE – maximum angle or displacement in pixels.

Next, we declare graphical objects: GLine string for the pendulum string and GOval ball for the pendulum bob.

The run() Method – Setup and Main Loop

1. Window setup: setSize(600, 600) defines the dimensions of the main window.
2. Object initialization: We create a GOval and GLine, set their properties and add them to the canvas using add(...).
3. Start the animation: a while(true) loop continuously calculates positions and updates the display.

Details of the while(true) Loop

1. Read current time:
   long time = System.currentTimeMillis() % (long)PERIOD;
   Gets the current time within a single oscillation period.
2. Calculate the angle:
   double angle = AMPLITUDE * Math.sin(2 * Math.PI * time / PERIOD);
   A sine function creates smooth oscillation.
3. Convert to coordinates:
   double x = centerX + PENDULUM_LENGTH * Math.sin(Math.toRadians(angle));
double y = topY + PENDULUM_LENGTH * Math.cos(Math.toRadians(angle));
   Trigonometry is used to determine the precise position of the bob.
4. Update the graphics:
   ball.setLocation(x - ball.getWidth() / 2, y - ball.getHeight() / 2);
string.setStartPoint(centerX, topY);
string.setEndPoint(x, y);
5. Control animation speed:
   pause(10); introduces a short delay for smooth rendering.

The GraphicsProgram Class

The GraphicsProgram class from the ACM library automatically creates a GUI window and a canvas, invokes init() and run(), and provides convenient methods:

• add(GObject obj) / remove(GObject obj)
• getWidth() / getHeight()
• pause(int ms)
• addMouseListeners(), addKeyListeners()
• setSize(width, height), setBackground(Color)

The GLine and GOval Classes

• GLine
  A line between two points:
  • new GLine(x1, y1, x2, y2)
  • setStartPoint(x, y), setEndPoint(x, y)
• GOval
  An oval or circle:
  • new GOval(width, height)
  • setFilled(true/false), setColor(Color)
  • setLocation(x, y)

By extending these classes, you get a fast and simple way to draw and animate in Java applications.