- Sphere Engine overview
- Compilers
- Overview
- API integration
- JavaScript widget
- Problems
- Overview
- API integration
- JavaScript widget
- E-learning platforms
- Problem setter's handbook
- Problems archive
- RESOURCES
- Programming languages
- Submission streams
- Webhooks
- Disk operations
- Multi-file submissions
- Generating images
- Client libraries
- API Changelog
- FAQ
Browse through the Sphere Engine frequently asked questions section and if you will not be able to find the answers you are looking for, feel free to contact us.
Sphere Engine modules
What is the difference between the Compilers and Problems modules?
The Sphere Engine Compilers module is a service that enables remote execution of computer programs and retrieving the results of their execution.
The Sphere Engine Problems module enables the automated verification of solutions to programming problems. It includes a Problems Manager feature for efficient programming problem creation and testing.
Which module should I choose?
If your project only requires running computer programs (e.g. executing sample source code inside a programming course), choose the Compilers module.
If you need to evaluate the programs (e.g. solutions to programming problems inside a recruitment platform), choose the Problems module.
When required, you can use both modules inside your application.
More information about the differences between the modules can be found in this comparative table.
What is the Sphere Engine Compilers Widget?
The Sphere Engine Compilers Widget is a method of integrating the Compilers module through a JavaScript widget embedded on a website.
What is the Sphere Engine Problems Widget?
The Sphere Engine Problems Widget is a method of integrating the Problems module through a JavaScript widget embedded on a website.
What is Sphere Engine for Education?
Sphere Engine for Education (or Problems LTI tool) is a method of integrating the Problems module with LMS systems using the LTI standard.
Are there any sample programming problems in the Sphere Engine Problems module?
Yes - the Problems section of the Problems Manager available after logging in to the Sphere Engine client panel
(Menu > Problems > Editor) allows you to filter the problems list by pressing the Shared problems button.
The displayed list contains sample programming problems that can be used inside your system right away or for testing purposes.
Integration
Is my system compatible with the Sphere Engine API?
How does integration with the Sphere Engine service work?
All modules support integration with either of the two independent methods:
-
Widget integration - a quick and easy method of integration, recommended for the extension of existing projects,
-
RESTful API - a highly configurable way of integration, recommended for building dedicated applications from scratch.
Sphere Engine Problems module additionally supports LMS integration through an LTI tool.
Which API version should I use?
Please use version 4 of our APIs, which is the latest one. We have moved from API Version 3 to API Version 4 in 2018 (full list of changes).
How do I use Sphere Engine offline or as an on-premise solution?
Yes - if you are interested in an independent instance of the Sphere Engine system running on your servers, please contact us.
Which Learning Management Systems (LMS) does Sphere Engine Problems support?
Sphere Engine Problems is compatible with all LMS systems that support the LTI standard, including Canvas, Moodle, Blackboard, Schoology.
If you are not sure if your system is compatible with Sphere Engine Problems, please contact us.
How do I integrate with Sphere Engine without much interference in the existing system?
Yes - integration using the web widget is limited to adding short snippets of HTML and JavaScript code.
Find out more in the following articles:
How do I share the access to the API with the development team without giving away the access data to the Sphere Engine account?
Yes - access to the Sphere Engine API is implemented using access tokens.
After logging in to the Sphere Engine client panel,
the tokens management section (Menu > API Tokens)
allows you to generate any number of access tokens that can be passed to your development team.
How do I remove the Sphere Engine logo displayed in the widget?
Yes - to delete the Sphere Engine logos, please contact us.
How do I use Sphere Engine API methods directly from the front-end of my web application?
While it may be tempting to integrate with the API in such a way, there are at least two reasons for not doing so:
- CORS and the Same-origin policy limitations
- security violation by revealing the API access token that should remain secret
CORS mechanism enables the communication between two mutually trusted servers hosted
on different domains. The server which handles cross-origin requests (in our
scenario it is the Sphere Engine API) should send a proper HTTP header (i.e.,
Access-Control-Allow-Origin) allowing the request to be handled. Sphere Engine
API denies this kind of requests for security reasons.
The mechanism of the API access tokens is the only method of API call authorization. Revealing the access token that is connected to your account will enable everyone to use Sphere Engine API on your credit. Access tokens should remain secret and if they leak out, they should be changed immediately. More precisely: compromised access tokens should be disabled in the proper panel where you can also generate fresh access tokens.
We recommend designing your web applications in such a way that they make Sphere Engine API calls in the back-end. If the front-end layer of your application requires asynchronous communication, please consider creating a custom layer designated to handling the Sphere Engine API (i.e. asynchronous calls should target your back-end application and then your back-end makes the Sphere Engine API call; then pass the response back in the opposite direction).
I experienced Cross-Origin Request Blocked error when trying to use Sphere Engine API, what happened?
Most likely you are trying to make an API call directly from the front-end of your web application. This is not possible due to the Same-origin policy. Please refer to the Can I use Sphere Engine API methods directly from the front-end of my web application? question to learn more.
Sphere Engine features
What programming languages does Sphere Engine support?
Sphere Engine supports the majority of popular programming languages, including C++, C#, Go, Haskell, Java, Kotlin, Node.js, PHP, Python, Ruby, Scala or Swift.
A separate part of the documentation contains a complete list of supported languages.
Can my Sphere Engine program operate on files and directories?
Yes - Sphere Engine allows you to perform disk operations within an isolated workspace dedicated to a single submission. Find out more about performing disk operations from the disk operations article.
Which data streams and for what purpose are used when processing the submission inside Sphere Engine?
During execution, the program has access to standard data streams. Find out more from the submission streams article.
Can I connect my Sphere Engine program to the Internet?
By default, the executed program does not have Internet access. However, it can be enabled for subscribed users.
How long does it take to run a program in the Sphere Engine system?
Multiple factors affect the program's execution time, for example:
- the programming language,
- the complexity of the program,
- the size of input data,
- time limits,
- the number of test cases (only Sphere Engine Problems).
A typical submission is executed within a few seconds. Long execution times are typically associated with the complexity of the program, not with the Sphere Engine infrastructure.
What happens to my Sphere Engine submission when there is temporarily no computing power at the moment of sending it?
There is nothing to worry about. Each correctly sent submission is stored in a database. If there are no free resources to execute the submission immediately, it waits in the submission queue. You do not need to implement a queue of submissions in your system - Sphere Engine handles that for you.
How do I execute a program consisting of multiple files?
Yes - using integration through RESTful API it is possible to run multi-file projects.
Is it possible to provide support for a new programming language or an additional library in Sphere Engine?
We regularly expand the library of supported programming languages and libraries, very often at our clients' requests. Please contact us if you feel that this is what you need.
Is it possible to expand the Sphere Engine system with additional features?
We regularly expand the capabilities of Sphere Engine, very often at our clients' requests. Please contact us if you feel that this is what you need.
Is Sphere Engine a platform where I can organize a programmer's recruitment, contests or hackathons?
The Sphere Engine Problems module provides all the tools required to create your online competition or recruitment platform for programmers, but it is not designed to support such an event itself.
For running online contests and hackathons, please try using our Spoj (Sphere Engine Online Judge) platform.
Sphere Engine limitations
What is the limit of submissions (programs) sent to Sphere Engine?
The limit of the number of submissions depends on the method of integration (JavaScript widget or RESTful API) and the type of subscription.
What is the program execution time limit?
In the case of the Compilers module, the limitation for the program execution time depends on the configuration and can range from 1 to 15 seconds.
In the Problems module, the program execution time limit results from the test case parameters and can also range from 1 to 60 seconds.
Note: The limit value for execution time applies only to the actual time it takes to run the program. Each time the submission is executed, many routine operations are performed (e.g. program compilation and preparation of the runtime environment), which affect the total time required to run the submission. These are not taken into account in the program's execution time limit.
What is the limit of the number of test cases in a single programming problem in the Sphere Engine Problems module?
The default maximum number of test cases is 16. If the test case construction is correct, this number should be sufficient. Please refer to the “Good test case design article” from the Problem setter's handbook which explains how to create correct and valuable test cases for problems.
It is also possible to increase the maximum number of test cases - please contact us if you feel that this is what you need.
What is the size limit of the source code submitted to Sphere Engine?
The maximum size of uploaded source files as part of a single submission is:
- 64kB for the Sphere Engine Compilers module,
- 32kB for the Sphere Engine Problems module.
Additionally, in the case of integration through Sphere Engine Problems Widget or LTI tool, the restriction can be modified by the author of the problem.
What is the size limit of input data in Sphere Engine Compilers?
The maximum size of the input data file in the Sphere Engine Compilers service is 64kB.
What is the size limit of the data streams generated when executing the submission?
Data generated when executing submissions (i.e., the "stdout", "stderr" streams) can have any size (OS limitations may apply). However, Sphere Engine saves only a shortened data stream of the maximum allowed stream size.
For the Sphere Engine Compilers module, the maximum stream size is 1MB for both streams.
For the Sphere Engine Problems module, the maximum stream size (per test case) is:
- 5kB for "stdout" stream,
- 1kB for "stderr" stream.
Note: The verification procedure conducted during the evaluation of the user's submission uses complete stream data.
What is the size limit for test case files (e.g., input data and reference output data)?
Each file with test case data can weigh up to 20MB. It is also possible to increase the maximum size of test case files - please contact us if you feel that this is what you need.
What is the operational memory (RAM) limit for running the program in Sphere Engine?
The program launched in Sphere Engine has access to 1.5GB of RAM. If this limit is exceeded, the execution of the program is interrupted.
In case of integration through the API, the Sphere Engine Compilers module offers the ability to set the memory limit.
Is there a limit on the number of programming problems that I can create as part of the Sphere Engine Problems module?
The standard limit is up to 1000 problems, however, it is possible to remove the limit of the number of problems. Please contact us if you feel that this is what you need.
Executing submissions
What happens after I send my submission?
After sending the submission it lands in a queue and waits to be executed by the checker server (i.e. the server responsible for executing the programs).
Then the checker server processes the submission by going through the following steps:
- (for compiled languages e.g. C++) the program is compiled,
- the program is executed (many times in case of Problems module - independently for each test case),
- the results of execution after each test case are verified by the “test case judge” (only the Problems module),
- the results of executing all test cases are summarized by the “master judge” (only the Problems module).
After processing the submission, Sphere Engine provides the results of the execution (including execution time, memory usage, data streams).
Note: The status of the submission is being updated in real-time during execution.
Why doesn't a submission sent to the Sphere Engine Problems receive the maximum number of points?
There are many reasons why a seemingly correct solution may not get the maximum points.
First, it is worth verifying the following aspects of the solution:
- the correctness of handling edge cases,
- program's performance for large input data,
- the correctness of the program for atypical input data,
- the correctness of the program for input data realizing maximum ranges for variables occurring in input data.
Why the submission sent to Sphere Engine does not execute correctly?
There are many reasons why a program sent to Sphere Engine does not run correctly.
After executing the submission, information that can help identify the right reason is available in:
- the status of the submission (e.g. "compilation error", "run-time error", "wrong answer"),
- the content of data streams (e.g. compilation errors and run-time errors).
Why do I receive a compilation error indicating a lack of function/module/class/procedure?
Some code written in the languages supported by Sphere Engine requires specific naming or structure. For example, a Java application should contain a public class named Main (or a private class named as you desire).
Familiarizing yourself with sample source code files for the selected programming language (available in the public GitHub repository with common configuration for programming languages) may be useful in identifying the reason for the error.
Why does the processing of submission inside Sphere Engine finish with the "Compilation Error" (CE) status?
Data regarding compilation errors can be found in the stream containing the compilation errors.
Why does the processing of submission inside Sphere Engine finish with the "Time Limit Exceeded" (TLE) status?
If the program has been running for too long (i.e. longer than the execution time limit), its execution was interrupted by the system. In this situation, the submission (or a single test case in case of the Problems module) receives the TLE status.
Examples of reasons why a program might be executing for a long time:
- the occurrence of infinite loops,
- the high computational complexity of the algorithm used in the program,
- a large amount of data processed by the program.
Why does the processing of a submission inside Sphere Engine finish with the "Wrong Answer" (WA) status?
The most common reason is an error in solving the problem. First of all, check the correctness of handling edge cases and tricky, rare or specific data. Next, it is recommended to read the description of the problem again, to make sure that the answer is correct.
Why does the processing of submission inside Sphere Engine finish with the "Runtime Error" (RE) status?
Other
How does the Problems module verify the correctness of a submission?
The most important components of a programming problem are its test cases. Test cases consist of input data and reference output data. The submitted program is executed with the input data of the test case and then the output data it generates is compared to the reference output data.
A detailed description of processing submissions in the Problems module is described in the Submission flow chapter of the Problem setter's handbook.
How is the score of a solution to a programming problem determined in the Problems module?
For each test case, the “test case judge” sets a partial score. Then, after running the program for all test cases, the “master judge” summarizes the partial results and determines the final result.
Both the “test case judge” and the “master judge” operate in a way designed by the author.
Note: Both “test case judges” and “master judges”, are built-in components of Sphere Engine. Usually, the use of these built-in judges is sufficient, i.e. the implementation of your judging programs is not required.
Example
Master judge “Score is % of correctly solved sets” gives a score proportional to the number of correctly solved test cases. For a problem with five test cases, a user's submission that correctly solves three test cases will receive a final result of 60, which should be interpreted as 60% (3 out of 5 = 60%).
How long are the submissions and execution results stored on the Sphere Engine servers?
All data concerning the submission (e.g. the source code, data streams) is stored on the Sphere Engine servers for one month. Please contact us if you would like to store your data for a longer period.