Our failing run, from the Linux lab on 11 Nov 2026 with the official 5.0.0 jar (F17):
java -jar logisim-evolution-5.0.0-all.jar -w main vectors/full-adder-fail.txt circuits/full-adder-v5.circ
Output: Loading test vector “vectors/full-adder-fail.txt”…
Output: Running 8 vectors…
Output: 1 2 3 4 5 6 7 8
Output: Error on test vector 8:
Output: S = 1 (expected 0)
Output:
Output: Passed: 7, Failed: 1
echo $?
0
The same exit code 0 appeared on Linux, GitHub-hosted Windows Server 2025, Windows 11 ARM64, and macOS 15 on Apple Silicon and Intel. These are the systems we could reach, not every machine a course uses. Re-check it after each release.
How to test a circuit in Logisim: run a test vector in the GUI
Open the circuit
The test runs on the circuit that is current in the project window. Open your
.circfile and select the circuit your vector is written for.Check: The circuit you want to test is in the window.
Open the Test Vector window
Choose Simulate, Test Vector…. It starts empty and reads “Selection is empty.” (F105).
Check: A small window with Load Vector, Run, Stop, Reset and Close Window.
Load the vector
Press Load Vector and pick your file. The file chooser is filtered to “Logisim-evolution Test Vector (*.txt)”.
Check: A file chooser listing .txt files.
Read the result
Logisim ran every row as soon as we loaded the file. The header shows the counts. A failing row is listed first and its wrong output cell is shaded red.
Check: The header shows Passed and Failed counts.
The Test Vector window: the header reads Passed: 8 Failed: 0. A table has Show and Set buttons per row, a Status column where every row says pass, the columns <set> 0 and <seq> comb, then the pins A, B, Cin, S and Cout with the eight rows of the full adder. Buttons below: Load Vector, Run, Stop, Reset, Close Window.
The Test Vector window with the header Passed: 7 Failed: 1. The first row says fail and its S cell is shaded red with the value 1 while Cin, A, B are all 1; the other seven rows say pass.
Each row has a Show button and a Set button. We did not press them, so we describe nothing about what they do to the canvas. We also did not test hover text on a red cell.
To practise, download the full adder, the passing vector and the failing vector, where row 8 is wrong on purpose. Both vectors are the ones we used for the screenshots above.
The file format
Our passing vector for the full adder. The first line after the comment names the pins; every other line is one test:
# full adder, all 8 rows (logisim.dev lab)
A B Cin S Cout
0 0 0 0 0
0 0 1 1 0
0 1 0 1 0
0 1 1 0 1
1 0 0 1 0
1 0 1 0 1
1 1 0 0 1
1 1 1 1 1| Comments | A line starting with # is ignored. Our file above has one and passed 8 of 8. | Tested (F17 run) |
|---|---|---|
| Header line | One name per column, the same as the pin labels, including capitals. s does not match a pin labelled S: the run stops with “Column S has no matching pin”. A trailing space in the label did not matter. | Tested (F38, F102) |
| Multi-bit pins | Write the width in brackets, for example Q[4]. A one-bit column against a two-bit pin stops with “Column S has width 1 but pin has width 2”. | Tested (F102) |
| Hexadecimal | Start with 0x, for example 0xF. A capital 0X was rejected. | Tested (F38) |
| Decimal | The value must fit the column as a signed number: 15 in a 4-bit column was rejected (“Too many bits”). | Tested (F38) |
| Binary | Digits equal to the width, for example 0101 in a 4-bit column. | Used in our vectors; wrong-length case not tested |
| Don't care | <DC> in an output column accepts any value, at any width. A bare x is only a per-bit don't care inside a binary value, and on an 8-bit column it is rejected. | Tested (F72, F104) |
| Floating | <float> as an expected output means the pin must be floating. Our buffer row with the buffer off passed with <float> and failed with an expected 0 (“Y = U (expected 0)”). | Tested (F104) |
| Extra or missing values | One value too many on a row is rejected (“too many values”). | Tested (F38) |
| Underscores in numbers | Not tested here. | Not tested |
No rows match.
Not sure about your file? Build and check your vector in the browser.
Sequential circuits: set and seq
By default every row is its own test: Logisim resets the circuit before each row. A flip-flop therefore forgets its state between rows. Our 14-row flip-flop vector passed only 3 rows that way, and all 14 once we added the two extra columns (F65).
Add the columns <set> and <seq> at the end of the header. Rows with the same <set> number belong together and run in <seq> order with no reset between them. The first step of a set starts from a reset; each later step starts with one simulation tick. A row with <set> 0 and <seq> 1 is rejected (F38). The upstream guide inside the jar describes the same rule.
Our 4-bit counter vector gives the clock as an input pin called CLK, one row for the low half and one for the high half of each cycle:
CLK Q[4] <set> <seq>
0 0x0 1 1
1 0x1 1 2
0 0x1 1 3
1 0x2 1 4
0 0x2 1 5
1 0x3 1 6Show values as a table
| step | CLK | Q |
|---|---|---|
| 0 | 0 | 0 |
| 1 | 1 | 1 |
| 2 | 0 | 1 |
| 3 | 1 | 2 |
| 4 | 0 | 2 |
| 5 | 1 | 3 |
The Test Vector window for the counter vector with the header Passed: 41 Failed: 0, scrolled to the last rows. Columns: Show, Set, Status, <set> 1, <seq> from 27 to 41, CLK alternating 1 and 0, and Q in hex counting d, e, f, 0, 1, 2, 3, 4.
All 41 steps passed in the GUI and on the command line. Download the counter and its vector.
A Clock component works too, but then there is no CLK column: the vector lists only outputs, and each step after the first moves the clock by half a cycle. A 6-step vector with outputs 0x0 0x1 0x1 0x2 0x2 0x3 passed on a counter with a Clock component, and a CLK column on it was rejected (F104). We published the input-pin version because the vector then states the clock value on every row.
Classic Logisim 2.7.1 has no test vectors: its -help lists no such option and its jar holds no test vector class (F106). See the classic 2.7.1 guide.
Floating and don’t-care outputs
Our controlled buffer passes input A when E is 1 and leaves Y floating when E is 0. The vector uses <float> for the floating rows and <DC> for a row where we accept anything:
# controlled buffer: E=1 passes A, E=0 leaves Y floating
A E Y
0 1 0
1 1 1
0 0 <float>
1 0 <float>
1 0 <DC>Download the buffer circuit and its vector. All five rows passed (F104).
Generate a vector from a log
Two Logisim windows write tables you can start from: the timing diagram window and Combinational Analysis. Neither writes a file that is guaranteed to load as a vector, so run the result through the checker before you rely on it.
Run test vectors from the command line
The option is -w or --test-vector, followed by the circuit name, the vector file and the circuit file (F01). The installed launchers accept command-line options too (F28, tested with –version and –tty); for a grader we recommend the jar, because the command is the same on every system.
On Windows
java -jar logisim-evolution-5.0.0-all.jar --no-splash --test-vector main full-adder.txt full-adder.circ
On macOS
java -jar logisim-evolution-5.0.0-all.jar --no-splash --test-vector main full-adder.txt full-adder.circ
On Linux
java -jar logisim-evolution-5.0.0-all.jar --no-splash --test-vector main full-adder.txt full-adder.circ
On a server with no display, put xvfb-run -a in front of java.
The output is a line for each loaded vector file, one progress number per row, an “Error on test vector N:” block for each failure naming the pin, the actual value and the expected value, and a last line Passed: N, Failed: M.
| Vector passes | Passed: 8, Failed: 0 | 0 | F17, F92 |
|---|---|---|---|
| Vector fails | Error on test vector 8: then Passed: 7, Failed: 1 | 0 | F17, F92 |
| Header name or width does not match | Error preparing test vector: Column S has no matching pin | 0 | F102 |
| Circuit name not in the file | Circuit 'nosuch' not found. | 0 | F92, F102 |
| Circuit file missing | an ERROR line from Startup | 255 | F92, F102 |
| Classic 2.7.1 file, empty file, damaged file, unknown library | nothing: a dialog waits for a click | none (hangs) | F102 |
| No display | java.awt.HeadlessException | 1 | F18 |
| <code>-b</code> test bench, pass | Test bench pass | 0, from the code in the jar; not run | F103 |
| <code>-b</code> test bench, fail | Test bench fail | 255 (-1), from the code in the jar; not run | F103 |
No rows match.
The -b or --test-circuit option is a different feature: it looks for a circuit named logisim_test_verif with output pins test_bench_done_o and test_bench_ok_o and waits for both to be 1. We built four such files and none of them finished on our lab machine: a folder chooser for a simulator path stayed open (F103). We therefore do not recommend it for grading, and the two exit codes above come from reading the jar, not from a run. The older option name -testvector is not in the 5.0.0 help.
A folder chooser with Look In set to root, an empty list, Folder name /root, Files of Type All Files, and the buttons Select and Cancel.
Autograder recipe
We ran 30 student-style variants of the full adder through this recipe (F102). The recipe gave the right verdict on every one. Steps:
Put Java 21 and the jar in the image
Use the jar from the download page. Pin the version your course uses (which version). On Ubuntu or Debian the installer package also works, see Linux install.
Check: java -version prints 21.
Install Xvfb
–test-vectorneeds a display, so wrap it inxvfb-run -a.Check: xvfb-run is on the PATH.
Run each submission with a time limit
Five of our 30 files opened a modal dialog and would have waited forever. A limit of 30 seconds was far above the 1 second a normal run took.
Check: A file that opens a dialog is killed, not waited for.
Decide from the text
Pass needs: a line
Passed: N, Failed: 0; N equal to the number of rows in the vector; no word “Exception” in the output. Everything else is a fail. Never use the exit code.Check: Pass only when every condition holds.
Check the pin types of any suspicious pass
An output pin changed to an input passed 8 of 8 in our run. If you grade strictly, also parse the submitted
.circand confirm the pin directions (the .circ viewer lists them).Check: Output columns are output pins.
The recipe as one script, the same file as the download:
#!/usr/bin/env bash
# Usage: autograde-logisim.sh <jar> <circuit-name> <vector.txt> <circuit.circ> [timeout-seconds]
jar=$1; circuit=$2; vector=$3; file=$4; limit=${5:-30}
expected=$(grep -Ev '^[[:space:]]*(#|$)' "$vector" | tail -n +2 | wc -l)
out=$(timeout -k 5 "$limit" xvfb-run -a java -jar "$jar" --no-splash -w "$circuit" "$vector" "$file" 2>&1)
code=$?
[ "$code" -eq 124 ] || [ "$code" -eq 137 ] && { echo "FAIL timeout after ${limit}s"; exit 1; }
summary=$(printf '%s\n' "$out" | grep -E '^Passed: [0-9]+, Failed: [0-9]+' | tail -n 1)
[ -z "$summary" ] && { echo "FAIL no summary line (exit $code)"; exit 1; }
passed=${summary#Passed: }; passed=${passed%%,*}; failed=${summary##*Failed: }
printf '%s\n' "$out" | grep -q 'Exception' && { echo "FAIL exception in output"; exit 1; }
[ "$failed" -ne 0 ] && { echo "FAIL $summary"; exit 1; }
[ "$passed" -ne "$expected" ] && { echo "FAIL passed $passed rows, vector has $expected"; exit 1; }
echo "PASS $summary"; exit 0Download autograde-logisim.sh. Gradescope and GitHub Actions run the same script inside a container with Java and Xvfb installed; we did not run either service, so we give no service-specific steps.
What our 30 files did, by class:
| Passed 8, Failed 0 | 10 | correct file; extra input or output pin; label with a trailing space; header saying 3.8.0 or 9.9.9; CRLF line endings; byte-order mark; no main attribute; output pin turned into an input |
| Summary with failures | 7 | wrong gate (two files); outputs swapped; output or input unconnected; a constant fighting an output; a ring of three inverters |
| No summary line, exit 0 or 255 | 8 | label <code>s</code> or <code>CIN</code>; missing pin; circuit not named <code>main</code> (two files); a 2-bit output pin; main circuit with no pins; file missing |
| Hangs on a dialog | 5 | classic 2.7.1 format file; empty file; plain text; truncated XML; unknown built-in library |
No rows match.
A modal error dialog on a grey background with a red X and the text "16-empty-file: XML formatting error: org.xml.sax.SAXParseException; lineNumber: 1" and the buttons Copy error and OK.
A warning dialog: You are opening a file created with original Logisim code. You might encounter some problems in the execution, since some components evolved since then. Moreover, labels will be converted to match VHDL limitations for variable names. One OK button.
Not covered by our run: a file saved by 4.1.0, a design that cheats with a lookup table, and a circuit that makes the simulator hang. For a comparison without a display, --tty table prints the whole truth table of a combinational circuit and works headless; see the command-line reference. More on running a course: teachers and courses.
Checklist before you submit
Related pages: the full adder project has its own vectors, and subcircuits explains setting the main circuit.